API Reference · Identidade e acesso

Convenções

As rotas protegidas recebem Authorization: Bearer <credencial>. A API aceita JWT próprio, JWT Appwrite e token de sistema conforme a operação. A autorização dos recursos permanece nas ACLs da API. Os erros usam o corpo abaixo. Cada tabela de erros declara o status, o código confirmado e a condição. Quando um status possui causas diferentes, a tabela separa cada variante confirmada. O formato abaixo vale para os erros produzidos pela aplicação; exceções do próprio framework sem código explícito podem não incluir errorCode.

Corpo de erro — JSON

Campo	Tipo	Presença	Descrição
`statusCode`	number	Sempre	Repete o status HTTP.
`message`	string ou array de strings	Sempre	Mensagem legível; validação pode retornar várias mensagens.
`errorCode`	string	Condicional	Código estável nos erros emitidos pela aplicação; pode faltar em exceção do framework sem código explícito.
`error`	string	Condicional	Nome do status HTTP; ausente em algumas exceções com corpo textual.

Cadastro de Pessoa e conta

`POST /v1/people`

Cria uma Pessoa. Com account, cadastra também a conta vinculada e provisiona a identidade no Appwrite.

Autenticação e autorização: Bearer de Pessoa com Acesso de Núcleo ou superior. A criação da conta requer Acesso Global e Pessoa física com papel USER ou ASSOCIATE.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Corpo	`personType`	`FISICA` ou `JURIDICA`	Condicional	Com `account`, informe `FISICA`.
Corpo	`name` / `companyName`	string	Condicional	Informe nome ou razão social.
Corpo	`roles`	array de papéis	Condicional	Com `account`, inclui `USER` ou `ASSOCIATE`.
Corpo	`account.email`	e-mail, até 254 caracteres	Com `account`	E-mail de acesso.
Corpo	`account.password`	string, 8 a 72 caracteres	Com `account`	Credencial provisionada no Appwrite.
Corpo	`account.accessProfile`	Perfil de Acesso	Com `account`	Perfil concedido pelo operador.
Corpo	`cpfCnpj`	string ou `null`	Não	CPF/CNPJ válido, normalizado para dígitos.
Corpo	`hasNoCpfCnpj`	boolean	Não	Incompatível com `cpfCnpj`.
Corpo	`noCpfCnpjReason`	string ou `null`, até 120 caracteres	Não	Motivo da ausência de documento.
Corpo	`identifier`	string ou `null`, até 40 caracteres	Não	Identificador livre.
Corpo	`identityStatus`	estado da identidade	Não	Estado da identidade da Pessoa.
Corpo	`possibleDuplicateOf`	array de UUIDs	Não	Pessoas candidatas a duplicata.
Corpo	`nucleos`	array de siglas	Não	Núcleos responsáveis; siglas normalizadas.
Corpo	`portfolioId`	UUID	Com `CLIENT`	Carteira do novo cliente.
Corpo	`portfolioEffectiveFrom`	data civil `YYYY-MM-DD`	Com `CLIENT`	Início do vínculo com a Carteira.
Corpo	`originUoSigla`	string ou `null`, até 40 caracteres	Com `CLIENT`	Unidade de origem; sigla normalizada.
Corpo	`originDate`	data civil `YYYY-MM-DD` ou `null`	Com `CLIENT`	Data de entrada pela unidade de origem.
Corpo	`originationType`	tipo de originação ou `null`	Não	Tipo da origem.
Corpo	`originCity`	string ou `null`, até 120 caracteres	Não	Cidade de origem.
Corpo	`referredByPersonId`	UUID ou `null`	Não	Pessoa indicadora.
Corpo	`referralType`	tipo de indicação ou `null`	Não	Requer `referredByPersonId`.
Corpo	`referralChannel`	canal de indicação ou `null`	Não	Canal de chegada.
Corpo	`birthDate`	data civil `YYYY-MM-DD` ou `null`	Não	Nascimento.
Corpo	`gender`	gênero ou `null`	Não	Gênero declarado.
Corpo	`generalNotes`	string ou `null`, até 5000 caracteres	Não	Observações gerais.
Corpo	`phones`	array de telefones	Não	Cada item aceita `phoneType`, `number`, `isPrimary`, `ownership` e `contactChannel`; `number` obrigatório.
Corpo	`emails`	array de e-mails	Não	Cada item aceita `emailType`, `email` e `isPrimary`; `email` obrigatório.
Corpo	`addresses`	array de endereços	Não	Cada item aceita `addressType`, `zipCode`, `street`, `number`, `complement`, `district`, `city`, `state`, `isPrimary`, `referencePoints`.
Corpo	`documents`	array de documentos	Não	Cada item aceita `documentType`, `number`, `issuingAuthority`, `issueDate`.

Itens das listas de entrada

Cada lista é opcional. Para cada item enviado, os campos seguem o contrato abaixo.

Campo	Tipo	Obrigatório no item	Descrição
`phones[].phoneType`	string ou `null`, até 40 caracteres	Não	Tipo do telefone.
`phones[].number`	string, até 30 caracteres	Sim	Número do telefone.
`phones[].isPrimary`	boolean ou `null`	Não	Marca telefone principal.
`phones[].ownership`	enum ou `null`	Não	Titularidade.
`phones[].contactChannel`	enum ou `null`	Não	Canal de contato.
`emails[].emailType`	string ou `null`, até 40 caracteres	Não	Tipo do e-mail.
`emails[].email`	e-mail, até 255 caracteres	Sim	Endereço de e-mail.
`emails[].isPrimary`	boolean ou `null`	Não	Marca e-mail principal.
`addresses[].addressType`	string ou `null`, até 40 caracteres	Não	Tipo do endereço.
`addresses[].zipCode`	string ou `null`, até 12 caracteres	Não	CEP.
`addresses[].street`	string ou `null`, até 255 caracteres	Não	Logradouro.
`addresses[].number`	string ou `null`, até 20 caracteres	Não	Número.
`addresses[].complement`	string ou `null`, até 120 caracteres	Não	Complemento.
`addresses[].district`	string ou `null`, até 120 caracteres	Não	Bairro.
`addresses[].city`	string ou `null`, até 120 caracteres	Não	Cidade.
`addresses[].state`	string ou `null`, até 4 caracteres	Não	UF.
`addresses[].isPrimary`	boolean ou `null`	Não	Marca endereço principal.
`addresses[].referencePoints`	array de até 5 strings	Não	Pontos de referência; cada um até 120 caracteres.
`documents[].documentType`	string ou `null`, até 60 caracteres	Não	Tipo do documento.
`documents[].number`	string ou `null`, até 60 caracteres	Não	Número do documento.
`documents[].issuingAuthority`	string ou `null`, até 120 caracteres	Não	Órgão emissor.
`documents[].issueDate`	data civil `YYYY-MM-DD` ou `null`	Não	Data de emissão.

Saída

HTTP	Campo	Tipo	Descrição
201	`id`	UUID	ID da Pessoa.
201	`personType`	`FISICA`, `JURIDICA` ou `null`	Natureza da Pessoa.
201	`name`	string ou `null`	Nome da Pessoa física.
201	`companyName`	string ou `null`	Razão social.
201	`cpfCnpj`	string ou `null`	CPF/CNPJ normalizado para dígitos.
201	`hasNoCpfCnpj`	boolean	Declara ausência de CPF/CNPJ.
201	`noCpfCnpjReason`	string ou `null`	Justificativa da ausência.
201	`identifier`	string ou `null`	Identificador livre.
201	`identityStatus`	estado da identidade	Estado da identidade.
201	`possibleDuplicateOf`	array de UUIDs	Candidatos a duplicata.
201	`nucleos`	array de siglas	Núcleos responsáveis.
201	`roles`	array de papéis	Papéis institucionais.
201	`originUoSigla`	string ou `null`	Unidade de origem.
201	`originDate`	data civil ou `null`	Data de origem.
201	`originationType`	tipo de originação ou `null`	Como a origem foi estabelecida.
201	`originCity`	string ou `null`	Cidade de origem.
201	`referredByPersonId`	UUID ou `null`	Pessoa indicadora.
201	`referralType`	tipo de indicação ou `null`	Qualificação da indicação.
201	`referralChannel`	canal de indicação ou `null`	Canal de chegada.
201	`birthDate`	data civil ou `null`	Data de nascimento.
201	`gender`	gênero ou `null`	Gênero declarado.
201	`generalNotes`	string ou `null`	Observações gerais.
201	`isClient`	boolean ou `null`	Indicador derivado dos processos.
201	`isOpposingParty`	boolean ou `null`	Indicador derivado dos processos.
201	`authorUserId`	UUID ou `null`	Autor do cadastro.
201	`portfolioId`	UUID ou `null`	Carteira vigente.
201	`phones`	array de `PersonPhone`	Telefones cadastrados.
201	`emails`	array de `PersonEmail`	E-mails cadastrados.
201	`addresses`	array de `PersonAddress`	Endereços cadastrados.
201	`documents`	array de `PersonIdDocument`	Documentos cadastrados.
201	`createdAt`	data e hora ISO 8601	Criação.
201	`updatedAt`	data e hora ISO 8601	Última atualização.
201	`account`	objeto ou `null`	`null` quando a conta não foi solicitada.
201	`account.id`	UUID	Identificador da conta.
201	`account.email`	string	E-mail normalizado.
201	`account.accessProfile`	Perfil de Acesso	Perfil concedido.
201	`account.active`	boolean	Estado da conta.

Itens das listas de saída

Cada item salvo inclui os campos públicos abaixo. personId e a relação interna person ficam fora da resposta.

Campo	Tipo	Descrição
`phones[].id`	UUID	Identificador do item.
`phones[].phoneType`	string ou `null`	Tipo do telefone.
`phones[].number`	string	Número do telefone.
`phones[].isPrimary`	boolean ou `null`	Marca telefone principal.
`phones[].ownership`	enum ou `null`	Titularidade.
`phones[].contactChannel`	enum ou `null`	Canal de contato.
`phones[].createdAt`	data e hora ISO 8601	Criação do item.
`emails[].id`	UUID	Identificador do item.
`emails[].emailType`	string ou `null`	Tipo do e-mail.
`emails[].email`	e-mail	Endereço de e-mail.
`emails[].isPrimary`	boolean ou `null`	Marca e-mail principal.
`emails[].createdAt`	data e hora ISO 8601	Criação do item.
`addresses[].id`	UUID	Identificador do item.
`addresses[].addressType`	string ou `null`	Tipo do endereço.
`addresses[].zipCode`	string ou `null`	CEP.
`addresses[].street`	string ou `null`	Logradouro.
`addresses[].number`	string ou `null`	Número.
`addresses[].complement`	string ou `null`	Complemento.
`addresses[].district`	string ou `null`	Bairro.
`addresses[].city`	string ou `null`	Cidade.
`addresses[].state`	string ou `null`	UF.
`addresses[].isPrimary`	boolean ou `null`	Marca endereço principal.
`addresses[].referencePoints`	array de strings	Pontos de referência; cada um até 120 caracteres.
`addresses[].createdAt`	data e hora ISO 8601	Criação do item.
`documents[].id`	UUID	Identificador do item.
`documents[].documentType`	string ou `null`	Tipo do documento.
`documents[].number`	string ou `null`	Número do documento.
`documents[].issuingAuthority`	string ou `null`	Órgão emissor.
`documents[].issueDate`	data civil `YYYY-MM-DD` ou `null`	Data de emissão.
`documents[].createdAt`	data e hora ISO 8601	Criação do item.

Erros

HTTP	`errorCode`	Condição
400	`VALIDATION_FAILED`	Corpo inválido, inclusive CPF/CNPJ ou papel inválido.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Perfil insuficiente ou concessão de perfil não autorizada.
404	`NOT_FOUND`	Carteira informada para papel `CLIENT` inexistente.
404	`APPWRITE_NOT_FOUND`	Appwrite devolveu 404 durante o provisionamento ou a verificação do e-mail.
409	`CONFLICT`	CPF/CNPJ ou e-mail da conta já cadastrado.
422	`RULE_VIOLATION`	Condição de domínio não atendida, inclusive conta sem Pessoa física ou papel elegível.
500	`INTERNAL`	Falha de persistência ou configuração do provedor de mutação.
500	`APPWRITE_CREDENTIALS`	Credenciais da integração Appwrite recusadas.
502	`APPWRITE_UPSTREAM`	Appwrite retornou falha ou houve erro de rede durante o provisionamento.
503	`UPSTREAM_UNAVAILABLE`	Integração Appwrite desabilitada para cadastro com conta.
504	`APPWRITE_TIMEOUT`	Prazo da integração Appwrite excedido.

Autenticação local

`POST /v1/auth/login`

Autentica uma conta local e emite JWT da API. Contas vinculadas ao Appwrite usam a sessão do provedor.

Autenticação e autorização: operação pública; limite de cinco tentativas por minuto por IP.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Corpo	`email`	e-mail, até 254 caracteres	Sim	E-mail de acesso.
Corpo	`password`	string, 1 a 72 caracteres	Sim	Senha da conta local.

Saída

HTTP	Campo	Tipo	Descrição
200	`accessToken`	string	JWT para Bearer.
200	`expiresIn`	number	Validade em segundos.

Erros

HTTP	`errorCode`	Condição
400	`VALIDATION_FAILED`	Corpo inválido.
401	`UNAUTHORIZED`	Credenciais inválidas, conta inativa ou conta Appwrite.
403	`ACCESS_PROFILE_UNMAPPED`	Conta sem Perfil de Acesso convertido.
429	`RATE_LIMITED`	Limite de tentativas excedido.

`GET /v1/users/me`

Retorna a conta da Pessoa autenticada e seus vínculos com núcleos.

Autenticação e autorização: Bearer JWT próprio ou Appwrite; token de sistema não representa Pessoa.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Cabeçalho	`Authorization`	Bearer JWT	Sim	Credencial de Pessoa.

Saída

HTTP	Campo	Tipo	Descrição
200	`id`	UUID	ID da conta.
200	`personId`	UUID ou `null`	Pessoa titular; nulo para conta legada sem vínculo.
200	`email`	string	E-mail da conta.
200	`name`	string	Nome de exibição.
200	`accessProfile`	Perfil de Acesso	Perfil efetivo.
200	`nuclei`	array	Núcleos da Pessoa; vazio sem vínculos.
200	`nuclei[].sigla`	string	Sigla do núcleo.
200	`nuclei[].role`	papel no núcleo	Papel no vínculo.

Erros

HTTP	`errorCode`	Condição
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de sistema.
403	`ACCESS_PROFILE_UNMAPPED`	Conta sem Perfil de Acesso convertido.

`PATCH /v1/users/me/password`

Altera a senha da conta local. Contas Appwrite alteram a senha no provedor.

Autenticação e autorização: Bearer JWT próprio de Pessoa titular da conta local.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Corpo	`currentPassword`	string, 1 a 72 caracteres	Sim	Senha atual.
Corpo	`newPassword`	string, 8 a 72 caracteres	Sim	Nova senha.

Saída

HTTP	Campo	Tipo	Descrição
204	—	sem corpo	Senha alterada.

Erros

HTTP	`errorCode`	Condição
400	`VALIDATION_FAILED`	Corpo inválido.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Senha atual incorreta, token de sistema ou conta Appwrite.

Tokens de sistema

`POST /v1/auth/tokens`

Emite token de máquina vinculado a um sistema habilitado. O segredo completo aparece somente nesta resposta. Cada item listado depois omite o segredo e seu hash.

Autenticação e autorização: Bearer de Pessoa com Acesso de Núcleo ou superior.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Corpo	`name`	string, até 120 caracteres	Sim	Nome não vazio.
Corpo	`systemKey`	string	Sim	Chave de sistema habilitado no catálogo.
Corpo	`scopes`	array de strings	Não	Até 32 escopos; reservados para autorização futura.
Corpo	`expiresAt`	data ISO 8601	Não	Data futura; omitida significa sem expiração.

Saída

HTTP	Campo	Tipo	Descrição
201	`id`	UUID	ID do token.
201	`name`	string	Nome informado.
201	`systemKey`	string	Sistema vinculado.
201	`token`	string	Segredo completo no formato `nhub_<id>.<segredo>`.

Erros

HTTP	`errorCode`	Condição
400	`VALIDATION_FAILED`	Corpo inválido, expiração passada ou sistema não habilitado.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de máquina ou perfil insuficiente.

`GET /v1/auth/tokens`

Lista os tokens do titular sem revelar segredos.

Autenticação e autorização: Bearer de Pessoa; token de sistema não acessa tokens pessoais.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Cabeçalho	`Authorization`	Bearer JWT	Sim	Credencial de Pessoa.
Query	`cursor`	string	Não	Cursor opaco da página anterior.
Query	`limit`	inteiro de 1 a 200	Não	Padrão: 50.

Saída

HTTP	Campo	Tipo	Descrição
200	`items`	array de tokens	Tokens do titular; sem segredo nem hash.
200	`items[].id`	UUID	ID do token.
200	`items[].name`	string	Nome.
200	`items[].ownerId`	UUID	Titular.
200	`items[].scopes`	array de strings	Escopos declarados.
200	`items[].systemKey`	string ou `null`	Sistema vinculado; `null` em token legado.
200	`items[].expiresAt`	data e hora ISO 8601 ou `null`	Expiração.
200	`items[].revokedAt`	data e hora ISO 8601 ou `null`	Revogação.
200	`items[].lastUsedAt`	data e hora ISO 8601 ou `null`	Último uso registrado.
200	`items[].createdAt`	data e hora ISO 8601	Emissão.
200	`nextCursor`	string ou `null`	`null` indica fim da listagem.

Erros

HTTP	`errorCode`	Condição
400	`VALIDATION_FAILED`	Cursor malformado ou limite fora de 1 a 200.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de sistema.

`DELETE /v1/auth/tokens/:id`

Revoga token do próprio titular.

Autenticação e autorização: Bearer de Pessoa titular; token de sistema não revoga tokens pessoais.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	ID do token.
Cabeçalho	`Authorization`	Bearer JWT	Sim	Credencial de Pessoa.

Saída

HTTP	Campo	Tipo	Descrição
204	—	sem corpo	Token revogado.

Erros

HTTP	`errorCode`	Condição
400	`VALIDATION_FAILED`	ID fora do formato UUID.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de sistema.
404	`NOT_FOUND`	Token inexistente ou de outro titular.

Consulta de autorização

`POST /v1/authorization/document-access`

Informa se um usuário pode ler um documento. Uma negativa retorna allowed: false, sem revelar a existência do documento.

Autenticação e autorização: Bearer token de sistema. A resposta inclui Cache-Control: private, max-age=60.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Corpo	`documentId`	UUID	Sim	Documento consultado.
Corpo	`userId`	UUID	Sim	Usuário cuja leitura é avaliada.

Saída

HTTP	Campo	Tipo	Descrição
200	`allowed`	boolean	Permissão de leitura efetiva.

Erros

HTTP	`errorCode`	Condição
400	`VALIDATION_FAILED`	ID fora do formato UUID.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Chamador autenticado como Pessoa.

Administração de contas

As respostas de conta omitem passwordHash, appwriteSubject, profile legado e a relação interna person.

`GET /v1/users`

Lista contas para administração. Exige Acesso Global ou superior.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Query	`cursor`	string	Não	Cursor opaco da página anterior.
Query	`limit`	inteiro de 1 a 200	Não	Padrão: 50.

Saída

HTTP	Campo	Tipo	Descrição
200	`items`	array de contas	Contas da página.
200	`items[].id`	UUID	ID da conta.
200	`items[].email`	string	E-mail normalizado.
200	`items[].name`	string	Nome de exibição.
200	`items[].accessProfile`	Perfil de Acesso ou `null`	Perfil da conta; `null` durante migração.
200	`items[].personId`	UUID ou `null`	Pessoa titular; `null` durante migração.
200	`items[].active`	boolean	Estado da conta.
200	`items[].createdAt`	data e hora ISO 8601	Criação.
200	`items[].updatedAt`	data e hora ISO 8601	Última atualização.
200	`nextCursor`	string ou `null`	`null` indica fim da lista.

Erros

HTTP	`errorCode`	Condição
400	`VALIDATION_FAILED`	Cursor ou limite inválido.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Perfil insuficiente.

`POST /v1/users`

Cria conta local para uma Pessoa física existente, sem provisionamento Appwrite. Exige Acesso Global ou superior.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Corpo	`personId`	UUID	Sim	Pessoa física titular.
Corpo	`email`	e-mail, até 254 caracteres	Sim	E-mail normalizado.
Corpo	`name`	string, até 120 caracteres	Sim	Nome não vazio.
Corpo	`password`	string, 8 a 72 caracteres	Sim	Senha inicial local.
Corpo	`accessProfile`	Perfil de Acesso	Sim	Perfil da conta.

Saída

HTTP	Campo	Tipo	Descrição
201	`id`	UUID	ID da conta.
201	`email`	string	E-mail normalizado.
201	`name`	string	Nome de exibição.
201	`accessProfile`	Perfil de Acesso ou `null`	Perfil da conta; `null` durante migração.
201	`personId`	UUID ou `null`	Pessoa titular; `null` durante migração.
201	`active`	boolean	Estado da conta.
201	`createdAt`	data e hora ISO 8601	Criação.
201	`updatedAt`	data e hora ISO 8601	Última atualização.

Erros

HTTP	`errorCode`	Condição
400	`VALIDATION_FAILED`	Corpo inválido.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Perfil insuficiente.
409	`CONFLICT`	E-mail ou Pessoa já vinculados.
422	`RULE_VIOLATION`	Pessoa inexistente ou não física.

`GET /v1/users/:id`

Consulta a conta indicada. Acesso Global ou superior pode consultar outras contas; demais Pessoas consultam apenas a própria.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	ID da conta.

Saída

HTTP	Campo	Tipo	Descrição
200	`id`	UUID	ID da conta.
200	`email`	string	E-mail normalizado.
200	`name`	string	Nome de exibição.
200	`accessProfile`	Perfil de Acesso ou `null`	Perfil da conta; `null` durante migração.
200	`personId`	UUID ou `null`	Pessoa titular; `null` durante migração.
200	`active`	boolean	Estado da conta.
200	`createdAt`	data e hora ISO 8601	Criação.
200	`updatedAt`	data e hora ISO 8601	Última atualização.

Erros

HTTP	`errorCode`	Condição
400	`VALIDATION_FAILED`	ID inválido.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Sem acesso à conta de outra Pessoa.
404	`NOT_FOUND`	Conta inexistente.

`PATCH /v1/users/:id`

Atualiza uma conta. Exige Acesso Global ou superior.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Conta alterada.
Corpo	`personId`	UUID	Não	Pessoa física titular.
Corpo	`name`	string, até 120 caracteres	Não	Nome de exibição.
Corpo	`accessProfile`	Perfil de Acesso	Não	Perfil concedido.
Corpo	`active`	boolean	Não	`false` desativa a conta.

Saída

HTTP	Campo	Tipo	Descrição
200	`id`	UUID	ID da conta.
200	`email`	string	E-mail normalizado.
200	`name`	string	Nome de exibição.
200	`accessProfile`	Perfil de Acesso ou `null`	Perfil da conta; `null` durante migração.
200	`personId`	UUID ou `null`	Pessoa titular; `null` durante migração.
200	`active`	boolean	Estado da conta.
200	`createdAt`	data e hora ISO 8601	Criação.
200	`updatedAt`	data e hora ISO 8601	Última atualização.

Erros

HTTP	`errorCode`	Condição
400	`VALIDATION_FAILED`	ID ou corpo inválido.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Perfil insuficiente.
404	`NOT_FOUND`	Conta inexistente.
409	`CONFLICT`	Pessoa já vinculada.
422	`RULE_VIOLATION`	Pessoa inexistente ou não física.

API Reference · Identidade e acesso

Convenções

Cadastro de Pessoa e conta

POST /v1/people

Autenticação local

POST /v1/auth/login

GET /v1/users/me

PATCH /v1/users/me/password

Tokens de sistema

POST /v1/auth/tokens

GET /v1/auth/tokens

DELETE /v1/auth/tokens/:id

Consulta de autorização

POST /v1/authorization/document-access

Administração de contas

GET /v1/users

POST /v1/users

GET /v1/users/:id

PATCH /v1/users/:id

Camadas do domínio

`POST /v1/people`

`POST /v1/auth/login`

`GET /v1/users/me`

`PATCH /v1/users/me/password`

`POST /v1/auth/tokens`

`GET /v1/auth/tokens`

`DELETE /v1/auth/tokens/:id`

`POST /v1/authorization/document-access`

`GET /v1/users`

`POST /v1/users`

`GET /v1/users/:id`

`PATCH /v1/users/:id`