API Reference · Entrevistas
Convenções
As operações recebem Authorization: Bearer <credencial>. Corpos de criação, edição e transição usam JSON. UUIDs nativos não se confundem com identificadores opacos do espelho. Listagens retornam items e nextCursor; o cliente deve tratar o cursor como opaco.
Os estados admitidos são ABERTA, EM_ANALISE, CONCLUIDA_COM_DIREITO, CONCLUIDA_SEM_DIREITO ou ARQUIVADA. As áreas são previdenciario, civil ou trabalho. O detalhe acrescenta capacidades do usuário; criação, edição e transição devolvem os campos da entrevista sem essas capacidades adicionais.
Corpo dos erros da aplicação
| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
statusCode | number | Sempre | Status HTTP. |
message | string ou string[] | Sempre | Mensagem; validação pode retornar uma lista. |
errorCode | string | Quando atribuído pela aplicação | Código estável para tratamento do erro; exceções sem código explícito podem omiti-lo. |
error | string | Condicional | Nome do status; pode faltar em exceções com corpo textual. |
As tabelas por operação usam esse envelope. Falhas não tratadas da aplicação retornam 500 INTERNAL; uma falha de infraestrutura não equivale a lista vazia ou registro não encontrado. A matriz detalhada de perfis e vínculos está pendente de revisão, sem alterar as capacidades retornadas no detalhe.
GET /v1/consultations
Lista entrevistas, mais recentes primeiro, com filtros combinados dentro do alcance do usuário.
Autenticação e autorização: Bearer válido; o alcance é aplicado à consulta antes da paginação.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Query | cursor | string | Não | Cursor opaco devolvido pela página anterior. |
| Query | limit | integer, 1 a 200 | Não | Padrão 50. |
| Query | search | string, até 200 caracteres | Não | Busca por pessoa, assunto e núcleos; não inclui relato. Ignora termos menores que dois caracteres e considera até seis palavras. |
| Query | nucleo | string, 1 a 16 caracteres | Não | Um núcleo destinatário; ignora caixa. |
| Query | clientPersonId | UUID | Não | Pessoa cliente. |
| Query | status | ABERTA, EM_ANALISE, CONCLUIDA_COM_DIREITO, CONCLUIDA_SEM_DIREITO ou ARQUIVADA | Não | Parâmetro repetível; destinos combinam em OU entre si. |
| Query | area | previdenciario, civil ou trabalho | Não | Área do assunto. |
| Query | subjectSlug | string, até 80 caracteres | Não | Igualdade exata; slug desconhecido resulta em página vazia. |
| Query | flagInitialStudy | true ou false | Não | Marca de estudo inicial. |
| Query | flagAppealResearch | true ou false | Não | Marca de pesquisa de recurso. |
| Query | createdFrom | string ISO 8601 | Não | Limite inferior inclusivo de createdAt; data sem hora usa meia-noite UTC. |
| Query | createdTo | string ISO 8601 | Não | Limite superior inclusivo de createdAt; não filtra a data civil do atendimento. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | items | array | Itens da página. |
| 200 | nextCursor | string ou null | Cursor opaco; null indica fim. |
| 200 | items[].id | UUID | Identificador da entrevista. |
| 200 | items[].nucleos | string[] | Núcleos destinatários. |
| 200 | items[].nucleos[] | string | Sigla normalizada de núcleo. |
| 200 | items[].subjectSlug | string ou null | Slug do assunto. |
| 200 | items[].subjectName | string ou null | Nome do assunto. |
| 200 | items[].area | previdenciario, civil ou trabalho ou null | Área derivada do assunto. |
| 200 | items[].clientPersonId | UUID | Pessoa cliente fixa. |
| 200 | items[].clientName | string ou null | Nome copiado da pessoa na criação. |
| 200 | items[].notes | string ou null | Relato do atendimento. |
| 200 | items[].code | string | Código ENT-AAAA-NNN…, com ano e sequência de no mínimo três dígitos, gerado pelo servidor. Em implementação. |
| 200 | items[].title | string ou null | Título da entrevista. Em implementação. |
| 200 | items[].interviewerUserId | UUID ou null | Usuário que conduziu a entrevista; null após a exclusão do usuário. Em implementação. |
| 200 | items[].consultationDate | string, data civil YYYY-MM-DD | Data do atendimento. |
| 200 | items[].flagInitialStudy | boolean | Marca de estudo inicial. |
| 200 | items[].flagAppealResearch | boolean | Marca de pesquisa de recurso. |
| 200 | items[].status | ABERTA, EM_ANALISE, CONCLUIDA_COM_DIREITO, CONCLUIDA_SEM_DIREITO ou ARQUIVADA | Situação atual. |
| 200 | items[].originUoSigla | string ou null | Unidade de origem copiada da pessoa. |
| 200 | items[].authorUserId | UUID ou null | Usuário autor. |
| 200 | items[].createdAt | string ISO 8601 | Instante do cadastro. |
| 200 | items[].updatedAt | string ISO 8601 | Instante da atualização. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | Cursor, limite, UUID, datas, enum ou flags inválidos. |
| 401 | UNAUTHORIZED | Credencial ausente ou inválida. |
| 403 | FORBIDDEN | Identidade sem condições para resolver o alcance de acesso. |
Os filtros de eixos diferentes combinam em E. A ordenação usa createdAt DESC, id DESC. Sem resultados: lista vazia e cursor null.
GET /v1/consultations/subjects
Fornece o catálogo de classificação e sugestões de núcleos.
Autenticação e autorização: Bearer válido.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Cabeçalho | Authorization | Bearer | Sim | Credencial válida; sem query ou corpo. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | areas | array | Áreas do catálogo. |
| 200 | areas[].area | previdenciario, civil ou trabalho | Identificador da área. |
| 200 | areas[].label | string | Rótulo da área. |
| 200 | areas[].suggestedNucleus | string | Sigla sugerida para encaminhamento. |
| 200 | subjects | array | Assuntos em ordem de apresentação. |
| 200 | subjects[].slug | string | Identificador estável do assunto. |
| 200 | subjects[].label | string | Nome do assunto. |
| 200 | subjects[].area | previdenciario, civil ou trabalho | Área do assunto. |
| 200 | receivingNuclei | string[] | Núcleos oferecidos prioritariamente na interface. |
| 200 | receivingNuclei[] | string | Sigla de núcleo. |
| 200 | wildcardNuclei | string[] | Núcleos curinga. |
| 200 | wildcardNuclei[] | string | Sigla de núcleo curinga. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 401 | UNAUTHORIZED | Credencial ausente ou inválida. |
As sugestões do catálogo não substituem a validação das siglas no cadastro de núcleos.
POST /v1/consultations
Cria uma entrevista com situação ABERTA, autor autenticado e histórico de criação.
Autenticação e autorização: Bearer de usuário pessoal autenticado; pessoa cliente legível.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Corpo | nucleos | string[] | Sim | Ao menos um núcleo existente; normalização e deduplicação. |
| Corpo | nucleos[] | string, 1 a 16 caracteres | Sim por item | Sigla do núcleo; lista normalizada não pode ficar vazia. |
| Corpo | subjectSlug | string, até 80 caracteres | Não | Assunto do catálogo; nome e área são derivados. |
| Corpo | clientPersonId | UUID | Sim | Pessoa existente e legível. |
| Corpo | notes | string, até 100.000 caracteres | Não | Relato; string vazia é aceita. |
| Corpo | title | string de 1 a 255, aceita null | Não | Título da entrevista; null apaga na edição. Em implementação. |
| Corpo | interviewerUserId | UUID, aceita null | Não | Usuário que conduziu a entrevista; precisa existir; null apaga na edição. Em implementação. |
| Corpo | consultationDate | string, YYYY-MM-DD | Não | Data civil existente; ausência na criação usa o dia em America/Recife. |
| Corpo | flagInitialStudy | boolean | Não | Padrão false. |
| Corpo | flagAppealResearch | boolean | Não | Padrão false. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 201 | id | UUID | Identificador da entrevista. |
| 201 | nucleos | string[] | Núcleos destinatários. |
| 201 | nucleos[] | string | Sigla normalizada de núcleo. |
| 201 | subjectSlug | string ou null | Slug do assunto. |
| 201 | subjectName | string ou null | Nome do assunto. |
| 201 | area | previdenciario, civil ou trabalho ou null | Área derivada do assunto. |
| 201 | clientPersonId | UUID | Pessoa cliente fixa. |
| 201 | clientName | string ou null | Nome copiado da pessoa na criação. |
| 201 | notes | string ou null | Relato do atendimento. |
| 201 | code | string | Código ENT-AAAA-NNN…, com ano e sequência de no mínimo três dígitos, gerado pelo servidor. Em implementação. |
| 201 | title | string ou null | Título da entrevista. Em implementação. |
| 201 | interviewerUserId | UUID ou null | Usuário que conduziu a entrevista; null após a exclusão do usuário. Em implementação. |
| 201 | consultationDate | string, data civil YYYY-MM-DD | Data do atendimento. |
| 201 | flagInitialStudy | boolean | Marca de estudo inicial. |
| 201 | flagAppealResearch | boolean | Marca de pesquisa de recurso. |
| 201 | status | ABERTA, EM_ANALISE, CONCLUIDA_COM_DIREITO, CONCLUIDA_SEM_DIREITO ou ARQUIVADA | Situação atual. |
| 201 | originUoSigla | string ou null | Unidade de origem copiada da pessoa. |
| 201 | authorUserId | UUID ou null | Usuário autor. |
| 201 | createdAt | string ISO 8601 | Instante do cadastro. |
| 201 | updatedAt | string ISO 8601 | Instante da atualização. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | Campos desconhecidos, tipos inválidos, lista vazia, limites excedidos ou data civil inválida. |
| 401 | UNAUTHORIZED | Credencial ausente ou inválida. |
| 403 | FORBIDDEN | Token de Sistema; a operação exige usuário pessoal. |
| 403 | FORBIDDEN | Identidade sem condições para resolver o alcance de acesso. |
| 422 | RULE_VIOLATION | Núcleo inexistente ou lista vazia após normalização. |
| 422 | RULE_VIOLATION | Assunto fora do catálogo. |
| 422 | RULE_VIOLATION | interviewerUserId de usuário inexistente. Em implementação. |
| 422 | RULE_VIOLATION | Pessoa cliente inexistente ou fora do alcance. |
subjectName, area, clientName, originUoSigla, authorUserId e status são atribuídos pelo servidor; não entram no corpo.
GET /v1/consultations/{id}
Obtém a entrevista e as capacidades calculadas para o usuário.
Autenticação e autorização: Bearer válido e alcance de leitura sobre a entrevista. Registro inexistente, excluído ou fora do alcance responde 404.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | id | UUID | Sim | Identificador da entrevista nativa. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | id | UUID | Identificador da entrevista. |
| 200 | nucleos | string[] | Núcleos destinatários. |
| 200 | nucleos[] | string | Sigla normalizada de núcleo. |
| 200 | subjectSlug | string ou null | Slug do assunto. |
| 200 | subjectName | string ou null | Nome do assunto. |
| 200 | area | previdenciario, civil ou trabalho ou null | Área derivada do assunto. |
| 200 | clientPersonId | UUID | Pessoa cliente fixa. |
| 200 | clientName | string ou null | Nome copiado da pessoa na criação. |
| 200 | notes | string ou null | Relato do atendimento. |
| 200 | code | string | Código ENT-AAAA-NNN…, com ano e sequência de no mínimo três dígitos, gerado pelo servidor. Em implementação. |
| 200 | title | string ou null | Título da entrevista. Em implementação. |
| 200 | interviewerUserId | UUID ou null | Usuário que conduziu a entrevista; null após a exclusão do usuário. Em implementação. |
| 200 | consultationDate | string, data civil YYYY-MM-DD | Data do atendimento. |
| 200 | flagInitialStudy | boolean | Marca de estudo inicial. |
| 200 | flagAppealResearch | boolean | Marca de pesquisa de recurso. |
| 200 | status | ABERTA, EM_ANALISE, CONCLUIDA_COM_DIREITO, CONCLUIDA_SEM_DIREITO ou ARQUIVADA | Situação atual. |
| 200 | originUoSigla | string ou null | Unidade de origem copiada da pessoa. |
| 200 | authorUserId | UUID ou null | Usuário autor. |
| 200 | createdAt | string ISO 8601 | Instante do cadastro. |
| 200 | updatedAt | string ISO 8601 | Instante da atualização. |
| 200 | canDelete | boolean | Se o usuário pode excluir a entrevista. |
| 200 | allowedStatusTransitions | array de situações | Destinos permitidos a partir da situação atual. |
| 200 | allowedStatusTransitions[] | ABERTA, EM_ANALISE, CONCLUIDA_COM_DIREITO, CONCLUIDA_SEM_DIREITO ou ARQUIVADA | Um destino permitido. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | UUID inválido. |
| 401 | UNAUTHORIZED | Credencial ausente ou inválida. |
| 403 | FORBIDDEN | Identidade sem condições para resolver o alcance de acesso. |
| 404 | NOT_FOUND | Entrevista inexistente, excluída ou fora do alcance. |
PATCH /v1/consultations/{id}
Atualiza parcialmente a entrevista.
Autenticação e autorização: Bearer de usuário pessoal autenticado e alcance sobre a entrevista. Token de Sistema é recusado. A autorização detalhada por perfil e vínculo permanece pendente de revisão.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | id | UUID | Sim | Identificador da entrevista nativa. |
| Corpo | nucleos | string[] | Não | Ao menos um núcleo existente; normalização e deduplicação. |
| Corpo | nucleos[] | string, 1 a 16 caracteres | Com a lista | Sigla do núcleo; lista normalizada não pode ficar vazia. |
| Corpo | subjectSlug | string até 80 caracteres ou null | Não | null remove assunto, nome e área. |
| Corpo | notes | string, até 100.000 caracteres | Não | Relato; string vazia é aceita. |
| Corpo | title | string de 1 a 255, aceita null | Não | Título da entrevista; null apaga na edição. Em implementação. |
| Corpo | interviewerUserId | UUID, aceita null | Não | Usuário que conduziu a entrevista; precisa existir; null apaga na edição. Em implementação. |
| Corpo | consultationDate | string, YYYY-MM-DD | Não | Data civil existente; ausência preserva o valor. |
| Corpo | flagInitialStudy | boolean | Não | Ausência preserva o valor. |
| Corpo | flagAppealResearch | boolean | Não | Ausência preserva o valor. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | id | UUID | Identificador da entrevista. |
| 200 | nucleos | string[] | Núcleos destinatários. |
| 200 | nucleos[] | string | Sigla normalizada de núcleo. |
| 200 | subjectSlug | string ou null | Slug do assunto. |
| 200 | subjectName | string ou null | Nome do assunto. |
| 200 | area | previdenciario, civil ou trabalho ou null | Área derivada do assunto. |
| 200 | clientPersonId | UUID | Pessoa cliente fixa. |
| 200 | clientName | string ou null | Nome copiado da pessoa na criação. |
| 200 | notes | string ou null | Relato do atendimento. |
| 200 | code | string | Código ENT-AAAA-NNN…, com ano e sequência de no mínimo três dígitos, gerado pelo servidor. Em implementação. |
| 200 | title | string ou null | Título da entrevista. Em implementação. |
| 200 | interviewerUserId | UUID ou null | Usuário que conduziu a entrevista; null após a exclusão do usuário. Em implementação. |
| 200 | consultationDate | string, data civil YYYY-MM-DD | Data do atendimento. |
| 200 | flagInitialStudy | boolean | Marca de estudo inicial. |
| 200 | flagAppealResearch | boolean | Marca de pesquisa de recurso. |
| 200 | status | ABERTA, EM_ANALISE, CONCLUIDA_COM_DIREITO, CONCLUIDA_SEM_DIREITO ou ARQUIVADA | Situação atual. |
| 200 | originUoSigla | string ou null | Unidade de origem copiada da pessoa. |
| 200 | authorUserId | UUID ou null | Usuário autor. |
| 200 | createdAt | string ISO 8601 | Instante do cadastro. |
| 200 | updatedAt | string ISO 8601 | Instante da atualização. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | UUID, corpo ou data inválidos; campo não permitido, inclusive clientPersonId ou status. |
| 401 | UNAUTHORIZED | Credencial ausente ou inválida. |
| 403 | FORBIDDEN | Token de Sistema; a operação exige usuário pessoal. |
| 403 | FORBIDDEN | Identidade sem condições para resolver o alcance de acesso. |
| 404 | NOT_FOUND | Entrevista inexistente, excluída ou fora do alcance. |
| 422 | RULE_VIOLATION | Núcleo inexistente ou lista vazia após normalização. |
| 422 | RULE_VIOLATION | Assunto fora do catálogo. |
| 422 | RULE_VIOLATION | interviewerUserId de usuário inexistente. Em implementação. |
Campos ausentes preservam valores. A lista de núcleos enviada substitui a anterior; notes: "" limpa o relato. Uma alteração efetiva registra histórico na mesma transação.
POST /v1/consultations/{id}/status
Altera a situação e registra a transição no histórico.
Autenticação e autorização: Bearer de usuário pessoal autenticado e alcance sobre a entrevista. Token de Sistema é recusado. A autorização detalhada por perfil e vínculo permanece pendente de revisão. Reabertura exige capacidade adicional.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | id | UUID | Sim | Identificador da entrevista nativa. |
| Corpo | status | ABERTA, EM_ANALISE, CONCLUIDA_COM_DIREITO, CONCLUIDA_SEM_DIREITO ou ARQUIVADA | Sim | Estado de destino, permitido para a situação atual e o usuário. |
| Corpo | reason | string, até 500 caracteres | Não | Justificativa da transição. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | id | UUID | Identificador da entrevista. |
| 200 | nucleos | string[] | Núcleos destinatários. |
| 200 | nucleos[] | string | Sigla normalizada de núcleo. |
| 200 | subjectSlug | string ou null | Slug do assunto. |
| 200 | subjectName | string ou null | Nome do assunto. |
| 200 | area | previdenciario, civil ou trabalho ou null | Área derivada do assunto. |
| 200 | clientPersonId | UUID | Pessoa cliente fixa. |
| 200 | clientName | string ou null | Nome copiado da pessoa na criação. |
| 200 | notes | string ou null | Relato do atendimento. |
| 200 | code | string | Código ENT-AAAA-NNN…, com ano e sequência de no mínimo três dígitos, gerado pelo servidor. Em implementação. |
| 200 | title | string ou null | Título da entrevista. Em implementação. |
| 200 | interviewerUserId | UUID ou null | Usuário que conduziu a entrevista; null após a exclusão do usuário. Em implementação. |
| 200 | consultationDate | string, data civil YYYY-MM-DD | Data do atendimento. |
| 200 | flagInitialStudy | boolean | Marca de estudo inicial. |
| 200 | flagAppealResearch | boolean | Marca de pesquisa de recurso. |
| 200 | status | ABERTA, EM_ANALISE, CONCLUIDA_COM_DIREITO, CONCLUIDA_SEM_DIREITO ou ARQUIVADA | Situação atual. |
| 200 | originUoSigla | string ou null | Unidade de origem copiada da pessoa. |
| 200 | authorUserId | UUID ou null | Usuário autor. |
| 200 | createdAt | string ISO 8601 | Instante do cadastro. |
| 200 | updatedAt | string ISO 8601 | Instante da atualização. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | UUID, estado de destino ou justificativa inválidos. |
| 401 | UNAUTHORIZED | Credencial ausente ou inválida. |
| 403 | FORBIDDEN | Token de Sistema; a operação exige usuário pessoal. |
| 403 | FORBIDDEN | Identidade sem condições para resolver o alcance de acesso. |
| 404 | NOT_FOUND | Entrevista inexistente, excluída ou fora do alcance. |
| 403 | FORBIDDEN | Reabertura sem capacidade para essa operação. |
| 422 | RULE_VIOLATION | Par de transição não permitido, inclusive origem igual ao destino. |
A tabela de transições está em Regras de negócio. A situação de origem é lida do registro, não recebida no corpo.
DELETE /v1/consultations/{id}
Exclui logicamente a entrevista.
Autenticação e autorização: Bearer de usuário pessoal autenticado e alcance sobre a entrevista. Token de Sistema é recusado. A autorização detalhada por perfil e vínculo permanece pendente de revisão. Requer capacidade de exclusão.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | id | UUID | Sim | Identificador da entrevista nativa. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 204 | — | Sem corpo | Exclusão registrada; a linha permanece armazenada. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | UUID inválido. |
| 401 | UNAUTHORIZED | Credencial ausente ou inválida. |
| 403 | FORBIDDEN | Token de Sistema; a operação exige usuário pessoal. |
| 403 | FORBIDDEN | Identidade sem condições para resolver o alcance de acesso. |
| 404 | NOT_FOUND | Entrevista inexistente, excluída ou fora do alcance. |
| 403 | FORBIDDEN | Usuário sem capacidade de exclusão. |
Após a exclusão, a entrevista não aparece nas listas e suas rotas respondem 404. Repetir a exclusão responde 404.
GET /v1/consultations/{id}/events
Lista o histórico da entrevista, mais antigo primeiro.
Autenticação e autorização: Bearer válido e alcance de leitura sobre a entrevista. Registro inexistente, excluído ou fora do alcance responde 404.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | id | UUID | Sim | Identificador da entrevista nativa. |
| Query | cursor | string | Não | Cursor opaco devolvido pela página anterior. |
| Query | limit | integer, 1 a 200 | Não | Padrão 50. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | items | array | Itens da página. |
| 200 | nextCursor | string ou null | Cursor opaco; null indica fim. |
| 200 | items[].id | UUID | Identificador do evento. |
| 200 | items[].resourceType | string | consultation. |
| 200 | items[].resourceId | string | UUID da entrevista. |
| 200 | items[].resourceLabel | string ou null | Rótulo do recurso. |
| 200 | items[].action | created, updated, deleted, restored, transitioned, linked, unlinked, imported ou action | Natureza da operação no histórico compartilhado. |
| 200 | items[].eventType | string | Tipo do evento. |
| 200 | items[].summary | string | Descrição breve. |
| 200 | items[].changes | array | Diferenças registradas. |
| 200 | items[].changes[].field | string | Campo alterado. |
| 200 | items[].changes[].label | string | Rótulo do campo. |
| 200 | items[].changes[].before | string ou null | Valor anterior representado como texto. |
| 200 | items[].changes[].after | string ou null | Novo valor representado como texto. |
| 200 | items[].changes[].beforeTruncated | boolean | Indica truncamento do valor anterior. |
| 200 | items[].changes[].afterTruncated | boolean | Indica truncamento do valor novo. |
| 200 | items[].metadata | objeto | Contexto adicional do evento. |
| 200 | items[].metadata.reason | string, quando informada | Justificativa em evento de transição. |
| 200 | items[].actorKind | user, machine ou system | Natureza do autor. |
| 200 | items[].actorUserId | UUID ou null | Usuário autor. |
| 200 | items[].actorLabel | string | Identificação de exibição do autor. |
| 200 | items[].occurredAt | string ISO 8601 | Instante do acontecimento. |
| 200 | items[].createdAt | string ISO 8601 | Instante do registro. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | UUID, cursor ou limite inválidos. |
| 401 | UNAUTHORIZED | Credencial ausente ou inválida. |
| 403 | FORBIDDEN | Identidade sem condições para resolver o alcance de acesso. |
| 404 | NOT_FOUND | Entrevista inexistente, excluída ou fora do alcance. |
As diferenças usam os campos before e after; não há garantia de omissão de valores no formato de resposta. A política de conteúdo do histórico permanece em revisão.
GET /v1/consultations/{id}/dossier
Lista as juntadas relacionadas à entrevista, mais antigas primeiro.
Autenticação e autorização: Bearer válido e alcance de leitura sobre a entrevista. Registro inexistente, excluído ou fora do alcance responde 404. A leitura do arquivo mantém autorização própria.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | id | UUID | Sim | Identificador da entrevista nativa. |
| Query | cursor | string | Não | Cursor opaco devolvido pela página anterior. |
| Query | limit | integer, 1 a 200 | Não | Padrão 50. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | items | array | Itens da página. |
| 200 | nextCursor | string ou null | Cursor opaco; null indica fim. |
| 200 | items[].id | UUID | Identificador da juntada. |
| 200 | items[].documentId | UUID | Documento juntado. |
| 200 | items[].personId | UUID | Pessoa do dossiê. |
| 200 | items[].category | institucional, financeiro, pessoal, trabalhista, previdenciario ou civel | Categoria. |
| 200 | items[].suggestedCategory | institucional, financeiro, pessoal, trabalhista, previdenciario ou civel ou null | Categoria sugerida. |
| 200 | items[].relationType | string | entrevista neste recorte. |
| 200 | items[].relationRef | string | UUID da entrevista. |
| 200 | items[].relationLabel | string ou null | Rótulo da relação. |
| 200 | items[].authorUserId | UUID | Autor da juntada. |
| 200 | items[].authorName | string | Nome do autor. |
| 200 | items[].nucleos | string[] | Siglas registradas na juntada. |
| 200 | items[].nucleos[] | string | Uma sigla. |
| 200 | items[].associationId | string ou null | Referência associativa. |
| 200 | items[].originUoSigla | string ou null | Unidade de origem. |
| 200 | items[].createdAt | string ISO 8601 | Instante da juntada. |
| 200 | items[].document | objeto ou null | Resumo quando o documento é legível. |
| 200 | items[].document.id | UUID, com documento | Identificador do documento. |
| 200 | items[].document.originalName | string, com documento | Nome original do arquivo. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | UUID, cursor ou limite inválidos. |
| 401 | UNAUTHORIZED | Credencial ausente ou inválida. |
| 403 | FORBIDDEN | Identidade sem condições para resolver o alcance de acesso. |
| 404 | NOT_FOUND | Entrevista inexistente, excluída ou fora do alcance. |
Uma juntada pode conter document: null. Para enviar e juntar arquivos, a interface usa os serviços compartilhados de Documentos e Dossiês.
POST /v1/consultations/{id}/summary
Retorna o resumo guardado ou gera um novo texto a partir do relato e do histórico legível.
Autenticação e autorização: Bearer de usuário pessoal autenticado e entrevista legível.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | id | UUID | Sim | Identificador da entrevista nativa. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | summary | string | Texto do resumo, sem corte adicional pela API. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | UUID inválido. |
| 401 | UNAUTHORIZED | Credencial ausente ou inválida. |
| 403 | FORBIDDEN | Token de Sistema; a operação exige usuário pessoal. |
| 403 | FORBIDDEN | Identidade sem condições para resolver o alcance de acesso. |
| 404 | NOT_FOUND | Entrevista inexistente, excluída ou fora do alcance. |
| 502 | SUMMARY_PROVIDER_FAILED | Provedor falhou ou respondeu sem texto. |
| 503 | SUMMARY_UNAVAILABLE | Chave ou prompt não configurados. |
| 503 | SUMMARY_PROVIDER_TIMEOUT | Provedor não respondeu no prazo. |
Não recebe corpo. Escritas com evento invalidam o resumo guardado. A nova tentativa após falha é manual.
POST /v1/consultations/{id}/notes/professionalize
Estado: em implementação na API.
Devolve uma prévia do relato revisado na gramática, na ortografia, na pontuação e na fluidez, sem acrescentar, retirar ou reinterpretar fatos. Organiza o resultado em parágrafos de até 300 caracteres, preserva marcações HTML de negrito, itálico, citação e menções e responde somente com um elemento <p> por parágrafo. Nada é gravado: o relato só é salvo quando o usuário confirma e envia o texto por PATCH /v1/consultations/{id}.
Autenticação e autorização: Bearer de usuário pessoal autenticado com permissão para editar a entrevista.
Entrada — JSON
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | id | UUID | Sim | Identificador da entrevista nativa. |
| Corpo | notes | string HTML, de 1 a 100.000 caracteres | Sim | Relato em edição, ainda não salvo. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | notes | string HTML | Prévia do relato revisado; não é gravada. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | UUID ou corpo inválido. |
| 401 | UNAUTHORIZED | Credencial ausente ou inválida. |
| 403 | FORBIDDEN | Token de Sistema. |
| 404 | NOT_FOUND | Entrevista inexistente ou fora do alcance. |
| 500 | INTERNAL | Falha não tratada. |
| 502 | SUMMARY_PROVIDER_FAILED | Provedor falhou ou respondeu sem texto; a nova tentativa é manual. |
| 503 | SUMMARY_UNAVAILABLE | Chave ou prompt da revisão não configurados. |
| 503 | SUMMARY_PROVIDER_TIMEOUT | Provedor não respondeu no prazo. |
Consulta ao Projuris Legado
A consulta e a incorporação de entrevistas externas pertencem ao módulo Projuris Legado. O contrato de integração está pendente de revisão pelo responsável; esta seção não especifica um endpoint vigente.
Operações compartilhadas
A juntada usa POST /v1/documents e POST /v1/dossier, cujos contratos pertencem ao acervo documental. Os vínculos com Atendimento não acrescentam operações de escrita ao espelho Projuris.