Apontamentos de compliance

Durante o processo de análise cadastral do Cedente, as equipes de Compliance, Risco ou de validação interna podem registrar apontamentos (também chamados de annotations). Um apontamento é uma solicitação ou questionamento direcionado ao agente responsável pelo cadastro, que precisa ser respondido para que a análise prossiga.

Sempre que um apontamento é criado, ele nasce no status open e, caso configurado, é disparado um Webhook de Apontamento notificando a abertura. Também é enviado um e-mail aos destinatários configurados para o agente. Após o agente responder ao apontamento, ele passa para o status closed e um novo webhook é disparado.

信息

Apontamentos só existem enquanto a análise estiver em um dos status in_manual_analysis, pending_internal_validation ou in_risk_analysis. Cada apontamento aceita apenas uma resposta.

Quem faz o quê:

Ação	Gestora	Consultoria	Cedente
Listar apontamentos da análise	Sim	Sim	Não (use o webhook e a consulta por chave)
Consultar apontamento e documento	Sim	Sim	Sim
Responder	`PUT .../annotation/{annotation_key}`	`PUT .../annotation/{annotation_key}`	`PUT .../annotation/{annotation_key}/response`

Consulta Paginada de Apontamentos

Recupera a lista de apontamentos de uma análise, permitindo ao agente identificar o que precisa ser respondido.

Disponível em

Perfil	Host	Permissão exigida
Gestora	`manager-api`	Leitura
Consultoria	`consultant-api`	Ler Cedentes

URL base de cada host: Ambientes (Hosts).

O cedente não tem esta listagem: ele recebe o webhook de apontamento, que traz a annotation_key, e consulta o apontamento por chave.

Request

ENDPOINT

/assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotations

MÉTODO

GET

Query params

Campo	Tipo	Descrição	Caracteres
`limit`	integer	Limite de objetos por página (padrão 10, máximo 50).	-
`page`	integer	Página desejada (inicia em 0).	-

Response

STATUS

200

Response Body
{
    "data": [
        {
            "annotation_key": "1f2e3d4c-5b6a-4c8d-9e0f-1a2b3c4d5e6f",
            "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
            "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4",
            "status": "open",
            "origin_type": "compliance",
            "annotation_datetime": "2025-01-22T20:30:23Z",
            "message": "Anexar detalhes do processo XXXXXXXXXXX."
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}

Erros

Status	Código	Quando acontece
404	`ASR000026`	O agente autenticado não está habilitado no cadastro de cedentes.
400	—	`limit` acima de `50` ou `page` negativo.

Erros de autenticação, permissão e host: veja Erros da API.

Consulta de Apontamento por Chave

Disponível em

Perfil	Host	Permissão exigida
Gestora	`manager-api`	Leitura
Consultoria	`consultant-api`	Ler Cedentes
Cedente	`assignor-api`	Leitura

URL base de cada host: Ambientes (Hosts).

Request

ENDPOINT

/assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotation/ANNOTATION_KEY

MÉTODO

GET

Response

STATUS

200

Response Body
{
    "annotation_key": "1f2e3d4c-5b6a-4c8d-9e0f-1a2b3c4d5e6f",
    "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4",
    "status": "closed",
    "origin_type": "compliance",
    "annotation_datetime": "2025-01-22T20:30:23Z",
    "message": "Anexar detalhes do processo XXXXXXXXXXX.",
    "response": "Segue autos do processo.",
    "response_datetime": "2025-01-23T14:05:11Z",
    "attached_document_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a"
}

信息

Os campos response, response_datetime e attached_document_key só são retornados quando o apontamento já foi respondido e/ou possui um documento anexado.

Erros

Status	Código	Quando acontece
404	`ASR000004`	`assignor_registry_key` não encontrado ou o agente não tem acesso a esse cedente.
404	`ASR000033`	`analysis_key` não encontrado.
404	`ASR000043`	`annotation_key` não pertence à análise indicada.

Erros de autenticação, permissão e host: veja Erros da API.

Resposta ao Apontamento

Envia a resposta a um apontamento open. Opcionalmente, é possível anexar um documento em PDF (até 20 MB) que comprove ou complemente a resposta. Respondido, o apontamento passa para closed e o webhook de apontamento é disparado.

A gestora e a consultoria respondem pelo PUT no próprio apontamento; o cedente responde pelo PUT em /response. O corpo e a resposta são os mesmos.

Disponível em

Perfil	Host	Permissão exigida
Gestora	`manager-api`	Escrita
Consultoria	`consultant-api`	Cadastrar Cedente

URL base de cada host: Ambientes (Hosts).

Request (gestora e consultoria)

ENDPOINT

/assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotation/ANNOTATION_KEY

MÉTODO

PUT

Disponível em

Perfil	Host	Permissão exigida
Cedente	`assignor-api`	Escrita

URL base de cada host: Ambientes (Hosts).

Request (cedente)

ENDPOINT

/assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotation/ANNOTATION_KEY/response

MÉTODO

PUT

Request Body

Request Body
{
    "response": "Segue autos do processo.",
    "document_b64": "JVBERi0xLjQK..."
}

Objeto de Resposta

Campo	Tipo	Descrição	Caracteres
`response` *	string	Texto de resposta ao apontamento.	1 - 3000
`document_b64`	string	Arquivo PDF codificado em Base64. Até 20 MB.	-

*Campos obrigatórios.

Response

STATUS

202

Response Body
{
    "annotation_key": "1f2e3d4c-5b6a-4c8d-9e0f-1a2b3c4d5e6f",
    "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4",
    "status": "closed",
    "origin_type": "compliance",
    "annotation_datetime": "2025-01-22T20:30:23Z",
    "message": "Anexar detalhes do processo XXXXXXXXXXX.",
    "response": "Segue autos do processo.",
    "response_datetime": "2025-01-23T14:05:11Z",
    "attached_document_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a"
}

Erros

Status	Código	Quando acontece
404	`ASR000004`	`assignor_registry_key` não encontrado ou o agente não tem acesso a esse cedente.
404	`ASR000033`	`analysis_key` não encontrado.
404	`ASR000043`	`annotation_key` não pertence à análise indicada.
400	`ASR000045`	O apontamento não está `open`.
400	`ASR000044`	O apontamento já foi respondido. Cada apontamento aceita uma única resposta.
400	`ASR000005`	`document_b64` não é Base64 válido.
400	`ASR000060`	O conteúdo de `document_b64` não é um PDF.
400	`ASR000059`	O PDF passa de 20 MB.

Erros de autenticação, permissão e host: veja Erros da API.

Consulta de Documento do Apontamento

Recupera uma URL temporária para download do documento anexado a um apontamento. A DOCUMENT_KEY é o attached_document_key do apontamento.

Disponível em

Perfil	Host	Permissão exigida
Gestora	`manager-api`	Leitura
Consultoria	`consultant-api`	Ler Cedentes
Cedente	`assignor-api`	Leitura

URL base de cada host: Ambientes (Hosts).

Request

ENDPOINT

/assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotation/ANNOTATION_KEY/document/DOCUMENT_KEY

MÉTODO

GET

Response

STATUS

200

Response Body
{
    "document_url": "https://URL_TEMPORARIA_DO_DOCUMENTO"
}

信息

A document_url retornada é uma URL pré-assinada com validade de 24 horas.

Erros

Status	Código	Quando acontece
404	`ASR000004`	`assignor_registry_key` não encontrado ou o agente não tem acesso a esse cedente.
404	`ASR000033`	`analysis_key` não encontrado.
404	`ASR000043`	`annotation_key` não pertence à análise indicada.
404	`ASR000006`	`DOCUMENT_KEY` não é o documento anexado ao apontamento.

Erros de autenticação, permissão e host: veja Erros da API.

Objeto de Apontamento

Campo	Tipo	Descrição
`annotation_key`	string	Identificador único do apontamento.
`analysis_key`	string	Chave da análise à qual o apontamento pertence.
`assignor_registry_key`	string	Chave do cedente.
`status`	string	Status atual do apontamento. Ver Annotation Status.
`origin_type`	string	Origem do apontamento. Ver Annotation Origin Type.
`annotation_datetime`	string	Data e hora de criação do apontamento (ISO 8601).
`message`	string	Mensagem do apontamento registrada pela equipe da QI DTVM.
`response`	string	Resposta enviada pelo agente (presente após a resposta).
`response_datetime`	string	Data e hora da resposta (presente após a resposta).
`attached_document_key`	string	Chave do documento anexado à resposta (quando houver).

Annotation Status

Enumerador	Descrição
open	Aberto e aguardando resposta do agente.
closed	Respondido e encerrado. A QI DTVM pode reabri-lo (volta a `open`).

Annotation Origin Type

Enumerador	Descrição
compliance	Apontamento originado pela equipe de Compliance (análise manual).
risk_analysis	Apontamento originado pela equipe de Risco.
internal	Apontamento originado na validação interna.

Consulta Paginada de Apontamentos​

Request​

Query params​

Response​

Erros​

Consulta de Apontamento por Chave​

Request​

Response​

Erros​

Resposta ao Apontamento​

Request (gestora e consultoria)​

Request (cedente)​

Request Body​

Objeto de Resposta​

Response​

Erros​

Consulta de Documento do Apontamento​

Request​

Response​

Erros​

Objeto de Apontamento​

Annotation Status​

Annotation Origin Type​

Consulta Paginada de Apontamentos

Request

Query params

Response

Erros

Consulta de Apontamento por Chave

Request

Response

Erros

Resposta ao Apontamento

Request (gestora e consultoria)

Request (cedente)

Request Body

Objeto de Resposta

Response

Erros

Consulta de Documento do Apontamento

Request

Response

Erros

Objeto de Apontamento

Annotation Status

Annotation Origin Type