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/email/:email/schedule	Adicionar agendamentos
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

---

Agendamentos

Adicionar Agendamento

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)

Exemplo de Requisição:

[
  { 
    "description": "Reunião TOPTIC 1",
    "startDate": 1666781221748,
    "finalDate": 1667562421748
  },
  { 
    "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"
}

---

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.