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.

informação

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.

Consulta Paginada de Apontamentos

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

Request

ENDPOINT

/assignor_registry/public/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 Tratáveis

Código	HTTP	Causa	Como resolver
ASR000026	404	Agente não encontrado para a `AGENT-KEY` informada.	Verificar se a chave do agente autenticado está correta.

Consulta de Apontamento por Chave

Request

ENDPOINT

/assignor_registry/public/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"
}

informação

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 Tratáveis

Código	HTTP	Causa	Como resolver
ASR000026	404	Agente não encontrado para a `AGENT-KEY` informada.	Verificar se a chave do agente autenticado está correta.
ASR000004	404	Cedente não encontrado para o `assignor_registry_key` informado.	Verificar se o `assignor_registry_key` está correto e pertence ao agente autenticado.
ASR000033	404	Análise não encontrada para o `analysis_key` informado.	Verificar se o `analysis_key` está correto.
ASR000043	404	Apontamento não encontrado para o `annotation_key` informado.	Verificar se o `annotation_key` pertence à análise indicada.

Resposta ao Apontamento

Envia a resposta do agente a um apontamento. Opcionalmente, é possível anexar um documento em PDF que comprove ou complemente a resposta.

Request

ENDPOINT

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

MÉTODO

PUT

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

Objeto de Resposta

Campo	Tipo	Descrição	Caracteres
`response` *	string	Texto de resposta ao apontamento.	1 - 3000
`document_b64`	string	Binário do arquivo em PDF, codificado em Base64.	-

*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 Tratáveis

Código	HTTP	Causa	Como resolver
ASR000026	404	Agente não encontrado para a `AGENT-KEY` informada.	Verificar se a chave do agente autenticado está correta.
ASR000004	404	Cedente não encontrado para o `assignor_registry_key` informado.	Verificar se o `assignor_registry_key` está correto e pertence ao agente autenticado.
ASR000033	404	Análise não encontrada para o `analysis_key` informado.	Verificar se o `analysis_key` está correto.
ASR000043	404	Apontamento não encontrado para o `annotation_key` informado.	Verificar se o `annotation_key` pertence à análise indicada.
ASR000045	400	O apontamento não está mais em status `open` e não aceita mais respostas.	Só é possível responder apontamentos com status `open`.
ASR000044	400	O apontamento já foi respondido.	Cada apontamento aceita apenas uma resposta.
ASR000005	400	Formato de arquivo inválido.	Enviar `document_b64` como string em base64 válida.
ASR000060	400	O arquivo enviado não é um PDF válido.	O conteúdo decodificado de `document_b64` deve ser um PDF.
ASR000059	400	Tamanho do arquivo excede o limite.	Reduzir o tamanho do PDF antes de enviar (limite informado na mensagem do erro).

Consulta de Documento do Apontamento

Recupera uma URL temporária para download do documento anexado a um apontamento.

Request

ENDPOINT

/assignor_registry/public/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://assignor-bucket.s3.amazonaws.com/8e515a17-8b4d-49a3-aed6-47c9574e426a?..."
}

informação

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

Erros Tratáveis

Código	HTTP	Causa	Como resolver
ASR000026	404	Agente não encontrado para a `AGENT-KEY` informada.	Verificar se a chave do agente autenticado está correta.
ASR000004	404	Cedente não encontrado para o `assignor_registry_key` informado.	Verificar se o `assignor_registry_key` está correto e pertence ao agente autenticado.
ASR000033	404	Análise não encontrada para o `analysis_key` informado.	Verificar se o `analysis_key` está correto.
ASR000043	404	Apontamento não encontrado para o `annotation_key` informado.	Verificar se o `annotation_key` pertence à análise indicada.
ASR000006	404	Documento não encontrado para o `document_key` informado.	Verificar se o `document_key` corresponde ao documento anexado ao apontamento.

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
created	Apontamento criado, ainda não disponibilizado.
open	Aberto e aguardando resposta do agente.
closed	Respondido e encerrado.

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 Tratáveis​

Consulta de Apontamento por Chave​

Request​

Response​

Erros Tratáveis​

Resposta ao Apontamento​

Request​

Objeto de Resposta​

Response​

Erros Tratáveis​

Consulta de Documento do Apontamento​

Request​

Response​

Erros Tratáveis​

Objeto de Apontamento​

Annotation Status​

Annotation Origin Type​

Consulta Paginada de Apontamentos

Request

Query params

Response

Erros Tratáveis

Consulta de Apontamento por Chave

Request

Response

Erros Tratáveis

Resposta ao Apontamento

Request

Objeto de Resposta

Response

Erros Tratáveis

Consulta de Documento do Apontamento

Request

Response

Erros Tratáveis

Objeto de Apontamento

Annotation Status

Annotation Origin Type