API Reference · Pessoas
Cobertura da interface de Pessoas
O Sitemap registra as operações que cada superfície consome. Aniversariantes, checklist de documentos, escrita de relações, catálogo de Representados e criação de Associação no cadastro não possuem consumidor visual de Pessoas neste escopo.
Convenções
As rotas recebem Authorization: Bearer <credencial>: JWT Appwrite, JWT próprio da API ou token de sistema. As rotas de leitura não exigem Perfil de Acesso mínimo; cada registro é filtrado pelo alcance efetivo do ator, e pessoa fora do alcance responde o mesmo 404 de pessoa inexistente. Token de sistema apenas lê. Todas as operações podem responder 401 UNAUTHORIZED (credencial ausente ou inválida) e 500 INTERNAL (falha não tratada); as tabelas de erros abaixo listam as demais condições de cada operação.
Datas civis usam YYYY-MM-DD; instantes usam ISO 8601. Listas paginadas comuns devolvem { items, nextCursor }, com nextCursor: null na última página; sem resultado, a resposta é { items: [], nextCursor: null }. Operações contadas documentam também totalItems em sua própria saída e devolvem totalItems: 0 quando não há resultado.
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; no 400 de validação, uma mensagem por regra violada. |
errorCode | string | Sempre | Código estável do catálogo: VALIDATION_FAILED (400), RULE_VIOLATION (422), NOT_FOUND (404), FORBIDDEN (403), UNAUTHORIZED (401), CONFLICT (409), UPSTREAM_UNAVAILABLE (503), APPWRITE_UPSTREAM (502), INTERNAL (500). |
error | string | Condicional | Nome do status HTTP; ausente quando a exceção foi lançada com corpo textual. |
Objeto Person — corpo de saída
Base de todas as respostas de pessoa. Na listagem (GET /v1/people e GET /v1/people/birthdays) os itens vêm sem emails, documents e bankAccounts; GET /v1/people acrescenta portfolioId e portfolioLabel para a Carteira vigente de que a pessoa é cliente, ambos null quando não há vínculo. A ficha completa (GET /v1/people/{id}, PATCH /v1/people/{id} e POST /v1/people) traz as três listas e acrescenta os campos projetados listados em Ficha completa.
| Campo | Tipo | Descrição |
|---|---|---|
id | UUID | Identificador da Pessoa. |
personType | FISICA, JURIDICA ou null | Natureza; decide o tamanho do cpfCnpj. |
name | string ou null | Nome da pessoa física. |
companyName | string ou null | Razão social da pessoa jurídica. |
cpfCnpj | string ou null | CPF ou CNPJ só com dígitos; único entre as pessoas. |
hasNoCpfCnpj | boolean | Pessoa declaradamente sem CPF/CNPJ. |
noCpfCnpjReason | string ou null | Justificativa da ausência de CPF/CNPJ. |
identifier | string ou null | Identificador livre. |
identityStatus | confirmado ou pendente | pendente quando a identidade importada precisa de revisão. |
possibleDuplicateOf | array de UUIDs | Candidatas a duplicata. |
nucleos | array de strings | Siglas dos núcleos responsáveis, em maiúsculas. |
roles | array de PersonRole | Papéis na Relação. |
originUoSigla | string ou null | Unidade de origem, em maiúsculas. |
originDate | data civil ou null | Entrada pela unidade de origem. |
originationType | enum ou null | Como a origem foi estabelecida. |
originCity | string ou null | Cidade de origem. |
serviceUnitId | UUID ou null | Unidade de atendimento habitual. Em implementação. |
avatarDocumentId | UUID ou null | Documento usado como foto. Em implementação. |
referredByPersonId | UUID ou null | Pessoa indicadora. |
referralType | PARTNER, SCOUT, CLIENT, ASSOCIATE, INTERNAL ou null | Qualificação da indicação. |
referralChannel | WHATSAPP, INSTAGRAM, PHONE_CALL, IN_PERSON, WEBSITE, OTHER ou null | Canal de chegada. |
birthDate | data civil ou null | Nascimento. |
gender | MALE, FEMALE, OTHER ou null | Gênero declarado. |
generalNotes | string ou null | Observações gerais. |
oabNumber | string ou null | Número da inscrição principal na OAB, de pessoa física ou jurídica (sociedade de advogados; pessoa jurídica a partir de nead-hub-api#84), sempre com oabUf; sem unicidade. |
oabUf | string ou null | UF da inscrição, em maiúsculas; sempre com oabNumber. |
isClient | boolean ou null | Derivado dos processos; apenas a importação o preenche. |
isOpposingParty | boolean ou null | Derivado dos processos; apenas a importação o preenche. |
authorUserId | UUID ou null | Usuário que cadastrou; null após a exclusão do usuário. |
phones | array de PersonPhone | Telefones. |
emails | array de PersonEmail | E-mails; ausente na listagem. |
addresses | array de PersonAddress | Endereços. |
documents | array de PersonIdDocument | Documentos de identificação; ausente na listagem. |
bankAccounts | array de PersonBankAccount | Contas bancárias; ausente na listagem. |
representedParties | array de Representados | Representados da pessoa EXTERNAL_LAWYER, expandidos; [] para as demais. Campos em Representado. |
createdAt | data e hora ISO 8601 | Criação. |
updatedAt | data e hora ISO 8601 | Última atualização. |
Ficha completa — campos projetados
Presentes em GET /v1/people/{id}, PATCH /v1/people/{id} e POST /v1/people, além dos campos de Person.
| Campo | Tipo | Descrição |
|---|---|---|
portfolioId | UUID ou null | Carteira vigente de que a pessoa é cliente (CLIENT). |
ownedPortfolioId | UUID ou null | Carteira de que a pessoa é dona (PARTNER); distinta de portfolioId. |
orgUnitId | UUID ou null | Projeção de vínculo legado entre esta Pessoa e uma Unidade de Negócio. |
Representado — corpo de saída
Usado em representedParties[] e nas operações de /v1/represented-parties.
| Campo | Tipo | Descrição |
|---|---|---|
id | string | Identificador do Representado. |
name | string | Nome como consta no registro. |
kind | COMPANY, PUBLIC_BODY, NONPROFIT, UNION, COOPERATIVE, CONDOMINIUM, INDIVIDUAL ou OTHER | Tipo de Representado. |
authorUserId | string ou null | Usuário que cadastrou; null após a exclusão do usuário. |
createdAt | data e hora ISO 8601 | Criação. |
updatedAt | data e hora ISO 8601 | Última atualização. |
Itens das listas de saída
| Campo | Tipo | Descrição |
|---|---|---|
phones[].id | UUID | Identificador do item. |
phones[].phoneType | string ou null | Tipo do telefone. |
phones[].number | string | Número. |
phones[].isPrimary | boolean ou null | Telefone principal. |
phones[].ownership | SELF, FAMILY, WORK, THIRD_PARTY ou null | Titularidade. |
phones[].contactChannel | CALL_ONLY, MESSAGE_ONLY, BOTH 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 | Endereço. | |
emails[].isPrimary | boolean ou null | 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 | 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. |
documents[].issuingAuthority | string ou null | Órgão emissor. |
documents[].issueDate | data civil ou null | Emissão. |
documents[].createdAt | data e hora ISO 8601 | Criação do item. |
bankAccounts[].id | string | Identificador do item. |
bankAccounts[].bankCode | string | Código COMPE do banco, três dígitos. |
bankAccounts[].bankName | string ou null | Nome do banco. |
bankAccounts[].branchNumber | string | Agência, só dígitos. |
bankAccounts[].branchDigit | string ou null | Dígito da agência. |
bankAccounts[].accountNumber | string | Conta, só dígitos. |
bankAccounts[].accountDigit | string ou null | Dígito da conta. |
bankAccounts[].accountType | CHECKING, SAVINGS, PAYMENT, SALARY ou BENEFIT | Tipo de conta; BENEFIT em implementação. |
bankAccounts[].operation | string ou null | Operação bancária. Em implementação. |
bankAccounts[].notes | string ou null | Observações da conta. Em implementação. |
bankAccounts[].pixKeyType | CPF_CNPJ, EMAIL, PHONE, RANDOM ou null | Tipo da chave Pix. |
bankAccounts[].pixKey | string ou null | Chave Pix. |
bankAccounts[].holderName | string ou null | Titular quando a conta não é da própria pessoa. |
bankAccounts[].isPrimary | boolean | Conta principal; no máximo uma por lista. |
bankAccounts[].createdAt | data e hora ISO 8601 | Criação do item. |
Itens das listas de entrada
Usados em POST /v1/people e PATCH /v1/people/{id}. Cada lista é opcional; enviada, substitui a lista inteira.
| 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. |
phones[].isPrimary | boolean ou null | Não | Telefone principal. |
phones[].ownership | SELF, FAMILY, WORK, THIRD_PARTY ou null | Não | Titularidade. |
phones[].contactChannel | CALL_ONLY, MESSAGE_ONLY, BOTH 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. |
emails[].isPrimary | boolean ou null | Não | 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 | Endereço principal. |
addresses[].referencePoints | array de até 5 strings | Não | Cada ponto 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. |
documents[].issuingAuthority | string ou null, até 120 caracteres | Não | Órgão emissor. |
documents[].issueDate | data civil ou null | Não | Emissão. |
bankAccounts[].bankCode | string, três dígitos | Sim | Código COMPE do banco. |
bankAccounts[].bankName | string ou null, até 120 caracteres | Não | Nome do banco. |
bankAccounts[].branchNumber | string, até 10 caracteres, só dígitos | Sim | Agência. |
bankAccounts[].branchDigit | string ou null, até 2 caracteres | Não | Dígito da agência. |
bankAccounts[].accountNumber | string, até 20 caracteres, só dígitos | Sim | Conta. |
bankAccounts[].accountDigit | string ou null, até 2 caracteres | Não | Dígito da conta. |
bankAccounts[].accountType | CHECKING, SAVINGS, PAYMENT, SALARY ou BENEFIT | Sim | Tipo de conta; BENEFIT em implementação. |
bankAccounts[].operation | string ou null, até 20 caracteres | Não | Operação bancária. Em implementação. |
bankAccounts[].notes | string ou null, até 2000 caracteres | Não | Observações da conta. Em implementação. |
bankAccounts[].pixKeyType | CPF_CNPJ, EMAIL, PHONE, RANDOM ou null | Com pixKey | Tipo da chave Pix. |
bankAccounts[].pixKey | string ou null, até 140 caracteres | Com pixKeyType | Chave Pix. |
bankAccounts[].holderName | string ou null, até 255 caracteres | Não | Titular quando a conta não é da própria pessoa. |
bankAccounts[].isPrimary | boolean | Não | No máximo uma true por lista. |
Registro de histórico (HistoryEntry) — corpo de saída
Usado nos itens de GET /v1/people/{id}/events e GET /v1/people/{id}/history.
| Campo | Tipo | Descrição |
|---|---|---|
id | string | Identificador do registro. |
resourceType | string | Tipo da entidade; person para a própria pessoa. |
resourceId | string | Identificador da entidade. |
resourceLabel | string ou null | Rótulo da entidade. |
action | created, updated, deleted, restored, transitioned, linked, unlinked, imported ou action | Ação registrada. |
eventType | string | Tipo do evento, como person.created e person.updated. |
summary | string | Resumo legível. |
changes | array | Campos alterados. |
changes[].field | string | Nome do campo. |
changes[].label | string | Rótulo do campo. |
changes[].before | string ou null | Valor anterior. |
changes[].after | string ou null | Valor posterior. |
changes[].beforeTruncated | boolean | Valor anterior truncado. |
changes[].afterTruncated | boolean | Valor posterior truncado. |
metadata | objeto | Metadados do evento. |
actorKind | user, machine ou system | Natureza do ator. |
actorUserId | string ou null | Usuário ator. |
actorLabel | string | Rótulo do ator. |
occurredAt | data e hora ISO 8601 | Momento do acontecimento, distinto do registro. |
createdAt | data e hora ISO 8601 | Registro. |
Cadastro, listagem e ficha
POST /v1/people
Cadastra uma pessoa com os filhos embutidos e, conforme os papéis, as entidades que nascem com ela na mesma transação: Cliente da Carteira (CLIENT), Carteira própria (PARTNER), Conta da Pessoa com identidade Appwrite (account), Associação (association) e vínculos de Representação (representedPartyIds). cpfCnpj é guardado só com dígitos e originUoSigla em maiúsculas; originationType vale DECLARED_MANUAL quando a sigla chega sem tipo.
Autenticação e autorização: Bearer de usuário pessoal com Acesso de Núcleo ou superior. CLIENT e association exigem gestão institucional EXPINS; account exige Acesso Global.
Entrada — JSON
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Corpo | personType | FISICA ou JURIDICA, aceita null | Não | Decide o tamanho do cpfCnpj; com account, FISICA. |
| Corpo | name | string até 255, aceita null | Condicional | name ou companyName é obrigatório. |
| Corpo | companyName | string até 255, aceita null | Condicional | name ou companyName é obrigatório. |
| Corpo | cpfCnpj | string, aceita null | Não | Com ou sem máscara; guardado só com dígitos (R9). |
| Corpo | hasNoCpfCnpj | boolean | Não | Incompatível com cpfCnpj. |
| Corpo | noCpfCnpjReason | string até 120, aceita null | Não | Justificativa da ausência. |
| Corpo | identifier | string até 40, aceita null | Não | Identificador livre. |
| Corpo | identityStatus | confirmado ou pendente | Não | Estado da identidade. |
| Corpo | possibleDuplicateOf | array de UUIDs | Não | Candidatas a duplicata. |
| Corpo | nucleos | array de strings, cada uma até 16 | Não | Normalizadas em maiúsculas; precisam existir. |
| Corpo | roles | array de PersonRole | Não | Normalizados em maiúsculas; novas atribuições de HEADQUARTERS_UNIT são recusadas. |
| Corpo | portfolioId | UUID | Com CLIENT | Carteira do novo cliente. |
| Corpo | portfolioEffectiveFrom | data civil | Com CLIENT | Primeiro dia do vínculo; até hoje. |
| Corpo | originUoSigla | string até 40, aceita null | Com CLIENT | Normalizada em maiúsculas; LSA é recusada. |
| Corpo | originDate | data civil, aceita null | Não | Entrada pela unidade de origem. |
| Corpo | originationType | enum, aceita null | Não | DECLARED_MANUAL quando omitido junto de originUoSigla. |
| Corpo | originCity | string até 120, aceita null | Não | Cidade de origem. |
| Corpo | serviceUnitId | UUID, aceita null | Não | Unidade de atendimento habitual; precisa ser unidade cadastrada (RN-PESSOAS-056). Em implementação. |
| Corpo | avatarDocumentId | UUID, aceita null | Não | Documento usado como foto; precisa existir (RN-PESSOAS-057). Em implementação. |
| Corpo | referredByPersonId | UUID, aceita null | Não | Precisa existir. |
| Corpo | referralType | PARTNER, SCOUT, CLIENT, ASSOCIATE, INTERNAL, aceita null | Não | Exige referredByPersonId. |
| Corpo | referralChannel | WHATSAPP, INSTAGRAM, PHONE_CALL, IN_PERSON, WEBSITE, OTHER, aceita null | Não | Canal de chegada. |
| Corpo | birthDate | data civil, aceita null | Não | Nascimento. |
| Corpo | gender | MALE, FEMALE, OTHER, aceita null | Não | Gênero declarado. |
| Corpo | generalNotes | string até 20000, aceita null | Não | Observações gerais. |
| Corpo | oabNumber | string até 20, aceita null | Condicional | Sempre junto de oabUf. Pessoa física ou jurídica (sociedade de advogados) a partir de nead-hub-api#84; até lá, só pessoa física. Exigido com o papel EXTERNAL_LAWYER a partir de nead-hub-api#84 (no cadastro; na edição, só quando a alteração cria a falta) (RN-PESSOAS-046). |
| Corpo | oabUf | string, aceita null | Condicional | Normalizada em maiúsculas; duas letras (^[A-Z]{2}$, fora disso 400); sempre junto de oabNumber. |
| Corpo | representedPartyIds | array de UUIDs | Não | Exige EXTERNAL_LAWYER quando não vazio; cada id precisa existir; repetição responde 400. |
| Corpo | phones | array de telefones | Não | Ver Itens das listas de entrada. |
| Corpo | emails | array de e-mails | Não | Ver Itens das listas de entrada. |
| Corpo | addresses | array de endereços | Não | Ver Itens das listas de entrada. |
| Corpo | documents | array de documentos | Não | Ver Itens das listas de entrada. |
| Corpo | bankAccounts | array de contas bancárias | Não | Ver Itens das listas de entrada; no máximo uma isPrimary. |
| Corpo | account | objeto | Não | Conta da Pessoa aberta junto com o cadastro; exige USER ou ASSOCIATE e pessoa física. |
| Corpo | account.email | e-mail até 254 | Com account | Normalizado em minúsculas. |
| Corpo | account.password | string de 8 a 72 | Com account | Senha inicial. |
| Corpo | account.accessProfile | admin-do-sistema, acesso-global, acesso-de-area, acesso-de-nucleo, operacional-autonomo ou operacional-restrito | Com account | Perfil de Acesso concedido. |
| Corpo | association | objeto | Não | Associação aberta junto com o cadastro; exige ASSOCIATE e pessoa física. |
| Corpo | association.sigla | string até 40, não vazia | Com association | Sigla única e imutável. |
| Corpo | association.lamarckPercentage | string decimal com quatro casas (^(?:0|[1-9]\d{0,2})\.\d{4}$) | Com association | Quota institucional, entre 50.0000 e 100.0000. |
| Corpo | association.percentage | string decimal com quatro casas | Não | Participação da pessoa; ausente, 100.0000 menos lamarckPercentage. |
| Corpo | association.name | string até 255, não vazia | Não | Rótulo da Associação. |
| Corpo | association.effectiveFrom | data civil | Não | Primeiro dia inclusivo; ausente, hoje. |
| Corpo | association.effectiveTo | data civil | Não | Último dia inclusivo; ausente mantém aberta. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 201 | Campos de Person e da ficha completa | Ver Convenções | Pessoa criada com os filhos, portfolioId, ownedPortfolioId, orgUnitId: null, representedParties e bankAccounts. |
| 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 em minúsculas. |
| 201 | account.accessProfile | Perfil de Acesso | Perfil concedido. |
| 201 | account.active | boolean | Estado da conta. |
| 201 | association | objeto ou null | null quando não solicitada. |
| 201 | association.id | UUID | Identificador da Associação. |
| 201 | association.versionId | UUID | Versão inicial. |
| 201 | association.portfolioId | UUID | Carteira vazia criada para a Associação. |
| 201 | association.sigla | string | Sigla em maiúsculas. |
| 201 | association.name | string | Rótulo. |
| 201 | association.effectiveFrom | data civil | Início inclusivo. |
| 201 | association.effectiveTo | data civil ou null | Fim inclusivo; null aberta. |
| 201 | association.lamarckPercentage | string decimal | Quota institucional. |
| 201 | association.percentage | string decimal | Participação da pessoa. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | Corpo inválido: cpfCnpj fora da regra R9 ou junto de hasNoCpfCnpj, papel fora do vocabulário, bloco orgUnit ou filho malformado. |
| 403 | FORBIDDEN | Perfil abaixo de Acesso de Núcleo; CLIENT ou association sem gestão institucional EXPINS; account abaixo de Acesso Global; token de sistema. |
| 404 | NOT_FOUND | portfolioId inexistente para CLIENT. |
| 409 | CONFLICT | cpfCnpj já pertence a outra pessoa; e-mail de account já cadastrado; sigla de association já cadastrada. |
| 422 | RULE_VIOLATION | Sem name nem companyName; núcleo inexistente; CLIENT sem originUoSigla, portfolioId ou data civil; dono da carteira sem vigência aberta; sigla inválida; indicação inconsistente; nova atribuição de HEADQUARTERS_UNIT; account sem papel USER ou ASSOCIATE ou sem pessoa física; association sem ASSOCIATE, sem pessoa física, com período invertido ou com quotas que não somam 100; representedPartyIds sem EXTERNAL_LAWYER ou com id inexistente; OAB sem par; OAB em pessoa jurídica (até nead-hub-api#84, RN-PESSOAS-046); EXTERNAL_LAWYER sem OAB (a partir de nead-hub-api#84); mais de uma conta bancária principal; Pix sem par; serviceUnitId que não é unidade cadastrada ou avatarDocumentId que não é Documento cadastrado (em implementação). |
| 500 | INTERNAL | Falha de persistência ou de provedor de mutação; pessoa, evento, vínculo, conta e associação revertidos. |
| 502 | APPWRITE_UPSTREAM | Appwrite recusou a identidade de account; nada é persistido. |
| 503 | UPSTREAM_UNAVAILABLE | account solicitado com a integração Appwrite desligada. |
GET /v1/people
Página alfabética do golden record (nameSortKey, id; pessoa sem nome abre a lista), já escopada no banco. Busca e filtros só estreitam o que o ator alcança. Os itens vêm sem emails, documents e bankAccounts.
Autenticação e autorização: Bearer autenticado; alcance efetivo aplicado registro a registro. Ler a Pessoa autoriza ver, somente naquela linha, o identificador e o rótulo de sua Carteira vigente. Essa projeção não concede acesso ao catálogo, à ficha nem aos demais clientes da Carteira.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Query | cursor | string | Não | Cursor opaco devolvido em nextCursor. |
| Query | limit | number de 1 a 200 | Não, padrão 50 | Tamanho da página. |
| Query | search | string até 200 | Não | Nome, razão social, CPF/CNPJ (com ou sem máscara), telefone, e-mail primário e inscrição na OAB, ignorando caixa e acento; o termo é quebrado em até 6 palavras, e a pessoa precisa conter todas; termo com menos de 2 caracteres é ignorado. Palavra formada só por dígitos e +().-, com ao menos 2 dígitos, compara apenas os dígitos com os telefones, com ou sem máscara. |
| Query | oabNumber | string de 1 a 20 | Não | Número da inscrição na OAB, igualdade exata. |
| Query | role | array de PersonRole, repetindo o parâmetro | Não | Vários papéis combinam em OU; o eixo combina em E com os demais filtros. |
| Query | nucleo | string | Não | Sigla de um núcleo, caixa indiferente; desconhecida devolve página vazia. |
| Query | originUoSigla | string de 1 a 40 | Não | Igualdade exata, caixa indiferente. |
| Query | referredByPersonId | UUID | Não | Igualdade exata; indicar não concede leitura. |
| Query | originCity | string de 1 a 120 | Não | Igualdade exata, sem dobra de caixa ou acento. |
| Query | referralChannel | WHATSAPP, INSTAGRAM, PHONE_CALL, IN_PERSON, WEBSITE ou OTHER | Não | Igualdade exata. |
| Query | createdFrom | ISO 8601 | Não | Início inclusivo do cadastro no hub (createdAt); data sem hora conta como meia-noite UTC. |
| Query | createdTo | ISO 8601 | Não | Fim inclusivo do cadastro no hub. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | items | array de PersonListItemDto | Campos de Person, sem emails, documents e bankAccounts, mais portfolioId (UUID da Carteira vigente ou null) e portfolioLabel (sigla da unidade/associação ou nome da pessoa parceira dona da Carteira, com o tipo do dono; null sem vínculo). Vínculo inconsistente — mais de uma Carteira vigente ou dono indisponível — não interrompe a listagem: a pessoa sai com os dois campos null e a inconsistência fica registrada no log da API. |
| 200 | nextCursor | string ou null | Cursor da próxima página; null na última. |
| 200 | totalItems | número inteiro não negativo | Total de pessoas sob o mesmo alcance e filtros, sem aplicar cursor nem limite. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | Cursor malformado; role ou referralChannel fora do vocabulário; nucleo fora de 1 a 16 caracteres; referredByPersonId fora do formato UUID; createdFrom ou createdTo fora do ISO 8601; limit fora de 1 a 200. |
GET /v1/people/birthdays
Aniversariantes de um dia, sob o mesmo escopo da listagem, em ordem de cadastro. Só mês e dia contam.
Autenticação e autorização: Bearer autenticado; alcance efetivo aplicado registro a registro.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Query | date | data civil | Não | Ano ignorado; omitido, hoje em America/Recife. |
| Query | cursor | string | Não | Cursor opaco devolvido em nextCursor. |
| Query | limit | number de 1 a 200 | Não, padrão 50 | Tamanho da página. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | date | data civil | Dia consultado. |
| 200 | items | array de Person | Aniversariantes; sem emails, documents e bankAccounts. |
| 200 | nextCursor | string ou null | Cursor da próxima página. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | date fora do formato ou dia inexistente; cursor malformado; limit fora de 1 a 200. |
GET /v1/people/{id}
A ficha completa: a pessoa com todos os filhos, representedParties expandidos e os campos projetados portfolioId, ownedPortfolioId e orgUnitId.
Autenticação e autorização: Bearer autenticado; pessoa no alcance do ator.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | id | UUID | Sim | Identificador da Pessoa. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | Campos de Person e da ficha completa | Ver Convenções | Pessoa com os filhos, portfolioId, ownedPortfolioId, orgUnitId, representedParties e bankAccounts. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | id fora do formato UUID. |
| 404 | NOT_FOUND | Pessoa inexistente ou fora do alcance do ator. |
PATCH /v1/people/{id}
Altera campos e substitui as listas de filhos presentes no corpo (omitir mantém, [] apaga). Os campos de originação só a presidência altera depois do cadastro. Cada campo cujo valor difere do gravado entra em person.updated. Ganhar o papel PARTNER cria a Carteira própria; perdê-lo a apaga, ou responde 422 se ela já teve cliente.
Autenticação e autorização: Bearer de usuário pessoal com a pessoa no alcance; campos de originação exigem PRES ou acesso institucional; transição de CLIENT exige gestão institucional EXPINS.
Entrada — JSON
Aceita os mesmos campos de POST /v1/people, exceto account e association, todos opcionais, e acrescenta portfolioEffectiveTo.
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | id | UUID | Sim | Identificador da Pessoa. |
| Corpo | Campos de POST /v1/people, exceto account e association | Ver POST /v1/people | Não | Apenas os campos enviados mudam; representedPartyIds substitui o conjunto inteiro e [] desvincula todos. |
| Corpo | portfolioId | UUID | Ao conceder CLIENT | Carteira do cliente. |
| Corpo | portfolioEffectiveFrom | data civil | Ao conceder CLIENT | Primeiro dia do vínculo; até hoje. |
| Corpo | portfolioEffectiveTo | data civil YYYY-MM-DD | Ao retirar CLIENT | Último dia inclusivo do vínculo; ontem civil. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | Campos de Person e da ficha completa | Ver Convenções | Ficha completa atualizada, com portfolioId, ownedPortfolioId, orgUnitId, representedParties e bankAccounts. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | id fora do formato UUID ou corpo inválido (cpfCnpj fora da regra R9, papel fora do vocabulário, bloco orgUnit, filho malformado). |
| 403 | FORBIDDEN | Campo de originação fora da presidência; transição de CLIENT sem gestão institucional EXPINS; token de sistema. |
| 404 | NOT_FOUND | Pessoa inexistente ou fora do alcance; portfolioId inexistente na promoção a CLIENT. |
| 409 | CONFLICT | cpfCnpj duplicado; vínculo de carteira concorrente; pessoa alterada concorrentemente. |
| 422 | RULE_VIOLATION | Promoção a CLIENT sem origem, portfolioId ou data; remoção sem portfolioEffectiveTo igual a ontem civil; troca de carteira por PATCH; dono sem vigência; nova atribuição de HEADQUARTERS_UNIT; remoção de PARTNER com clientes na Carteira; remoção de EXTERNAL_LAWYER com Representados sem enviar []; representedPartyIds sem EXTERNAL_LAWYER ou com id inexistente; OAB sem par; OAB em pessoa jurídica (até nead-hub-api#84, RN-PESSOAS-046); edição que acrescenta EXTERNAL_LAWYER sem OAB ou apaga a OAB de quem tem o papel (a partir de nead-hub-api#84); mais de uma conta bancária principal; Pix sem par; serviceUnitId ou avatarDocumentId alterado para referência inexistente (em implementação); demais regras de Pessoa. |
| 500 | INTERNAL | Provedor de mutação inválido ou falha de persistência; pessoa, evento e vínculo revertidos. |
Trilha e histórico
GET /v1/people/{id}/events
Trilha da pessoa, do evento mais recente ao mais antigo, sob a mesma leitura do registro. Pessoa sem eventos responde { items: [], nextCursor: null }.
Autenticação e autorização: Bearer autenticado; pessoa no alcance do ator.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | id | UUID | Sim | Identificador da Pessoa. |
| Query | cursor | string | Não | Cursor opaco devolvido em nextCursor. |
| Query | limit | number de 1 a 200 | Não, padrão 50 | Tamanho da página. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | items | array de HistoryEntry | Ver Convenções. |
| 200 | nextCursor | string ou null | Cursor da próxima página. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | id fora do formato UUID ou cursor inválido. |
| 404 | NOT_FOUND | Pessoa inexistente ou fora do alcance do ator. |
GET /v1/people/{id}/history
Linha do tempo única da pessoa, incluindo entrevistas e demais vínculos.
Autenticação e autorização: Bearer autenticado; pessoa no alcance do ator.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | id | UUID | Sim | Identificador da Pessoa. |
| Query | cursor | string | Não | Cursor opaco devolvido em nextCursor. |
| Query | limit | number de 1 a 200 | Não, padrão 50 | Tamanho da página. |
| Query | resourceType | string no padrão ^[a-z][a-z0-9-]{0,63}$ | Não | Restringe a um tipo de entidade. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | items | array de HistoryEntry | Ver Convenções. |
| 200 | nextCursor | string ou null | Cursor da próxima página. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | id fora do formato UUID, cursor ou filtro inválido. |
| 404 | NOT_FOUND | Pessoa inexistente ou fora do alcance do ator. |
Relacionamentos entre pessoas
GET /v1/people/{personId}/relationships
Relações da âncora, do ponto de vista dela, em ordem de criação. relationType pode ser um tipo de leitura que não existe no banco.
Autenticação e autorização: Bearer autenticado; âncora no alcance do ator.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | personId | UUID | Sim | Pessoa âncora. |
| Query | cursor | string | Não | Cursor opaco devolvido em nextCursor. |
| Query | limit | number de 1 a 200 | Não, padrão 50 | Tamanho da página. |
| Query | expand | true ou false | Não | true resolve a contraparte em person; ausente ou false, person não sai. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | items[].id | string | Identificador da relação, o mesmo pelas duas pontas. |
| 200 | items[].relationType | enum de 21 valores | Laço do ponto de vista da âncora para personId. |
| 200 | items[].personId | string | Outra ponta; sempre presente. |
| 200 | items[].note | string ou null | Observação livre. |
| 200 | items[].authorUserId | string ou null | Usuário que registrou; null após a exclusão do usuário. |
| 200 | items[].createdAt | data e hora ISO 8601 | Registro. |
| 200 | items[].person | objeto | Apenas com expand=true. |
| 200 | items[].person.id | string | Contraparte. |
| 200 | items[].person.name | string ou null | Nome ou razão social; null fora do alcance do ator ou sem nome. |
| 200 | nextCursor | string ou null | Cursor da próxima página. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | personId fora do formato UUID, cursor inválido ou expand fora de true/false. |
| 404 | NOT_FOUND | Pessoa inexistente ou fora do alcance do ator. |
POST /v1/people/{personId}/relationships
Registra a relação a partir de qualquer ponta: PARENT de A para B e CHILD de B para A gravam a mesma linha, na forma canônica. Responde a relação vista da âncora.
Autenticação e autorização: Bearer de usuário pessoal com alteração da âncora; a contraparte só precisa existir.
Entrada — JSON
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | personId | UUID | Sim | Pessoa âncora. |
| Corpo | personId | UUID | Sim | Outra ponta; precisa existir e ser diferente da âncora. |
| Corpo | relationType | SPOUSE, SIBLING, COUSIN, SIBLING_IN_LAW, FRIEND, PARENT, CHILD, GRANDPARENT, GRANDCHILD, UNCLE_AUNT, NEPHEW_NIECE, PARENT_IN_LAW, CHILD_IN_LAW, LEGAL_GUARDIAN, WARD, ADOPTIVE_PARENT, ADOPTED_CHILD, TUTOR, TUTELAGE_WARD, CURATOR ou CURATORSHIP_WARD | Sim | Laço do ponto de vista da âncora para a outra ponta. |
| Corpo | note | string até 255 | Não | Observação livre. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 201 | id | string | Identificador da relação. |
| 201 | relationType | enum | Laço do ponto de vista da âncora. |
| 201 | personId | string | Outra ponta. |
| 201 | note | string ou null | Observação livre. |
| 201 | authorUserId | string ou null | Usuário que registrou. |
| 201 | createdAt | data e hora ISO 8601 | Registro. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | personId fora do formato UUID ou corpo inválido (relationType fora do vocabulário, note acima de 255). |
| 404 | NOT_FOUND | Âncora inexistente ou fora do alcance do ator. |
| 409 | CONFLICT | Relação já existente, pedida por qualquer ponta, ou contradição com relação registrada entre as mesmas pessoas; message nomeia o id e o tipo. |
| 422 | RULE_VIOLATION | Autorrelação ou personId do corpo que não é uma pessoa cadastrada. |
DELETE /v1/people/{personId}/relationships/{relationshipId}
Apaga a relação; ela some das duas pontas.
Autenticação e autorização: Bearer de usuário pessoal com alteração da âncora.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | personId | UUID | Sim | Pessoa âncora. |
| Caminho | relationshipId | UUID | Sim | Relação da âncora. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 204 | — | Sem corpo | Relação apagada. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | personId ou relationshipId fora do formato UUID. |
| 404 | NOT_FOUND | Âncora inexistente ou fora do alcance; relação inexistente ou que não é da âncora. |
Registros de relacionamento
Estado: em implementação na API.
Criação, alteração e exclusão gravam no histórico da Pessoa o registro como ficou ou, na exclusão, como estava, em metadata (type, content, preferenceCategory, attentionKind, caseId, detail). A linha do tempo desses registros é lida por GET /v1/people/{id}/history?resourceType=person-relationship-record.
GET /v1/people/{personId}/relationship-records
Lista os registros de relacionamento da Pessoa do mais recente ao mais antigo (createdAt e id decrescentes), paginados por cursor.
Autenticação e autorização: Bearer autenticado; Pessoa no alcance de leitura do ator.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | personId | UUID | Sim | Pessoa dona dos registros. |
| Query | cursor | string | Não | Cursor opaco devolvido em nextCursor. |
| Query | limit | number de 1 a 200 | Não, padrão 50 | Tamanho da página. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | items[].id | UUID | Identificador do registro. |
| 200 | items[].personId | UUID | Pessoa dona do registro. |
| 200 | items[].type | EXPECTATION, PREFERENCE, AFFINITY ou ATTENTION | Expectativa, Preferência, Afinidade ou Atenção. |
| 200 | items[].content | string | Texto do registro. |
| 200 | items[].preferenceCategory | SERVICE_CHANNEL, COMMUNICATION_FORM, SERVICE_HOURS, OTHER ou null | Categoria da preferência; só em PREFERENCE. Em implementação. |
| 200 | items[].attentionKind | DOCUMENTS, EXPERT_EXAM, HEARING, FEES, CALL_IN, APPOINTMENT ou null | Tipo da etiqueta; só em ATTENTION. Em implementação. |
| 200 | items[].caseId | UUID ou null | Processo em que a pessoa é cliente; só em EXPECTATION; null após a exclusão do processo. Em implementação. |
| 200 | items[].detail | string ou null | Relato completo em AFFINITY; processo, data, local ou outra informação em ATTENTION. Em implementação. |
| 200 | items[].authorUserId | UUID ou null | Autor; null após a exclusão do usuário. |
| 200 | items[].createdAt | data e hora ISO 8601 | Data do registro. |
| 200 | items[].updatedAt | data e hora ISO 8601 | Data da última alteração. |
| 200 | nextCursor | string ou null | Cursor da próxima página. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | personId fora do formato UUID ou cursor inválido. |
| 401 | UNAUTHORIZED | Sem credencial válida. |
| 403 | FORBIDDEN | Alcance efetivo do ator indisponível ou inválido. |
| 404 | NOT_FOUND | Pessoa inexistente ou fora do alcance do ator. |
| 500 | INTERNAL | Falha não tratada. |
POST /v1/people/{personId}/relationship-records
Cria um registro de relacionamento e grava person-relationship-record.created no histórico da Pessoa.
Autenticação e autorização: Bearer de usuário pessoal com a mesma autorização de edição da Pessoa (RN-PESSOAS-062).
Entrada — JSON
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | personId | UUID | Sim | Pessoa dona do registro. |
| Corpo | type | EXPECTATION, PREFERENCE, AFFINITY ou ATTENTION | Sim | Tipo do registro. |
| Corpo | content | string não vazia, até 2000 | Sim | Texto do registro; gravado aparado. |
| Corpo | preferenceCategory | SERVICE_CHANNEL, COMMUNICATION_FORM, SERVICE_HOURS ou OTHER, aceita null | Não | Só em PREFERENCE. Em implementação. |
| Corpo | attentionKind | DOCUMENTS, EXPERT_EXAM, HEARING, FEES, CALL_IN ou APPOINTMENT, aceita null | Com ATTENTION | Só em ATTENTION, e obrigatório nele. Em implementação. |
| Corpo | caseId | UUID, aceita null | Não | Só em EXPECTATION; processo em que a pessoa é cliente. Em implementação. |
| Corpo | detail | string até 5000, aceita null | Não | Só em AFFINITY e ATTENTION; gravado aparado. Em implementação. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 201 | id, personId, type, content, preferenceCategory, attentionKind, caseId, detail, authorUserId, createdAt, updatedAt | Ver GET | Registro criado com o mesmo schema de items[] da listagem; authorUserId é o ator. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | personId fora do formato UUID; type fora do vocabulário; content vazio ou acima de 2000. |
| 401 | UNAUTHORIZED | Sem credencial válida. |
| 403 | FORBIDDEN | Token de sistema. |
| 404 | NOT_FOUND | Pessoa inexistente ou fora do alcance do ator. |
| 422 | RULE_VIOLATION | Campo enviado a tipo que não o aceita; ATTENTION sem attentionKind; caseId de processo em que a pessoa não é cliente. Em implementação. |
| 500 | INTERNAL | Falha não tratada. |
PATCH /v1/people/{personId}/relationship-records/{id}
Altera o tipo, o texto ou os campos próprios do tipo e grava person-relationship-record.updated no histórico da Pessoa. Campo ausente não muda.
Autenticação e autorização: Bearer de usuário pessoal com a mesma autorização de edição da Pessoa (RN-PESSOAS-062).
Entrada — JSON
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | personId | UUID | Sim | Pessoa dona do registro. |
| Caminho | id | UUID | Sim | Registro alterado. |
| Corpo | type | EXPECTATION, PREFERENCE, AFFINITY ou ATTENTION | Não | Novo tipo. |
| Corpo | content | string não vazia, até 2000 | Não | Novo texto; gravado aparado. |
| Corpo | preferenceCategory | SERVICE_CHANNEL, COMMUNICATION_FORM, SERVICE_HOURS ou OTHER, aceita null | Não | Só em PREFERENCE. Em implementação. |
| Corpo | attentionKind | DOCUMENTS, EXPERT_EXAM, HEARING, FEES, CALL_IN ou APPOINTMENT, aceita null | Não | Só em ATTENTION, e obrigatório nele. Em implementação. |
| Corpo | caseId | UUID, aceita null | Não | Só em EXPECTATION; processo em que a pessoa é cliente. Em implementação. |
| Corpo | detail | string até 5000, aceita null | Não | Só em AFFINITY e ATTENTION; gravado aparado. Em implementação. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | id, personId, type, content, preferenceCategory, attentionKind, caseId, detail, authorUserId, createdAt, updatedAt | Ver GET | Registro alterado com o mesmo schema de items[] da listagem. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | personId ou id fora do formato UUID; corpo inválido. |
| 401 | UNAUTHORIZED | Sem credencial válida. |
| 403 | FORBIDDEN | Token de sistema. |
| 404 | NOT_FOUND | Pessoa inexistente ou fora do alcance; registro inexistente ou de outra Pessoa. |
| 422 | RULE_VIOLATION | Campo enviado a tipo que não o aceita; ATTENTION sem attentionKind; caseId de processo em que a pessoa não é cliente. Em implementação. |
| 500 | INTERNAL | Falha não tratada. |
DELETE /v1/people/{personId}/relationship-records/{id}
Exclui o registro e grava person-relationship-record.deleted no histórico da Pessoa.
Autenticação e autorização: Bearer de usuário pessoal com a mesma autorização de edição da Pessoa (RN-PESSOAS-062).
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | personId | UUID | Sim | Pessoa dona do registro. |
| Caminho | id | UUID | Sim | Registro excluído. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 204 | — | Sem corpo | Registro excluído. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | personId ou id fora do formato UUID. |
| 401 | UNAUTHORIZED | Sem credencial válida. |
| 403 | FORBIDDEN | Token de sistema. |
| 404 | NOT_FOUND | Pessoa inexistente ou fora do alcance; registro inexistente ou de outra Pessoa. |
| 500 | INTERNAL | Falha não tratada. |
Notas de atendimento
Estado: em implementação na API.
A nota de atendimento é o registro simplificado feito na Ficha da Pessoa: texto, forma, quem iniciou, finalidade, satisfação, autor e data. Ela usa os vocabulários de modo, canal, direção e finalidade do Registro de Atendimento, mas não é um Registro de Atendimento (/v1/service-records) e não tem unidade, núcleo, assuntos nem ciclo de vida (RN-PESSOAS-066).
GET /v1/people/{personId}/service-notes
Lista as notas de atendimento da Pessoa do mais recente ao mais antigo (createdAt e id decrescentes), paginadas por cursor.
Autenticação e autorização: Bearer autenticado; Pessoa no alcance de leitura do ator.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | personId | UUID | Sim | Pessoa atendida. |
| Query | cursor | string | Não | Cursor opaco devolvido em nextCursor. |
| Query | limit | number de 1 a 200 | Não, padrão 50 | Tamanho da página. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | items[].id | UUID | Identificador da nota. |
| 200 | items[].personId | UUID | Pessoa atendida. |
| 200 | items[].content | string | O que foi tratado no atendimento: texto ou HTML do editor da ficha, com menções. |
| 200 | items[].mode | PRESENCIAL, REMOTO ou null | Forma do atendimento; null só em nota registrada antes do campo. |
| 200 | items[].channel | WHATSAPP, TELEFONE, VIDEOCONFERENCIA, EMAIL, REDE_SOCIAL ou null | Canal remoto; null quando presencial ou em nota registrada antes do campo. |
| 200 | items[].direction | INBOUND, OUTBOUND ou null | Quem iniciou: INBOUND (Recebido) ou OUTBOUND (Realizado); null só em nota registrada antes do campo. |
| 200 | items[].purpose | AVULSO, ENTREVISTA_INAUGURAL, ACOMPANHAMENTO, SOLICITACAO, ORIENTACAO, FINANCEIRO ou null | Finalidade; null quando não informada. |
| 200 | items[].satisfaction | SATISFEITO, INDIFERENTE, INSATISFEITO, CRITICO, SEM_RESPOSTA ou null | Satisfação da pessoa; null quando não informada. |
| 200 | items[].authorUserId | UUID ou null | Usuário que registrou; null após a exclusão do usuário. |
| 200 | items[].createdAt | data e hora ISO 8601 | Data do atendimento: o instante do registro. |
| 200 | nextCursor | string ou null | Cursor da próxima página. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | personId fora do formato UUID ou cursor inválido. |
| 401 | UNAUTHORIZED | Sem credencial válida. |
| 403 | FORBIDDEN | Alcance efetivo do ator indisponível ou inválido. |
| 404 | NOT_FOUND | Pessoa inexistente ou fora do alcance do ator. |
| 500 | INTERNAL | Falha não tratada. |
POST /v1/people/{personId}/service-notes
Registra uma nota de atendimento e grava person-service-note.created no histórico da Pessoa.
Autenticação e autorização: Bearer de usuário pessoal com a autorização de edição da Pessoa.
Entrada — JSON
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | personId | UUID | Sim | Pessoa atendida. |
| Corpo | content | string com texto, até 20000 | Sim | O que foi tratado: texto ou o HTML do editor da ficha, como o relato da entrevista, com menções; gravado aparado. Marcação sem texto (<p></p>) é recusada. |
| Corpo | mode | PRESENCIAL ou REMOTO | Sim | Forma do atendimento. |
| Corpo | channel | WHATSAPP, TELEFONE, VIDEOCONFERENCIA, EMAIL ou REDE_SOCIAL, aceita null | Com REMOTO | Canal remoto; obrigatório quando mode é REMOTO e ausente (ou null) quando é PRESENCIAL. |
| Corpo | direction | INBOUND ou OUTBOUND | Sim | Quem iniciou: INBOUND (Recebido) ou OUTBOUND (Realizado). |
| Corpo | purpose | AVULSO, ENTREVISTA_INAUGURAL, ACOMPANHAMENTO, SOLICITACAO, ORIENTACAO ou FINANCEIRO, aceita null | Não | Finalidade, um único valor. |
| Corpo | satisfaction | SATISFEITO, INDIFERENTE, INSATISFEITO, CRITICO ou SEM_RESPOSTA, aceita null | Não | Satisfação da pessoa. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 201 | id, personId, content, mode, channel, direction, purpose, satisfaction, authorUserId, createdAt | Ver GET | Nota registrada; authorUserId é o ator. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | personId fora do formato UUID; corpo inválido, sem mode ou direction, ou com valor fora dos vocabulários. |
| 401 | UNAUTHORIZED | Sem credencial válida. |
| 403 | FORBIDDEN | Token de sistema. |
| 404 | NOT_FOUND | Pessoa inexistente, fora do alcance ou sem permissão de editá-la. |
| 422 | RULE_VIOLATION | mode REMOTO sem channel, ou mode PRESENCIAL com channel. |
| 500 | INTERNAL | Falha não tratada. |
Resumo do Relacionamento
Estado: em implementação na API.
Texto gerado a partir dos registros de relacionamento da Pessoa, conforme RN-PESSOAS-068.
GET /v1/people/{personId}/relationship-summary
Lê o último resumo e informa se ele reflete os dados atuais. Ler nunca gera texto.
Autenticação e autorização: Bearer autenticado; Pessoa no alcance de leitura do ator.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | personId | UUID | Sim | Pessoa resumida. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | text | string ou null | Último texto gerado; null quando ainda não houve geração. |
| 200 | generatedAt | data e hora ISO 8601 ou null | Quando o texto foi gerado; null sem texto. |
| 200 | upToDate | boolean | true quando o texto reflete os dados atuais; false pede POST …/refresh. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | personId fora do formato UUID. |
| 401 | UNAUTHORIZED | Sem credencial válida. |
| 404 | NOT_FOUND | Pessoa inexistente ou fora do alcance do ator. |
| 500 | INTERNAL | Falha não tratada. |
POST /v1/people/{personId}/relationship-summary/refresh
Avalia a mudança dos dados de origem e gera novo resumo somente quando ela é material (RN-PESSOAS-068). Não recebe corpo.
Autenticação e autorização: Bearer de usuário pessoal; Pessoa no alcance de leitura do ator.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | personId | UUID | Sim | Pessoa resumida. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | text | string ou null | Último texto gerado; null quando ainda não houve geração. |
| 200 | generatedAt | data e hora ISO 8601 ou null | Quando o texto foi gerado; null sem texto. |
| 200 | upToDate | boolean | true quando o texto reflete os dados atuais; false pede POST …/refresh. |
Falha da avaliação ou do provedor não responde erro: devolve o texto anterior com upToDate: false.
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | personId fora do formato UUID. |
| 401 | UNAUTHORIZED | Sem credencial válida. |
| 403 | FORBIDDEN | Token de sistema. |
| 404 | NOT_FOUND | Pessoa inexistente ou fora do alcance do ator. |
| 500 | INTERNAL | Falha não tratada. |
Credenciais de serviço
Credencial de acesso da Pessoa a um serviço externo. A senha é gravada cifrada e só sai em claro pela operação própria de leitura da senha, que registra a leitura no histórico da Pessoa. Criação, alteração, exclusão e leitura da senha gravam person-credential.created, .updated, .deleted e .secret-viewed.
GET /v1/people/{personId}/credentials
Lista as credenciais da Pessoa em ordem de criação, sem a senha.
Autenticação e autorização: Bearer de usuário com Acesso de Núcleo ou superior; Pessoa no alcance de leitura do ator.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | personId | UUID | Sim | Pessoa dona da credencial. |
| Query | cursor | string | Não | Cursor opaco devolvido em nextCursor. |
| Query | limit | number de 1 a 200 | Não, padrão 50 | Tamanho da página. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | items[].id | UUID | Identificador da credencial. |
| 200 | items[].personId | UUID | Pessoa dona da credencial. |
| 200 | items[].service | string | Serviço externo. |
| 200 | items[].login | string | Login no serviço. |
| 200 | items[].url | string ou null | Endereço de acesso ao serviço. Em implementação. |
| 200 | items[].authorUserId | UUID ou null | Usuário que registrou a credencial. |
| 200 | items[].createdAt, items[].updatedAt | data e hora ISO 8601 | Trilha temporal. |
| 200 | nextCursor | string ou null | Cursor da próxima página. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | personId fora do formato UUID ou cursor inválido. |
| 401 | UNAUTHORIZED | Sem credencial válida. |
| 403 | FORBIDDEN | Perfil abaixo de Acesso de Núcleo. |
| 404 | NOT_FOUND | Pessoa inexistente ou fora do alcance; credencial inexistente ou de outra Pessoa. |
| 503 | UPSTREAM_UNAVAILABLE | Credencial de serviço desligada no servidor. |
POST /v1/people/{personId}/credentials
Registra uma credencial de serviço.
Autenticação e autorização: Bearer de usuário com Acesso de Núcleo ou superior e a autorização de edição da Pessoa.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | personId | UUID | Sim | Pessoa dona da credencial. |
| Corpo | service | string não vazia, até 60 | Sim | Serviço externo a que a credencial dá acesso. |
| Corpo | login | string não vazia, até 255 | Sim | Login no serviço. |
| Corpo | url | string até 2048, aceita null | Não | Endereço de acesso ao serviço; http ou https com protocolo explícito. url em implementação. |
| Corpo | secret | string não vazia, até 255 | Sim | Senha em claro; gravada só cifrada e nunca devolvida por esta operação. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 201 | id, personId, service, login, url, authorUserId, createdAt, updatedAt | Ver GET | Credencial criada, sem a senha. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | personId fora do formato UUID ou corpo inválido. |
| 401 | UNAUTHORIZED | Sem credencial válida. |
| 403 | FORBIDDEN | Perfil abaixo de Acesso de Núcleo. |
| 404 | NOT_FOUND | Pessoa inexistente ou fora do alcance; credencial inexistente ou de outra Pessoa. |
| 503 | UPSTREAM_UNAVAILABLE | Credencial de serviço desligada no servidor. |
PATCH /v1/people/{personId}/credentials/{id}
Altera os campos enviados; campo ausente não muda. secret enviado substitui a senha cifrada.
Autenticação e autorização: Bearer de usuário com Acesso de Núcleo ou superior e a autorização de edição da Pessoa.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | personId | UUID | Sim | Pessoa dona da credencial. |
| Caminho | id | UUID | Sim | Credencial. |
| Corpo | service | string não vazia, até 60 | Não | Serviço externo a que a credencial dá acesso. |
| Corpo | login | string não vazia, até 255 | Não | Login no serviço. |
| Corpo | url | string até 2048, aceita null | Não | Endereço de acesso ao serviço; http ou https com protocolo explícito. url em implementação. |
| Corpo | secret | string não vazia, até 255 | Não | Senha em claro; gravada só cifrada e nunca devolvida por esta operação. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | id, personId, service, login, url, authorUserId, createdAt, updatedAt | Ver GET | Credencial alterada, sem a senha. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | id fora do formato UUID ou corpo inválido. |
| 401 | UNAUTHORIZED | Sem credencial válida. |
| 403 | FORBIDDEN | Perfil abaixo de Acesso de Núcleo. |
| 404 | NOT_FOUND | Pessoa inexistente ou fora do alcance; credencial inexistente ou de outra Pessoa. |
| 503 | UPSTREAM_UNAVAILABLE | Credencial de serviço desligada no servidor. |
DELETE /v1/people/{personId}/credentials/{id}
Exclui a credencial.
Autenticação e autorização: Bearer de usuário com Acesso de Núcleo ou superior e a autorização de edição da Pessoa.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | personId | UUID | Sim | Pessoa dona da credencial. |
| Caminho | id | UUID | Sim | Credencial. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 204 | — | Sem corpo | Credencial excluída. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | personId ou id fora do formato UUID. |
| 401 | UNAUTHORIZED | Sem credencial válida. |
| 403 | FORBIDDEN | Perfil abaixo de Acesso de Núcleo. |
| 404 | NOT_FOUND | Pessoa inexistente ou fora do alcance; credencial inexistente ou de outra Pessoa. |
| 503 | UPSTREAM_UNAVAILABLE | Credencial de serviço desligada no servidor. |
GET /v1/people/{personId}/credentials/{id}/secret
Devolve a senha em claro e grava person-credential.secret-viewed no histórico da Pessoa a cada leitura.
Autenticação e autorização: Bearer de usuário com Acesso de Núcleo ou superior; Pessoa no alcance de leitura do ator.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | personId | UUID | Sim | Pessoa dona da credencial. |
| Caminho | id | UUID | Sim | Credencial. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | secret | string | Senha em claro da credencial. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | personId ou id fora do formato UUID. |
| 401 | UNAUTHORIZED | Sem credencial válida. |
| 403 | FORBIDDEN | Perfil abaixo de Acesso de Núcleo. |
| 404 | NOT_FOUND | Pessoa inexistente ou fora do alcance; credencial inexistente ou de outra Pessoa. |
| 503 | UPSTREAM_UNAVAILABLE | Credencial de serviço desligada no servidor. |
Checklist de documentos
GET /v1/people/{personId}/document-checklist
Os quatro itens do checklist, sempre presentes, mesmo sem nenhum confirmado.
Autenticação e autorização: Bearer autenticado; pessoa no alcance do ator.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | personId | UUID | Sim | Identificador da Pessoa. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | [] | array de 4 itens | Um item por kind. |
| 200 | [].personId | string | Identificador da Pessoa. |
| 200 | [].kind | procuracao, identidade_cpf, comprovante_residencia ou contrato_honorarios | Tipo do item. |
| 200 | [].status | pendente ou confirmado | Estado do item. |
| 200 | [].authorUserId | string ou null | Autor da última mudança; null quando nunca tocado ou autor excluído. |
| 200 | [].createdAt | data e hora ISO 8601 ou null | null quando o item é virtual. |
| 200 | [].updatedAt | data e hora ISO 8601 ou null | null quando o item é virtual. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | personId fora do formato UUID. |
| 404 | NOT_FOUND | Pessoa inexistente ou fora do alcance do ator. |
PATCH /v1/people/{personId}/document-checklist/{kind}
Confirma ou marca pendente um item; upsert idempotente, sem máquina de estados.
Autenticação e autorização: Bearer de usuário pessoal com Acesso de Núcleo ou superior e pessoa no alcance.
Entrada — JSON
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | personId | UUID | Sim | Identificador da Pessoa. |
| Caminho | kind | procuracao, identidade_cpf, comprovante_residencia ou contrato_honorarios | Sim | Tipo do item. |
| Corpo | status | pendente ou confirmado | Sim | Novo estado; reversível. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | personId | string | Identificador da Pessoa. |
| 200 | kind | enum | Tipo do item. |
| 200 | status | pendente ou confirmado | Estado gravado. |
| 200 | authorUserId | string ou null | Autor da mudança. |
| 200 | createdAt | data e hora ISO 8601 | Criação do item. |
| 200 | updatedAt | data e hora ISO 8601 | Última mudança. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | personId fora do formato UUID, kind fora dos quatro tipos ou status fora do enum. |
| 403 | FORBIDDEN | Perfil abaixo de Acesso de Núcleo. |
| 404 | NOT_FOUND | Pessoa inexistente ou fora do alcance do ator. |
Catálogo de Representados
Catálogo institucional de quem um advogado externo representa. Não tem escopo por núcleo: qualquer usuário autenticado lê; a escrita exige Acesso de Núcleo ou superior.
GET /v1/represented-parties
Página do catálogo, do mais antigo ao mais novo, com busca por nome e filtro por tipo.
Autenticação e autorização: Bearer autenticado.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Query | search | string até 255 | Não | Busca por nome, ignorando caixa; termo em branco é ignorado. |
| Query | kind | COMPANY, PUBLIC_BODY, NONPROFIT, UNION, COOPERATIVE, CONDOMINIUM, INDIVIDUAL ou OTHER | Não | Somente Representados de um tipo. |
| Query | cursor | string | Não | Cursor opaco devolvido em nextCursor. |
| Query | limit | number de 1 a 200 | Não, padrão 50 | Tamanho da página. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | items | array de Representados | Ver Representado em Convenções. |
| 200 | nextCursor | string ou null | Cursor da próxima página. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | Cursor malformado; limit fora de 1 a 200; search acima de 255; kind fora do vocabulário. |
POST /v1/represented-parties
Cadastra um Representado.
Autenticação e autorização: Bearer de usuário pessoal com Acesso de Núcleo ou superior.
Entrada — JSON
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Corpo | name | string de 1 a 255 | Sim | Aparado. |
| Corpo | kind | COMPANY, PUBLIC_BODY, NONPROFIT, UNION, COOPERATIVE, CONDOMINIUM, INDIVIDUAL ou OTHER | Sim | Tipo de Representado. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 201 | Campos de Representado | Ver Convenções | Representado criado. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | name fora de 1 a 255; kind fora do vocabulário; propriedade desconhecida. |
| 403 | FORBIDDEN | Perfil abaixo de Acesso de Núcleo ou token de sistema. |
| 409 | CONFLICT | Já existe Representado com este nome e este tipo, sem distinção de caixa. |
GET /v1/represented-parties/{id}
Um Representado do catálogo.
Autenticação e autorização: Bearer autenticado.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | id | UUID | Sim | Identificador do Representado. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | Campos de Representado | Ver Convenções | Representado. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | id fora do formato UUID. |
| 404 | NOT_FOUND | Representado inexistente. |
PATCH /v1/represented-parties/{id}
Altera nome e/ou tipo; o par resultante continua único.
Autenticação e autorização: Bearer de usuário pessoal com Acesso de Núcleo ou superior.
Entrada — JSON
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | id | UUID | Sim | Identificador do Representado. |
| Corpo | name | string de 1 a 255 | Não | Aparado. |
| Corpo | kind | enum de tipo de Representado | Não | Dentro do vocabulário fechado. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | Campos de Representado | Ver Convenções | Representado atualizado. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | id fora do formato UUID ou corpo inválido. |
| 403 | FORBIDDEN | Perfil abaixo de Acesso de Núcleo ou token de sistema. |
| 404 | NOT_FOUND | Representado inexistente. |
| 409 | CONFLICT | Já existe Representado com este nome e este tipo. |
DELETE /v1/represented-parties/{id}
Apaga o Representado.
Autenticação e autorização: Bearer de usuário pessoal com Acesso de Núcleo ou superior.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | id | UUID | Sim | Identificador do Representado. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 204 | — | Sem corpo | Representado apagado. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | id fora do formato UUID. |
| 403 | FORBIDDEN | Perfil abaixo de Acesso de Núcleo ou token de sistema. |
| 404 | NOT_FOUND | Representado inexistente. |
| 409 | CONFLICT | Representado ainda vinculado a alguma pessoa. |
Operações de outros domínios sob /v1/people
As rotas abaixo são montadas sob o caminho da pessoa, aplicam o alcance da pessoa e pertencem a outros domínios, que documentam seus contratos:
-
GETePOST /v1/people/{personId}/portfolio-transfers— histórico e transferência de Cliente da Carteira (Expansão; exige gestão EXPINS). -
GET /v1/portfolios?ownerPersonId=eGET /v1/portfolios/{id}— carteira própria da Pessoa Parceira (Expansão;PortfolioDtotrazownerPersonId). -
GET /v1/people/{personId}/dossier— Documentos e dossiês. -
GET /v1/people/{personId}/service-desk/ticketseGET /v1/people/{personId}/service-desk/messages— Integrações (DigiSac).
Integração com Projuris Legado
As consultas externas de anexos, processos e entrevistas pertencerão ao módulo Projuris Legado. O contrato está pendente de revisão pelo responsável; esta seção não especifica endpoints vigentes para essas consultas.