API de Pessoa

A API de Pessoa permite gerenciar o cadastro de pessoas no sistema Accessus. Pessoas são entidades fundamentais que podem ser associadas a acessos.

Visão Geral

Método	Endpoint	Descrição
POST	/persons	Criar nova pessoa
GET	/persons/documentNumber/:documentNumber	Consultar pessoa por número do documento
GET	/persons/email/:email	Consultar pessoa por e-mail

Base URL

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

---

Cadastro

Criar Pessoa

Cadastra uma nova pessoa no sistema.

POST/accessus/api/v1/persons

Autenticação

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

Corpo da Requisição

Campo	Tipo	Obrigatório	Descrição
name	string	✓	Nome da pessoa
familyName	string	✓	Sobrenome da pessoa
gender	number	✓	Sexo: 0 = Masculino, 1 = Feminino
documentType	object	✓	Tipo do documento (deve existir no sistema)
documentType.name	string	✓	Nome do tipo de documento (ex: CPF)
documentNumber	string	-	Número do documento
birthDate	string	-	Data de nascimento (formato: YYYY-MM-DD)
email	string	-	E-mail da pessoa
phoneNumber	string	-	Telefone de contato
place	string	-	Local/sala
garage	string	-	Vaga de garagem
companyName	string	-	Nome da empresa
registrationNumber	string	-	Número de matrícula
observation	string	-	Observações adicionais
contractTypeId	number	-	ID do tipo de contrato
unityId	number	-	ID da unidade
mainPhotoContent	string	-	Foto principal da pessoa em Base64. Quando informada, é cadastrada como foto principal

Exemplo de Requisição:

{
  "name": "João",
  "familyName": "da Silva",
  "birthDate": "2024-04-11",
  "place": "Sala 1",
  "garage": "G1 - 9",
  "documentType": { 
    "name": "CPF" 
  },
  "documentNumber": "11122233344",
  "gender": 0,
  "phoneNumber": "48999999292",
  "email": "joao@toptic.com.br",
  "observation": "n/a",
  "companyName": "TOPTIC TECHNOLOGY",
  "registrationNumber": "12345678",
  "contractTypeId": 1,
  "unityId": 1,
  "mainPhotoContent": "iVBORw0KGgoAAAANSUhEUgAA..."
}

Respostas

✅ 201 CREATED - Pessoa criada com sucesso

{
  "id": 7,
  "name": "João",
  "familyName": "da Silva",
  "birthDate": "2024-04-11",
  "place": "Sala 1",
  "garage": "G1 - 9",
  "documentType": { 
    "name": "CPF" 
  },
  "documentNumber": "11122233344",
  "gender": 0,
  "phoneNumber": "48999999292",
  "email": "joao@toptic.com.br",
  "observation": "n/a",
  "companyName": "TOPTIC TECHNOLOGY"
}

❌ 400 BAD REQUEST - Campos obrigatórios não enviados

{
  "status": 400,
  "message": "Alguns campos obrigatórios não enviados.",
  "path": "/accessus/api/v1/persons/"
}

❌ 400 BAD REQUEST - Tipo de documento inválido

{
  "status": 400,
  "message": "Tipo de documento não existe: XYZ",
  "path": "/accessus/api/v1/persons/"
}

❌ 400 BAD REQUEST - Documento já existente

{
  "status": 400,
  "message": "O nº documento 11122233344 já existe na base de dados.",
  "path": "/accessus/api/v1/persons/"
}

---

Consulta

Os endpoints de consulta retornam os mesmos dados do cadastro da pessoa. Os campos documentType, contractType e unity são retornados como objetos com id e name, e mainPhotoContent traz a foto principal em Base64 (ou null quando a pessoa não possui foto). A consulta respeita o escopo de organização do usuário autenticado.

Consultar Pessoa por Documento

Retorna a pessoa correspondente ao número do documento informado.

GET/accessus/api/v1/persons/documentNumber/:documentNumber

Autenticação

Requisito	Valor
Autenticação	Obrigatória
Permissão	PERM_API_READ_PERSON

Parâmetros de URL

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

Respostas

✅ 200 OK - Pessoa encontrada

{
  "name": "João",
  "familyName": "da Silva",
  "gender": 0,
  "documentType": {
    "id": 1,
    "name": "CPF"
  },
  "documentNumber": "11122233344",
  "birthDate": "2024-04-11",
  "email": "joao@toptic.com.br",
  "phoneNumber": "48999999292",
  "place": "Sala 1",
  "garage": "G1 - 9",
  "companyName": "TOPTIC TECHNOLOGY",
  "registrationNumber": "12345678",
  "observation": "n/a",
  "contractType": {
    "id": 1,
    "name": "CLT"
  },
  "unity": {
    "id": 1,
    "name": "Matriz"
  },
  "mainPhotoContent": "iVBORw0KGgoAAAANSUhEUgAA..."
}

❌ 404 NOT FOUND - Pessoa não encontrada

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

---

Consultar Pessoa por E-mail

Retorna a pessoa correspondente ao e-mail informado. O endpoint resolve um único registro: quando há mais de uma pessoa com o mesmo e-mail no escopo do usuário, é retornado um erro de conflito.

GET/accessus/api/v1/persons/email/:email

Autenticação

Requisito	Valor
Autenticação	Obrigatória
Permissão	PERM_API_READ_PERSON

Parâmetros de URL

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

Respostas

✅ 200 OK - Pessoa encontrada

{
  "name": "João",
  "familyName": "da Silva",
  "gender": 0,
  "documentType": {
    "id": 1,
    "name": "CPF"
  },
  "documentNumber": "11122233344",
  "birthDate": "2024-04-11",
  "email": "joao@toptic.com.br",
  "phoneNumber": "48999999292",
  "place": "Sala 1",
  "garage": "G1 - 9",
  "companyName": "TOPTIC TECHNOLOGY",
  "registrationNumber": "12345678",
  "observation": "n/a",
  "contractType": {
    "id": 1,
    "name": "CLT"
  },
  "unity": {
    "id": 1,
    "name": "Matriz"
  },
  "mainPhotoContent": "iVBORw0KGgoAAAANSUhEUgAA..."
}

❌ 404 NOT FOUND - Pessoa não encontrada

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

❌ 400 BAD REQUEST - Mais de uma pessoa com o mesmo e-mail

{
  "status": 400,
  "message": "There was more than one person for the email: joao@toptic.com.br",
  "path": "/accessus/api/v1/persons/email/joao@toptic.com.br"
}

---

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_WRITE_PERSON	Permite criar e editar pessoas
PERM_API_READ_PERSON	Permite consultar pessoas (por documento e por e-mail)

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.