API de Acesso

A API de Acesso permite gerenciar os acessos de pessoas no sistema Accessus, incluindo operações de agendamento, ativação/desativação e importação em massa.

Visão Geral

Método	Endpoint	Descrição
`POST`	`/accesses`	Criar acesso
`POST`	`/accesses/email/:email/schedule`	Adicionar agendamentos (por e-mail)
`POST`	`/accesses/docNumber/:docNumber/schedule`	Adicionar agendamentos (por documento)
`DELETE`	`/accesses/schedules/:id`	Remover agendamento
`PUT`	`/accesses/docNumber/:docNumber/tempInactive/:tempInactive`	Ativar/Desativar temporariamente
`DELETE`	`/accesses/docNumber/:docNumber/endAccess`	Finalizar acesso
`GET`	`/accesses/expired`	Listar acessos expirados
`POST`	`/accesses/import`	Importar em massa

Base URL

Todos os endpoints utilizam o prefixo: /accessus/api/v1

Recursos auxiliares

Para obter os ids usados na criação e no agendamento de acessos, consulte: API de Grupos de Acesso (id do grupo) e API de Pontos de Acesso (id do ponto de acesso).

Criação

Criar Acesso

Cria um novo acesso associando uma pessoa (pelo número do documento) a um grupo de acesso e/ou a uma lista de agendamentos. A pessoa deve existir previamente no sistema; o grupo de acesso e os pontos de acesso informados também.

POST/accessus/api/v1/accesses

Autenticação

Requisito	Valor
Autenticação	Obrigatória
Permissão	`PERM_API_WRITE_ACCESS`
Content-Type	`application/json`

Corpo da Requisição

Campo	Tipo	Obrigatório	Descrição
`docNumber`	string	✓	Número do documento da pessoa a ser associada ao acesso
`accessGroupId`	number	condicional	ID do grupo de acesso (ver API de Grupos de Acesso). Obrigatório apenas quando `schedules` não for informado
`schedules`	object[]	condicional	Lista de agendamentos do acesso. Obrigatória apenas quando `accessGroupId` não for informado. Cada item usa os mesmos campos do agendamento (ver abaixo)
`responsibleDocNumber`	string	-	Número do documento da pessoa responsável
`observation`	string	-	Observação do acesso
`createQrcode`	boolean	-	Quando `true`, cria também uma credencial do tipo QR Code (padrão: `false`)
`expiration`	string \| number	-	Data/hora de expiração. Aceita ISO-8601 (ex: `2025-12-31T23:59:59`) ou timestamp em milissegundos. Obrigatória quando o grupo de acesso não é permanente

Grupo de acesso e/ou agendamentos

É obrigatório informar accessGroupId e/ou schedules (um, o outro, ou ambos). Uma requisição sem grupo de acesso e sem agendamentos é rejeitada com 400.

Campos de cada item de schedules:

Campo	Tipo	Obrigatório	Descrição
`description`	string	✓	Descrição do agendamento (máximo 40 caracteres)
`startDate`	string \| number	✓	Data/hora inicial (ISO-8601 ou timestamp em milissegundos)
`finalDate`	string \| number	✓	Data/hora final (ISO-8601 ou timestamp em milissegundos)
`accessPointId`	number	-	ID do ponto de acesso do agendamento (ver API de Pontos de Acesso). Quando omitido, são utilizados os pontos de acesso dos grupos do usuário autenticado
`createQrcode`	boolean	-	Quando `true`, cria/atribui uma credencial do tipo QR Code ao acesso (e, se a pessoa tiver foto, também a credencial Facial). Padrão: `false`

Credencial facial automática

Se a pessoa associada possuir foto cadastrada, uma credencial do tipo Facial é criada automaticamente para o acesso.

Exemplo de Requisição (com grupo de acesso):

{
  "docNumber": "11122233344",
  "accessGroupId": 5,
  "responsibleDocNumber": "55566677788",
  "observation": "Acesso criado via API",
  "createQrcode": true,
  "expiration": "2025-12-31T23:59:59"
}

Exemplo de Requisição (com lista de agendamentos, sem grupo de acesso):

{
  "docNumber": "11122233344",
  "schedules": [
    {
      "description": "Visita técnica",
      "startDate": "2025-10-25T13:14:52",
      "finalDate": "2025-11-04T08:47:01",
      "accessPointId": 3,
      "createQrcode": true
    }
  ]
}

Exemplo de Requisição (com grupo de acesso e agendamentos):

{
  "docNumber": "11122233344",
  "accessGroupId": 5,
  "schedules": [
    {
      "description": "Reunião TOPTIC",
      "startDate": "2025-10-25T13:14:52",
      "finalDate": "2025-11-04T08:47:01"
    }
  ]
}

Respostas

✅ 201 CREATED - Acesso criado com sucesso

O corpo da resposta contém os dados enviados acrescidos do id do acesso criado. Quando schedules é informado, a resposta inclui os agendamentos criados, cada um com seu id.

{
  "id": 7,
  "docNumber": "11122233344",
  "accessGroupId": 5,
  "responsibleDocNumber": "55566677788",
  "observation": "Acesso criado via API",
  "createQrcode": true,
  "expiration": "2025-12-31T23:59:59"
}

Exemplo de resposta para criação com agendamentos:

{
  "id": 8,
  "docNumber": "11122233344",
  "createQrcode": false,
  "schedules": [
    {
      "id": 40,
      "description": "Visita técnica",
      "startDate": "2025-10-25T13:14:52",
      "finalDate": "2025-11-04T08:47:01",
      "createQrcode": true
    }
  ]
}

❌ 404 NOT FOUND - Pessoa não encontrada

{
  "status": 404,
  "message": "Person not found for document number: 11122233344",
  "path": "/accessus/api/v1/accesses"
}

❌ 404 NOT FOUND - Pessoa responsável não encontrada

{
  "status": 404,
  "message": "Responsible person not found for document number: 55566677788",
  "path": "/accessus/api/v1/accesses"
}

❌ 404 NOT FOUND - Grupo de acesso não encontrado

{
  "status": 404,
  "message": "Access Group not found for id: 5",
  "path": "/accessus/api/v1/accesses"
}

❌ 404 NOT FOUND - Ponto de acesso do agendamento não encontrado

Ocorre quando um item de schedules informa um accessPointId inexistente.

{
  "status": 404,
  "message": "Access Point not found for id: 3",
  "path": "/accessus/api/v1/accesses"
}

❌ 400 BAD REQUEST - Grupo de acesso e/ou agendamentos não informados

{
  "status": 400,
  "message": "accessGroupId and/or schedules must be provided.",
  "path": "/accessus/api/v1/accesses"
}

❌ 400 BAD REQUEST - Dados inválidos

{
  "status": 400,
  "messages": [
    "docNumber is required",
    "description is required"
  ],
  "path": "/accessus/api/v1/accesses"
}

Agendamentos

Adicionar Agendamento (por e-mail)

Adiciona um ou mais agendamentos a um acesso existente, identificado pelo e-mail da pessoa.

POST/accessus/api/v1/accesses/email/:email/schedule

Autenticação

Requisito	Valor
Autenticação	Obrigatória
Permissão	`PERM_API_WRITE_ACCESS`
Content-Type	`application/json`

Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
`email`	string	✓	E-mail da pessoa associada ao acesso	`joao@toptic.com.br`

Corpo da Requisição

Campo	Tipo	Obrigatório	Descrição
`description`	string	✓	Descrição do agendamento (máximo 40 caracteres)
`startDate`	number	✓	Data/hora inicial (timestamp em milissegundos)
`finalDate`	number	✓	Data/hora final (timestamp em milissegundos)
`accessPointId`	number	-	ID do ponto de acesso do agendamento (ver API de Pontos de Acesso). Quando omitido, são utilizados os pontos de acesso dos grupos do usuário autenticado
`createQrcode`	boolean	-	Quando `true`, cria/atribui uma credencial do tipo QR Code ao acesso (e, se a pessoa tiver foto, também a credencial Facial). Padrão: `false`

Exemplo de Requisição:

[
  { 
    "description": "Reunião TOPTIC 1",
    "startDate": 1666781221748,
    "finalDate": 1667562421748,
    "accessPointId": 3,
    "createQrcode": true
  },
  { 
    "description": "Reunião TOPTIC 2",
    "startDate": 1666781221748,
    "finalDate": 1667562421748
  }
]

Respostas

✅ 201 CREATED - Agendamentos criados com sucesso

[
  { 
    "id": 7,
    "description": "Reunião TOPTIC 1",
    "startDate": 1666781221748,
    "finalDate": 1667562421748
  },
  { 
    "id": 8,
    "description": "Reunião TOPTIC 2",
    "startDate": 1666781221748,
    "finalDate": 1667562421748
  }
]

❌ 404 NOT FOUND - Acesso não encontrado

{
  "status": 404,
  "message": "Access not found for email: joao@toptic.com.br",
  "path": "/accessus/api/v1/accesses/email/joao@toptic.com.br/schedule"
}

❌ 400 BAD REQUEST - Dados inválidos

{
  "status": 400,
  "messages": [ 
    "Some error message 1",
    "Some error message 2"
  ],
  "path": "/accessus/api/v1/accesses/email/joao@toptic.com.br/schedule"
}

Adicionar Agendamento (por documento)

Adiciona um ou mais agendamentos a um acesso existente, identificado pelo número do documento da pessoa. Aceita os mesmos campos do agendamento por e-mail, incluindo accessPointId e createQrcode.

POST/accessus/api/v1/accesses/docNumber/:docNumber/schedule

Autenticação

Requisito	Valor
Autenticação	Obrigatória
Permissão	`PERM_API_WRITE_ACCESS`
Content-Type	`application/json`

Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
`docNumber`	string	✓	Número do documento da pessoa associada ao acesso	`11122233344`

Corpo da Requisição

Campo	Tipo	Obrigatório	Descrição
`description`	string	✓	Descrição do agendamento (máximo 40 caracteres)
`startDate`	number	✓	Data/hora inicial (timestamp em milissegundos)
`finalDate`	number	✓	Data/hora final (timestamp em milissegundos)
`accessPointId`	number	-	ID do ponto de acesso do agendamento. Quando omitido, são utilizados os pontos de acesso dos grupos do usuário autenticado
`createQrcode`	boolean	-	Quando `true`, cria/atribui uma credencial do tipo QR Code ao acesso (e, se a pessoa tiver foto, também a credencial Facial). Padrão: `false`

Exemplo de Requisição:

[
  { 
    "description": "Visita técnica",
    "startDate": 1666781221748,
    "finalDate": 1667562421748,
    "accessPointId": 3,
    "createQrcode": true
  }
]

Respostas

✅ 201 CREATED - Agendamentos criados com sucesso

[
  { 
    "id": 9,
    "description": "Visita técnica",
    "startDate": 1666781221748,
    "finalDate": 1667562421748
  }
]

❌ 404 NOT FOUND - Acesso não encontrado

{
  "status": 404,
  "message": "Access not found for document number: 11122233344",
  "path": "/accessus/api/v1/accesses/docNumber/11122233344/schedule"
}

❌ 404 NOT FOUND - Ponto de acesso não encontrado

{
  "status": 404,
  "message": "Access Point not found for id: 3",
  "path": "/accessus/api/v1/accesses/docNumber/11122233344/schedule"
}

Remover Agendamento

Remove um agendamento específico pelo seu ID.

DELETE/accessus/api/v1/accesses/schedules/:id

Autenticação

Requisito	Valor
Autenticação	Obrigatória
Permissão	`PERM_API_WRITE_ACCESS`

Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
`id`	number	✓	ID do agendamento a ser removido	`45`

Respostas

✅ 200 OK - Agendamento removido com sucesso

Sem conteúdo no corpo da resposta.

❌ 404 NOT FOUND - Agendamento não encontrado

{
  "status": 404,
  "message": "Access Schedule with id 45 was not found.",
  "path": "/accessus/api/v1/accesses/schedules/45"
}

Gerenciamento de Status

Ativar ou Desativar Acesso Temporariamente

Altera o status de um acesso entre ativo e temporariamente inativo, sem finalizá-lo definitivamente.

PUT/accessus/api/v1/accesses/docNumber/:docNumber/tempInactive/:tempInactive

Autenticação

Requisito	Valor
Autenticação	Obrigatória
Permissão	`PERM_API_WRITE_ACCESS`
Content-Type	`application/json`

Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
`docNumber`	string	✓	Número do documento da pessoa	`SC12345678`
`tempInactive`	boolean	✓	`true` para desativar, `false` para reativar	`true`

Corpo da Requisição (opcional)

Campo	Tipo	Obrigatório	Descrição
`reason`	string	-	Motivo da alteração de status

Exemplo de Requisição:

{ 
  "reason": "Férias do colaborador"
}

Respostas

✅ 200 OK - Status alterado com sucesso

Sem conteúdo no corpo da resposta.

❌ 404 NOT FOUND - Acesso não encontrado

{
  "status": 404,
  "message": "Access not found for document number: 11111111111",
  "path": "/accessus/api/v1/accesses/docNumber/11111111111/tempInactive/true"
}

Finalizar Acesso Definitivamente

Encerra um acesso de forma permanente. Esta ação não pode ser desfeita.

DELETE/accessus/api/v1/accesses/docNumber/:docNumber/endAccess

Atenção

Esta operação é irreversível. O acesso será finalizado permanentemente e não poderá ser reativado.

Autenticação

Requisito	Valor
Autenticação	Obrigatória
Permissão	`PERM_API_WRITE_ACCESS`

Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
`docNumber`	string	✓	Número do documento da pessoa	`SP77777777`

Respostas

✅ 200 OK - Acesso finalizado com sucesso

Sem conteúdo no corpo da resposta.

❌ 404 NOT FOUND - Acesso não encontrado

{
  "status": 404,
  "message": "Access not found for document number: 11111111111",
  "path": "/accessus/api/v1/accesses/docNumber/11111111111/endAccess"
}

Consultas

Obter Acessos Expirados

Retorna uma lista com os números de documento de todos os acessos que já expiraram.

GET/accessus/api/v1/accesses/expired

Autenticação

Requisito	Valor
Autenticação	Obrigatória
Permissão	`PERM_API_READ_ACCESS`

Respostas

✅ 200 OK - Lista de documentos retornada

[
  "11111111111",
  "22222222222",
  "99999999999"
]

Importação

Importar Acessos em Massa

Permite importar múltiplos acessos de uma vez através de um arquivo CSV.

POST/accessus/api/v1/accesses/import

Autenticação

Requisito	Valor
Autenticação	Obrigatória
Permissão	`PERM_API_IMPORT_ACCESS`
Content-Type	`multipart/form-data`

Parâmetros (Form-Data)

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
`file`	file	✓	Arquivo CSV com os acessos	`acessos.csv`

Colunas do CSV

Coluna	Obrigatório	Descrição
`document_type`	✓	Tipo do documento (deve existir no sistema)
`document_number`	✓	Número do documento
`name`	✓	Nome completo da pessoa
`access_group_ids`	✓	IDs dos grupos de acesso
`photo_base64`	✓	Foto em Base64
`gender`	-	Sexo: `0` = Masculino, `1` = Feminino
`registration_number`	-	Número de matrícula
`birthdate`	-	Data de nascimento (formato: `dd/MM/yyyy`)
`templates_base64`	-	Templates biométricos em Base64

Respostas

✅ 201 CREATED - Importação realizada com sucesso

Sem conteúdo no corpo da resposta.

❌ 404 NOT FOUND - Erro na importação

Verifique se o arquivo CSV está no formato correto.

Permissões

Para habilitar as permissões necessárias para utilizar esta API, acesse: Atribuir Permissões ao Papel

Permissão	Descrição
`PERM_API_READ_ACCESS`	Permite consultar acessos
`PERM_API_WRITE_ACCESS`	Permite criar, editar e remover acessos
`PERM_API_IMPORT_ACCESS`	Permite importar acessos em massa

Atenção

Após habilitar uma permissão no menu Papel, realize o logout do sistema e reinicie a aplicação para que as alterações tenham efeito.

API de Acesso

Visão Geral​

Base URL

Recursos auxiliares

Criação​

Criar Acesso​

Autenticação​

Corpo da Requisição​

Grupo de acesso e/ou agendamentos

Credencial facial automática

Respostas​

Agendamentos​

Adicionar Agendamento (por e-mail)​

Autenticação​

Parâmetros de URL​

Corpo da Requisição​

Respostas​

Adicionar Agendamento (por documento)​

Autenticação​

Parâmetros de URL​

Corpo da Requisição​

Respostas​

Remover Agendamento​

Autenticação​

Parâmetros de URL​

Respostas​

Gerenciamento de Status​

Ativar ou Desativar Acesso Temporariamente​

Autenticação​

Parâmetros de URL​

Corpo da Requisição (opcional)​

Respostas​

Finalizar Acesso Definitivamente​

Atenção

Autenticação​

Parâmetros de URL​

Respostas​

Consultas​

Obter Acessos Expirados​

Autenticação​

Respostas​

Importação​

Importar Acessos em Massa​

Autenticação​

Parâmetros (Form-Data)​

Colunas do CSV​

Respostas​

Permissões​

Atenção

Visão Geral

Criação

Criar Acesso

Autenticação

Corpo da Requisição

Respostas

Agendamentos

Adicionar Agendamento (por e-mail)

Autenticação

Parâmetros de URL

Corpo da Requisição

Respostas

Adicionar Agendamento (por documento)

Autenticação

Parâmetros de URL

Corpo da Requisição

Respostas

Remover Agendamento

Autenticação

Parâmetros de URL

Respostas

Gerenciamento de Status

Ativar ou Desativar Acesso Temporariamente

Autenticação

Parâmetros de URL

Corpo da Requisição (opcional)

Respostas

Finalizar Acesso Definitivamente

Autenticação

Parâmetros de URL

Respostas

Consultas

Obter Acessos Expirados

Autenticação

Respostas

Importação

Importar Acessos em Massa

Autenticação

Parâmetros (Form-Data)

Colunas do CSV

Respostas

Permissões