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 oficial do ACCELERO para comunicação com sistemas externos. Ela permite consultar eventos de acesso, auditar operações do sistema, monitorar a lotação das áreas e criar/cancelar eventos de visita programaticamente.

Disponibilidade

Este recurso é disponibilizado como plugin (apiv1) e precisa ser instalado e habilitado pela equipe técnica da IONGRADE. Consulte o suporte para verificar compatibilidade com a sua versão do ACCELERO.

Compatibilidade

Versão atual do plugin: 1.1.0 — compatível com ACCELERO 2.17.0 ou superior.

Esta página documenta especificamente a API v1 do ACCELERO (rotas sob /api/1/...).

O que a API faz

Recurso	Endpoint	O que entrega
Pesquisa de eventos de acesso	`GET /api/1/events/search`	Histórico de entradas e saídas de pessoas, filtrado por período e categorias
Log de operações	`GET /api/1/operations`	Auditoria de operações (inserções, atualizações, exclusões, logins) realizadas no sistema
Lotação de áreas	`GET /api/1/occupancy`	Ocupação atual, capacidade e vagas disponíveis de todas as áreas
Criar evento de visita	`POST /api/1/event`	Cadastra um evento de visita vinculando visitante e anfitrião (host)
Cancelar evento de visita	`DELETE /api/1/event/{id}`	Cancela um evento de visita existente
Listar tipos de evento	`GET /api/1/event/types`	Tipos de evento disponíveis para uso na criação de visitas
Listar categorias de pessoa	`GET /api/1/categories`	Categorias de pessoa cadastradas, para uso como filtro

Convenções gerais

Aspecto	Valor
URL base	A URL do seu ambiente ACCELERO (ex.: `https://accelero.suaempresa.com`)
Formato de request	JSON (`Content-Type: application/json`)
Formato de response	JSON, codificação UTF-8
Formato de data	`YYYY-MM-DD` (ex.: `2025-01-31`)
Formato de data/hora	`YYYY-MM-DD HH:MM:SS` (ex.: `2025-01-31 14:30:00`)

URL base

A URL base é específica do ambiente do cliente. Confirme o endereço de produção com o administrador do ACCELERO antes de integrar.

Autenticação

Todas as requisições exigem um Bearer Token (API Key) no header Authorization:

Authorization: Bearer SEU_TOKEN_AQUI

O token corresponde a uma API Key vinculada a um usuário do ACCELERO. A requisição assume as permissões desse usuário — cada endpoint verifica a permissão correspondente (listar log de eventos, criar evento, listar categorias, etc.) antes de responder. Se o usuário não tiver a permissão necessária, a API retorna 401.

TODO: Adicionar Screenshot

Tela de geração/gestão de API Keys no ACCELERO (cadastro do usuário ou tela de configuração onde a chave é criada e copiada), mostrando onde o token é obtido.

Guarde o token com segurança

A API Key concede acesso aos dados do ACCELERO com as permissões do usuário associado. Trate-a como uma senha: nunca a exponha em código cliente público nem em repositórios.

Exemplo com cURL

curl -X GET https://accelero.suaempresa.com/api/1/occupancy \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json"

Códigos de status e erros

Código	Significado
`200`	Sucesso
`400`	Requisição inválida — payload incorreto ou intervalo de datas excedido
`401`	Não autorizado — token inválido/ausente ou usuário sem permissão
`404`	Entidade não encontrada (ex.: host, unidade ou evento inexistente)
`500`	Erro interno do servidor

As respostas de erro seguem o formato:

{
  "success": false,
  "error": "Mensagem descritiva do erro"
}

Consulta — Pesquisa de eventos de acesso

Endpoint: GET /api/1/events/search

Retorna eventos de entrada e saída de pessoas, filtrados por período e, opcionalmente, por categorias.

Parâmetros (corpo JSON)

Campo	Descrição
`filters.date_start`	Data inicial (`YYYY-MM-DD`) — obrigatória
`filters.date_end`	Data final (`YYYY-MM-DD`) — obrigatória
`filters.categories`	Lista de IDs de categorias de pessoa (opcional)
`sort`	Ordenação. Campo suportado: `date`. Use o prefixo `-` para ordem decrescente (ex.: `["-date"]`)
`page.number`	Número da página
`page.size`	Itens por página

Intervalo máximo de 61 dias

O intervalo entre date_start e date_end não pode exceder 61 dias. Ambas as datas são obrigatórias — requisições fora desse limite retornam 400 com a mensagem Max range date exceeded.

Exemplo de request

{
  "filters": {
    "date_start": "2025-01-01",
    "date_end": "2025-01-31",
    "categories": [1, 2]
  },
  "sort": ["-date"],
  "page": {
    "number": 1,
    "size": 50
  }
}

Campos da resposta

Cada evento retornado contém:

Campo	Conteúdo
`id`	ID do evento de acesso
`name`	Nome da pessoa
`email`	E-mail da pessoa
`document`	Documento (CPF/RG) da pessoa
`timestamp`	Data e hora do evento
`category`	Categoria da pessoa
`area`	Área do acesso
`access_type`	`enter` (entrada) ou `exit` (saída), derivado do tipo da área
`event_type`	Tipo do evento (ex.: forma de acesso)

Exemplo de resposta

[
  {
    "id": 12345,
    "name": "João Silva",
    "email": "joao.silva@email.com",
    "document": "12345678900",
    "timestamp": "2025-01-15 14:30:00",
    "category": "Funcionário",
    "area": "Portaria Principal",
    "access_type": "enter",
    "event_type": "Acesso por cartão"
  }
]

Consulta — Log de operações

Endpoint: GET /api/1/operations

Retorna o log de operações realizadas no sistema (inserções, atualizações, exclusões, logins, etc.), para fins de auditoria.

Parâmetros (corpo JSON)

Campo	Descrição
`filters.date_start`	Data inicial (`YYYY-MM-DD`) — obrigatória
`filters.date_end`	Data final (`YYYY-MM-DD`) — obrigatória
`filters.logType`	Lista de tipos de operação (ver tabela abaixo)
`filters.logObject`	Nome do objeto afetado (ex.: `"Pessoa"`, `"Area"`, `"Empresa"`)
`sort`	Ordenação. Campos suportados: `date`, `type`, `object`. Prefixo `-` para decrescente
`page.number`	Número da página
`page.size`	Itens por página

Tipos de operação (`logType`)

Valor	Tipo
`1`	Atualização
`2`	Inserção
`3`	Exclusão
`4`	Login
`5`	Outros
`6`	Visualização de dados
`7`	Complementar

Intervalo máximo de 61 dias

Assim como na pesquisa de eventos, o intervalo entre date_start e date_end não pode exceder 61 dias.

Exemplo de request

{
  "filters": {
    "date_start": "2025-01-01",
    "date_end": "2025-01-31",
    "logType": [1, 2, 3],
    "logObject": "Pessoa"
  },
  "sort": ["-date"],
  "page": {
    "number": 1,
    "size": 50
  }
}

Campos da resposta

Campo	Conteúdo
`id`	ID da operação
`type`	Tipo de operação (texto legível)
`object`	Objeto afetado
`key_id`	ID do registro afetado
`timestamp`	Data e hora da operação
`user_name`	Usuário que executou a operação (pode ser nulo)
`data`	Dados da operação em JSON

Consulta — Lotação de áreas

Endpoint: GET /api/1/occupancy

Retorna a lotação de todas as áreas cadastradas. Não aceita filtros.

Campos da resposta

Campo	Conteúdo
`id`	ID da área
`description`	Nome/descrição da área
`enabled`	Se a área está habilitada
`occupancy.current`	Pessoas atualmente na área
`occupancy.capacity`	Capacidade máxima
`occupancy.available`	Vagas disponíveis (`capacity - current`, nunca negativo)

Exemplo de resposta

[
  {
    "id": 1,
    "description": "Estacionamento Principal",
    "enabled": true,
    "occupancy": {
      "current": 45,
      "capacity": 100,
      "available": 55
    }
  }
]

Visitas — Criar evento

Endpoint: POST /api/1/event

Cria um evento de visita, vinculando um visitante a um anfitrião (host) já cadastrado no ACCELERO. Exige a permissão de criação de evento.

O host é localizado pelo CPF e precisa já existir, com pelo menos uma empresa vinculada. O visitante é localizado pelo CPF; se não existir (ou se o sistema estiver configurado para atualizar dados pela API), é cadastrado/atualizado com os dados informados.

Estrutura do payload

Bloco	Campo	Obrigatório	Descrição
`visitor`	`id`	Sim	Identificador do visitante no sistema externo (vendor)
`visitor`	`name`	Sim	Nome do visitante (3 a 50 caracteres)
`visitor`	`cpf`	Sim	CPF do visitante
`visitor`	`email`	Não	E-mail (até 50 caracteres)
`visitor`	`phone`	Não	Telefone (até 255 caracteres)
`visitor`	`photo`	Não	Foto do visitante em base64
`visitor`	`extra`	Não	Dados adicionais (até 500 caracteres)
`host`	`cpf`	Sim	CPF do anfitrião (deve existir no ACCELERO)
`host`	`unit`	Não	ID da empresa/unidade do anfitrião. Se omitido, usa a primeira empresa vinculada
`event`	`start`	Sim	Início do evento (`YYYY-MM-DD HH:MM:SS`)
`event`	`end`	Sim	Fim do evento (`YYYY-MM-DD HH:MM:SS`)
`event`	`type`	Sim	ID do tipo de evento (ver Listar tipos de evento)
`event`	`handler`	Sim	Identificador do sistema externo (vendor) que originou o evento
`event`	`status`	Não	Status inicial: cadastrado ou iniciado. Se omitido, usa o padrão do sistema
`webhook`	`onStart`	Não	URL de webhook chamada ao iniciar o evento
`webhook`	`onEnd`	Não	URL de webhook chamada ao encerrar o evento

Resposta

Em caso de sucesso, a API retorna {"success": true, "event_id": <id>} com o ID do evento criado.

Pré-requisitos do host

Se o CPF do host não existir, a API retorna 404 com Unknown host. Se o host não tiver empresa vinculada (ou a unit informada não corresponder a nenhuma), retorna 404 com Unknown unit.

TODO: Adicionar Diagrama

Fluxo de criação de visita via API: resolução do host pelo CPF → resolução da empresa/unidade → criação/atualização do visitante → criação do evento → vínculo visitante↔evento → registro dos webhooks.

Visitas — Cancelar evento

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

Cancela um evento de visita existente, identificado por {id} na rota. Exige a permissão de edição de evento.

O evento passa para o status cancelado, assim como os vínculos de pessoa associados a ele.

Resposta

Em caso de sucesso, retorna {"success": true}. Se o {id} não corresponder a um evento existente, retorna 404 com Unknown id.

Visitas — Listar tipos de evento

Endpoint: GET /api/1/event/types

Retorna os tipos de evento disponíveis, para preencher o campo event.type ao criar uma visita. Cada item contém id e description.

[
  { "id": 1, "description": "Visita" },
  { "id": 2, "description": "Prestador de serviço" }
]

Valores ilustrativos

Os IDs e descrições acima são exemplos. Os valores reais dependem dos tipos de evento cadastrados em cada ambiente.

Consulta — Listar categorias de pessoa

Endpoint: GET /api/1/categories

Retorna as categorias de pessoa cadastradas, úteis para preencher o filtro categories na pesquisa de eventos. Cada item contém id e description.

[
  { "id": 1, "description": "Funcionário" },
  { "id": 2, "description": "Visitante" }
]

Recursos para desenvolvedores

O plugin inclui artefatos técnicos que facilitam a integração:

Especificação OpenAPI 3.0 (openapi.yaml) — descreve os endpoints de consulta (eventos, operações e lotação) para uso em ferramentas como o Swagger Editor.
Collection do Postman (Accelero_API_v1.postman_collection.json) — requisições prontas com variáveis de base_url e api_key.

Disponibilidade dos artefatos

Os arquivos OpenAPI e Postman acompanham o plugin. Solicite-os ao suporte IONGRADE durante a implantação da integração.

OpenAPI x endpoints de visita

A especificação OpenAPI distribuída cobre os três endpoints de consulta (events/search, operations, occupancy). Os endpoints de visita (POST/DELETE /api/1/event, event/types, categories) foram adicionados na versão 1.1.0 e podem ainda não constar do arquivo OpenAPI — use esta página como referência para eles.

Boas práticas

Uma API Key por integração: crie um usuário dedicado no ACCELERO para cada sistema integrado, com apenas as permissões necessárias. Isso facilita auditoria e revogação.
Respeite o limite de 61 dias: ao consultar grandes períodos de eventos ou operações, fatie as consultas em janelas de até 61 dias e use a paginação.
Valide os IDs antes de criar visitas: consulte event/types e categories para obter IDs válidos antes de montar o payload de criação de evento.
Trate erros pelo campo error: todas as respostas de erro trazem success: false e uma mensagem em error — use-a para diagnóstico.

Troubleshooting

`401 — Invalid API key`

Possíveis causas:

Header Authorization ausente ou fora do formato Bearer <token>
Token incorreto ou revogado

Solução: confirme o header e gere uma nova API Key se necessário.

`401 — Not authorized`

Possível causa: o usuário associado à API Key não tem a permissão exigida pelo endpoint (listar log de eventos, criar/editar evento, listar categorias, etc.).

Solução: ajuste as permissões do usuário da integração no ACCELERO.

`400 — Max range date exceeded`

Possível causa: intervalo entre date_start e date_end maior que 61 dias, ou uma das datas ausente.

Solução: reduza o intervalo e garanta que ambas as datas estejam preenchidas.

`404 — Unknown host` / `Unknown unit` (ao criar visita)

Possíveis causas:

O CPF do host não existe no ACCELERO
O host não tem empresa vinculada, ou a unit informada não corresponde a nenhuma empresa dele

Solução: confirme o cadastro do anfitrião e o ID da unidade.

Integração com outros módulos

A API v1 opera sobre as entidades centrais do ACCELERO:

Pessoas e categorias — a pesquisa de eventos e a criação de visitas dependem do cadastro de Pessoas e de suas categorias.
Áreas — a lotação reflete a configuração de capacidade das Áreas.
Eventos (visitas) — a criação e o cancelamento atuam sobre Eventos.
Logs e monitoramento — a pesquisa de eventos consome o histórico de Logs e Monitoramento.

Próximos Passos

Pessoas — Entenda o cadastro consumido pela API
Áreas — Configuração de capacidade usada na lotação
Eventos — Eventos de visita criados/cancelados pela API

O que a API faz​

Convenções gerais​

Autenticação​

Exemplo com cURL​

Códigos de status e erros​

Consulta — Pesquisa de eventos de acesso​

Parâmetros (corpo JSON)​

Exemplo de request​

Campos da resposta​

Exemplo de resposta​

Consulta — Log de operações​

Parâmetros (corpo JSON)​

Tipos de operação (logType)​

Exemplo de request​

Campos da resposta​

Consulta — Lotação de áreas​

Campos da resposta​

Exemplo de resposta​

Visitas — Criar evento​

Estrutura do payload​

Visitas — Cancelar evento​

Visitas — Listar tipos de evento​

Consulta — Listar categorias de pessoa​

Recursos para desenvolvedores​

Boas práticas​

Troubleshooting​

401 — Invalid API key​

401 — Not authorized​

400 — Max range date exceeded​

404 — Unknown host / Unknown unit (ao criar visita)​

Integração com outros módulos​

Próximos Passos​

O que a API faz

Convenções gerais

Autenticação

Exemplo com cURL

Códigos de status e erros

Consulta — Pesquisa de eventos de acesso

Parâmetros (corpo JSON)

Exemplo de request

Campos da resposta

Exemplo de resposta

Consulta — Log de operações

Parâmetros (corpo JSON)

Tipos de operação (`logType`)

Exemplo de request

Campos da resposta

Consulta — Lotação de áreas

Campos da resposta

Exemplo de resposta

Visitas — Criar evento

Estrutura do payload

Visitas — Cancelar evento

Visitas — Listar tipos de evento

Consulta — Listar categorias de pessoa

Recursos para desenvolvedores

Boas práticas

Troubleshooting

`401 — Invalid API key`

`401 — Not authorized`

`400 — Max range date exceeded`

`404 — Unknown host` / `Unknown unit` (ao criar visita)

Integração com outros módulos

Próximos Passos