API de Integração v1

Documentação restrita (NDA)

A API de integração do ACCELERO é disponibilizada apenas mediante assinatura de NDA. Este conteúdo é de uso interno/restrito e não deve ser publicado no portal público nem compartilhado sem o acordo de confidencialidade correspondente.

A API de Integração v1 é a API REST do ACCELERO para sistemas externos. Com ela, o sistema do cliente cadastra pessoas, cria visitas (grants), acompanha o status do visitante, obtém o QR code de acesso e consulta eventos de acesso, operações e lotação de áreas.

A API cresce conforme a demanda dos clientes: cada nova necessidade vira uma rota nova no plugin.

Disponibilidade

Este recurso é disponibilizado como plugin (apiv1) e precisa ser instalado e habilitado pela equipe técnica da IONGRADE.

Compatibilidade

Versão atual do plugin: 1.2.0, compatível com ACCELERO 2.17.0, 2.17.1 e 2.17.2.

---

Rotas

Recurso	Método e rota	O que faz
Cadastrar pessoa	POST /api/1/people	Cria ou atualiza a pessoa. O documento é a chave
Desabilitar pessoa	DELETE /api/1/people/{id}	Desabilita a pessoa, sem apagar nada
Listar categorias	GET /api/1/categories	Categorias de pessoa cadastradas
Criar visita	POST /api/1/event	Cria a visita (grant) ligando visitante e anfitrião
Consultar visita	GET /api/1/event/{id}	Estado atual da visita e do visitante
Alterar status do visitante	POST /api/1/event/{id}/status	Autoriza ou devolve o visitante para check-in
QR code da visita	GET /api/1/event/{id}/qrcode	QR code de acesso do visitante
Cancelar visita	DELETE /api/1/event/{id}	Cancela a visita
Listar tipos de evento	GET /api/1/event/types	Tipos de evento cadastrados
Pesquisar eventos de acesso	GET /api/1/events/search	Entradas e saídas por período e categoria
Log de operações	GET /api/1/operations	Auditoria de inserções, alterações, exclusões e logins
Lotação de áreas	GET /api/1/occupancy	Ocupação, capacidade e vagas de cada área

---

Convenções gerais

Aspecto	Valor
URL base	A URL do ambiente ACCELERO do cliente (ex.: https://accelero.suaempresa.com)
Formato	JSON, UTF-8 (Content-Type: application/json)
Data	YYYY-MM-DD (ex.: 2026-09-24)
Data e hora	YYYY-MM-DD HH:MM:SS (ex.: 2026-09-24 08:00:00)
Resposta de sucesso	O JSON do recurso (objeto ou lista), sem envelope
Resposta de erro	{"success": false, "error": "mensagem"}

---

Autenticação

Todas as requisições exigem uma chave de API no header Authorization:

Authorization: Bearer SUA_CHAVE

A chave pertence a um operador do ACCELERO. A requisição roda com as permissões desse operador: criar e editar pessoa, criar e editar evento, listar evento, listar categorias. Sem a permissão exigida, a API responde 401 Not authorized.

Gerar a chave

A chave é gerada nas configurações do operador que vai representar a integração: abra a edição desse operador e vá até a aba API Keys.

1. Clique em Nova API Key.
2. Digite o código de confirmação exibido na tela.
3. Copie as duas chaves apresentadas: Chave pública e Chave secreta.

A chave secreta aparece uma única vez

Depois de fechar a tela, a chave secreta não é exibida de novo. Se ela se perder, exclua a chave e gere outra.

Use a Chave pública no header Authorization. A API v1 identifica a chamada pela chave pública; a chave secreta não é usada por ela. Enviar a secreta resulta em 401 Invalid API key.

A aba API Keys só aparece quando a licença tem o módulo API de integração. Detalhes da tela em Operadores.

Guarde a chave com segurança

Apesar do nome, a chave pública é a credencial da API v1: quem a tem acessa os dados do ACCELERO com as permissões do operador associado. Trate-a como uma senha. Recomende ao cliente um operador dedicado para a integração, só com as permissões necessárias.

curl -X GET https://accelero.suaempresa.com/api/1/occupancy \
  -H "Authorization: Bearer SUA_CHAVE"

---

Fluxo típico de integração com visitas

1. Cadastrar o visitante com POST /api/1/people (opcional: a criação da visita também cadastra o visitante pelo CPF).
2. Criar a visita com POST /api/1/event e guardar o event_id da resposta.
3. Obter o QR code com GET /api/1/event/{id}/qrcode e entregar ao visitante.
4. Acompanhar a visita com GET /api/1/event/{id} (check-in, autorização, entrada, saída).
5. Autorizar, quando o tipo de evento exige aprovação, com POST /api/1/event/{id}/status.
6. Cancelar, se necessário, com DELETE /api/1/event/{id}.

O QR pode ser obtido logo após criar a visita. Ele não muda com o status: na catraca, o ACCELERO aplica o status daquele momento. O mesmo QR é negado antes do check-in ou da autorização e passa depois.

---

Status do visitante

O status inicial do visitante segue o Status padrão para visitas configurado no tipo de evento e, quando existir, o status configurado na empresa visitada.

Código	Status na tela	Descrição na API	Catraca comum
1	Pré-cadastrada	awaiting_checkin	Nega
98	Check-in, pendente autorização	awaiting_authorization	Nega
2	Autorizada	authorized	Libera
3	Em andamento	started	Libera
9	Finalizada	ended	Nega
99	Cancelada	cancelled	Nega

No canal de check-in, o status 1 passa para 98. A primeira passagem pela catraca leva o status para 3, e a saída com baixa de visita, para 9.

---

Pessoas: cadastrar ou atualizar

Endpoint: POST /api/1/people

Cria ou atualiza a pessoa. O documento é a chave: se já existe uma pessoa com o mesmo documento (a pontuação é ignorada na busca), ela é atualizada; senão, é criada. Exige a permissão de criar pessoa (pessoa nova) ou editar pessoa (pessoa existente).

{
  "document": "123.456.789-09",
  "document_type": "cpf",
  "name": "Maria Silva",
  "email": "maria@exemplo.com",
  "phone": "11999999999",
  "code": "MAT-001",
  "photo": "<base64 ou data URI>",
  "enabled": true,
  "companies": [{ "id": 3, "association_type": 1, "pre_authorized": true, "authorizer": false }],
  "categories": [2]
}

Campo	Obrigatório	Regra
document	Sim	Chave do cadastro (até 50 caracteres)
name	Sim	3 a 50 caracteres
document_type	Não	cpf, rg, cnh, passport, foreign ou outros. Com cpf, o dígito verificador é validado
email	Não	Até 100 caracteres
phone	Não	Telefone
code	Não	Código (matrícula), até 20 caracteres. Único no ACCELERO
photo	Não	Foto em base64 ou data URI
enabled	Não	Pessoa nova nasce habilitada quando omitido
companies	Não	Empresas (id), com tipo de vínculo (association_type), pre_authorized (padrão true) e authorizer (padrão false)
categories	Não	IDs de categorias

Regras de atualização:

• Só os campos enviados mudam. Campo ausente mantém o valor atual.
• Empresas e categorias são apenas adicionadas, nunca removidas. Reenviar a mesma não duplica.
• Empresas, categorias e tipos de vínculo são conferidos antes de gravar. Um ID inexistente responde 404, e a pessoa não é criada nem alterada.
• O documento não muda por esta rota, porque é a chave. A troca de documento é feita pela interface.

Documento e código são únicos

O ACCELERO não aceita duas pessoas com o mesmo documento ou o mesmo código. Se o code enviado já pertence a outra pessoa, a API responde 409 Code already in use by another person e nada é gravado.

Resposta:

{ "success": true, "person_id": 1806777654, "created": true }

created é true quando a pessoa foi criada nesta chamada e false quando foi atualizada.

Pessoas: desabilitar

Endpoint: DELETE /api/1/people/{id}

Desabilita a pessoa identificada pelo person_id. Nada é apagado: vínculos, identificadores e histórico são mantidos. Para reabilitar, envie POST /api/1/people com enabled: true. Exige a permissão de editar pessoa.

---

Visitas: criar

Endpoint: POST /api/1/event

Cria a visita (grant), ligando um visitante a um anfitrião já cadastrado. Exige a permissão de criar evento.

{
  "visitor": { "id": "ext-123", "name": "Carlos Souza", "cpf": "52998224725", "email": "carlos@exemplo.com" },
  "host": { "cpf": "70000053945", "unit": "1244281355" },
  "event": { "start": "2026-09-24 08:00:00", "end": "2026-09-24 18:00:00", "type": 1, "handler": "sistema-cliente" },
  "webhook": { "onStart": "https://cliente/entrou", "onEnd": "https://cliente/saiu" }
}

Bloco	Campo	Obrigatório	Descrição
visitor	id	Sim	Identificador do visitante no sistema do cliente
visitor	name	Sim	Nome (3 a 50 caracteres)
visitor	cpf	Sim	CPF. O visitante é localizado por ele e cadastrado se não existir
visitor	email / phone / photo / extra	Não	E-mail (até 50), telefone, foto em base64, dados adicionais (até 500)
host	cpf	Sim	CPF do anfitrião, que precisa existir e estar ligado a uma empresa
host	unit	Não	ID da empresa do anfitrião. Sem ele, usa a primeira empresa vinculada
event	start / end	Sim	Início e fim da visita
event	type	Sim	ID do tipo de evento (Listar tipos de evento)
event	handler	Sim	Identificador do sistema de origem
event	status	Não	Força o status inicial do visitante: 1, 2, 3 ou 98
webhook	onStart / onEnd	Não	URLs chamadas na entrada e na saída com baixa de visita

Status inicial do visitante, na ordem (mesma regra do ACCELERO e do Accelero Visitas):

1. event.status, se enviado;
2. o status configurado na empresa visitada;
3. o Status padrão para visitas do tipo de evento;
4. Autorizada (2).

Os significados estão em Status do visitante.

Resposta:

{ "success": true, "event_id": "1698371166", "localizador": "0XR-Z5J3", "visitor_status": 2, "need_checkin": false }

• event_id: identifica a visita em todas as outras rotas. Vem como texto, por compatibilidade com versões anteriores.
• need_checkin: true quando o visitante nasceu Pré-cadastrado e precisa passar pelo check-in.

Webhooks

Os webhooks são chamados com GET, sem corpo, na entrada (onStart) e na saída com baixa de visita (onEnd). O ACCELERO espera HTTP 201. Com outra resposta, tenta de novo até 3 vezes, a cada 5 segundos. O check-in não gera webhook: para acompanhá-lo, use a consulta da visita.

Visitas: consultar

Endpoint: GET /api/1/event/{id}

Estado atual da visita. Exige a permissão de listar evento.

{
  "event_id": 1698371166,
  "type": { "id": 1, "description": "Visita" },
  "unit": 1244281355,
  "start": "2026-09-24 08:00:00",
  "end": "2026-09-24 18:00:00",
  "status": { "id": 1, "description": "registered" },
  "visitor": {
    "person_id": 1806777654,
    "name": "Carlos Souza",
    "document": "52998224725",
    "localizador": "0XR-Z5J3",
    "status": { "id": 2, "description": "authorized" }
  },
  "need_checkin": false,
  "has_qrcode": true
}

Campo	Conteúdo
status	Status do evento: registered, started, finished ou cancelled
visitor.status	Status do visitante (ver Status do visitante)
has_qrcode	Se o QR code já foi gerado para a visita

Visitas: alterar status do visitante

Endpoint: POST /api/1/event/{id}/status

Equivale ao update-status do Accelero Visitas. Uso típico: autorizar o visitante que fez check-in. Exige a permissão de editar evento.

{ "status": 2 }

• Aceita 1 (Pré-cadastrada), 98 (Check-in, pendente autorização) e 2 (Autorizada).
• Só altera enquanto o status atual também for um desses, ou seja, antes da entrada. Depois da primeira passagem, responde 400 Visit already started or ended.
• Visita cancelada ou finalizada responde 400. Para cancelar, use o DELETE.

Visitas: QR code de acesso

Endpoint: GET /api/1/event/{id}/qrcode

Devolve o QR code de acesso do visitante. Exige a permissão de listar evento.

{
  "event_id": 1698371166,
  "qrcode": "data:image/png;base64,iVBORw0KGgo...",
  "valid_from": "2026-09-24 08:00:00",
  "valid_until": "2026-09-24 18:00:00"
}

• O que é: uma credencial do tipo QRCode da pessoa, válida do dia de início ao dia de fim da visita. O modelo é o mesmo do Accelero Visitas.
• Primeira chamada: gera o QR. As seguintes devolvem o mesmo QR enquanto ele for válido.
• Na catraca: o ACCELERO encontra a visita vigente do visitante e aplica o status dela naquele momento.
• Fora da visita: visita cancelada, ainda não iniciada no mesmo dia ou já encerrada deixa o QR valendo só pelas regras de acesso da própria pessoa. Para um visitante sem categoria ou permissão própria, isso significa acesso negado.
• Recusa: visita cancelada ou finalizada responde 400.

Visitante sem permissões próprias

Como o QR é uma credencial da pessoa, ele só fica restrito à janela da visita se o visitante não tiver permissão de acesso própria (categoria, áreas ou empresa que já liberem a passagem). Confira o cadastro padrão de visitantes do cliente.

Visitas: cancelar

Endpoint: DELETE /api/1/event/{id}

Cancela o evento e o vínculo do visitante. O QR deixa de valer para esta visita. Exige a permissão de editar evento. Responde {"success": true}, ou 404 Unknown id se a visita não existir.

Visitas: listar tipos de evento

Endpoint: GET /api/1/event/types

Lista os tipos de evento (id e description), para preencher event.type.

[{ "id": "1", "description": "Visita" }]

---

Consulta: pesquisa de eventos de acesso

Endpoint: GET /api/1/events/search

Entradas e saídas de pessoas por período e, opcionalmente, por categoria. Exige a permissão de listar o log de eventos.

Campo	Descrição
filters.date_start / filters.date_end	Período (YYYY-MM-DD). Obrigatórios, com no máximo 61 dias entre eles
filters.categories	IDs de categorias de pessoa
sort	Campo date. Prefixo - para ordem decrescente
page.number / page.size	Paginação. Sem ela, vêm todos os registros do período

Os filtros podem ir no corpo JSON ou na query string:

GET /api/1/events/search?date_start=2026-09-01&date_end=2026-09-30&sort=-date&page=1&limit=50

Cada item traz id, name, email, document, timestamp, category, area, access_type (enter ou exit, pelo tipo da área) e event_type.

Prefira a query string nas consultas

Corpo em requisição GET só chega à API quando o cliente o envia com Content-Length. Clientes que enviam em chunked (o Newman, por exemplo) têm o corpo descartado, e a API responde 500 com erro vazio. A query string funciona em qualquer cliente.

Data final sem hora

Em events/search, date_end sem hora corta o período à meia-noite do início do dia. Para incluir o dia inteiro, informe a data seguinte ou 2026-09-30 23:59:59.

Consulta: log de operações

Endpoint: GET /api/1/operations

Log de operações para auditoria, com as mesmas regras de período (61 dias, duas datas obrigatórias, filtros no corpo ou na query string).

Filtro	Descrição
filters.logType	1 Atualização, 2 Inserção, 3 Exclusão, 4 Login, 5 Outros, 6 Visualização de dados, 7 Complementar
filters.logObject	Objeto afetado (ex.: Pessoa, Area, Empresa)
sort	date, type ou object

Cada item traz id, type (código numérico do logType), object, key_id, timestamp, user_name e data (JSON da operação).

Permissão

Esta rota não verifica uma permissão específica: qualquer chave válida consulta o log de operações.

Consulta: lotação de áreas

Endpoint: GET /api/1/occupancy

Lotação de todas as áreas: id, description, enabled e occupancy (current, capacity e available, esta nunca negativa). Não aceita filtros.

Consulta: categorias de pessoa

Endpoint: GET /api/1/categories

Lista as categorias (id e description), para os filtros de events/search e o cadastro de pessoas.

---

Códigos de resposta

Código	Quando
200	Sucesso
400	Payload inválido, status não aceito, período acima de 61 dias, visita cancelada ou finalizada
401	Chave ausente ou inválida (Invalid API key), ou usuário sem permissão (Not authorized)
404	Pessoa, visita, anfitrião, empresa, categoria ou tipo de vínculo inexistente
409	Documento ou código já pertence a outra pessoa
500	Erro interno

---

Pré-requisitos no ambiente do cliente

Para o QR code liberar a catraca:

• Serviço de QR code no ar. A imagem é gerada pelo serviço python-qrcode (modules_qrcode.yml). Sem ele, a rota de QR responde 500 Error connecting to QRCode webservice.
• Canal aceitando QRCode. O canal da catraca precisa ter o tipo de identificador QRCode entre os aceitos. Sem isso, a catraca exibe TIPO NAO ACEITO.
• Área liberada para a categoria da visita. A categoria que o tipo de evento atribui ao visitante precisa ter a área de destino liberada. Sem isso, o acesso é negado por área.

---

Recursos para desenvolvedores

O plugin traz, na pasta docs/:

• README.md: guia de integração com todas as rotas.
• openapi.yaml: especificação OpenAPI 3.0 de todas as rotas, para o Swagger Editor ou geração de cliente.
• Accelero_API_v1.postman_collection.json: requisições prontas e encadeadas. Basta preencher base_url, api_key, o anfitrião (host_cpf, host_unit) e os IDs de empresa e categoria; person_id e event_id são salvos a partir das respostas, e cada requisição confere o próprio resultado.

Distribuição

Os artefatos acompanham o plugin. Envie-os ao cliente junto com o NDA durante a implantação da integração.

---

Troubleshooting

401 Invalid API key

Possíveis causas: header Authorization ausente ou fora do formato Bearer <chave>; chave incorreta ou removida.

Solução: confira o header e, se necessário, gere uma nova chave na tela do usuário.

401 Not authorized

Possível causa: o usuário da chave não tem a permissão exigida pela rota.

Solução: ajuste o perfil do usuário da integração.

409 Code already in use by another person

Possível causa: o code enviado já pertence a outra pessoa.

Solução: confira o código no sistema do cliente. Documento e código são únicos no ACCELERO.

O visitante tem QR, mas a catraca nega

Sinal	Causa provável	Solução
Visita com need_checkin: true ou status awaiting_checkin	O tipo de evento exige check-in	Fazer o check-in no canal de check-in, ou autorizar com POST /api/1/event/{id}/status
Status awaiting_authorization	Falta a autorização do anfitrião	Autorizar pela interface ou com POST /api/1/event/{id}/status
Display TIPO NAO ACEITO	O canal não aceita QRCode	Incluir QRCode nos tipos aceitos do canal
Log com "área não permitida"	A categoria da visita não libera a área	Liberar a área na categoria atribuída pelo tipo de evento
Log com "categoria não autorizada"	Não há visita vigente (cancelada, fora do horário)	Conferir datas e status com GET /api/1/event/{id}

404 Unknown host / Unknown unit (ao criar visita)

Possíveis causas: o CPF do anfitrião não existe no ACCELERO; o anfitrião não tem empresa vinculada; ou a unit informada não é uma das empresas dele.

Solução: confira o cadastro do anfitrião e o ID da empresa.

---

Integração com outros módulos

• Pessoas e Categorias: o cadastro de pessoas e as permissões do visitante.
• Empresas: a unidade do anfitrião e o status de visita configurado na empresa.
• Eventos: tipos de evento, check-in e status das visitas.
• Identificadores: o QR code da visita é um identificador do tipo QRCode.
• Áreas: a lotação e as áreas liberadas para a categoria da visita.
• Logs e Monitoramento: a origem da pesquisa de eventos de acesso.