Apontamentos da análise do fornecedor
Durante a revisão manual (in_manual_analysis ou in_compliance_analysis), o analista da QI Tech pode abrir um apontamento: um pedido de esclarecimento ou de documento. A análise não é aprovada enquanto houver apontamento aberto. Nessa fase, responder a um apontamento é a única forma de anexar um documento.
Status do apontamento
| Status | Descrição |
|---|---|
opened | Aberto pela QI Tech, aguardando resposta. |
closed | Respondido pela gestora, ou fechado automaticamente quando a análise terminou. |
Para saber se há apontamento aberto, liste os apontamentos da análise com status=opened. O filtro annotation_status=opened da listagem de fornecedores olha só o apontamento mais recente da última análise: um apontamento mais antigo ainda aberto não aparece nele.
Listar apontamentos
| Perfil | Host | Permissão exigida |
|---|---|---|
| Gestora | manager-api | Leitura |
| Consultoria | consultant-api | Integração ativa |
URL base de cada host: Ambientes (Hosts).
Parâmetros de consulta
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
status | string | Não | opened ou closed. Aceita vários valores separados por vírgula. |
limit | integer | Não | Itens por página, de 0 a 1000. Padrão: 10. |
page | integer | Não | Página, a partir de 0. Padrão: 0. |
Devolve os apontamentos da análise, do mais recente para o mais antigo.
Resposta
{
"data": [
{
"annotation_key": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
"annotation_message": "Enviar comprovante de endereço atualizado.",
"annotation_response": null,
"annotation_datetime": "2026-11-03 10:00:00.527114",
"analysis_key": "8c2a6f0e-1b3d-4f7a-9c1e-2a4b6d8f0c13",
"status": "opened",
"attached_document_key": null,
"response_datetime": null
}
],
"limit": 10,
"page": 0,
"is_last_page": true
}
Atributos de cada apontamento
| Campo | Tipo | Descrição |
|---|---|---|
annotation_key | string | Chave do apontamento (UUID). |
annotation_message | string | Pedido do analista, até 200 caracteres. |
annotation_response | string | Resposta da gestora, ou null. |
annotation_datetime | string | Abertura do apontamento. |
analysis_key | string | Análise do apontamento. |
status | string | opened ou closed. |
attached_document_key | string | Documento anexado na resposta, ou null. |
response_datetime | string | Momento da resposta, ou null. |
Consultar apontamento por chave
Permissão: Gestora (manager-api): Leitura. Consultoria (consultant-api): Integração ativa. Devolve um apontamento, na estrutura de cada apontamento.
Responder apontamento
Responde ao apontamento e o fecha. Só é aceita com a análise em in_manual_analysis ou in_compliance_analysis; em qualquer outro status, inclusive com a análise concluída, devolve 405 (VRG000011).
A resposta pode levar um documento, de uma destas formas (nunca as duas):
- um documento novo, em Base64. Ele segue as regras de tipo e formato de Documentos e substitui o anterior do mesmo tipo;
- a chave de um documento que já está na análise.
| Perfil | Host | Permissão exigida |
|---|---|---|
| Gestora | manager-api | Escrita |
| Consultoria | consultant-api | Integração ativa |
URL base de cada host: Ambientes (Hosts).
{
"annotation_response": "Segue o comprovante de endereço atualizado.",
"name": "comprovante_endereco.pdf",
"document_type": "proof_of_residence",
"document_b64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwKL0xlbmd0aCAzIDAgUgo..."
}
{
"annotation_response": "O documento pedido já está na análise.",
"attached_document_key": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a"
}
Atributos do corpo
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
annotation_response | string | Sim | Resposta, até 1000 caracteres. |
document_b64 | string | Não | Documento novo em Base64. Exige name e document_type. |
name | string | Condicional | Nome do arquivo, de 1 a 255 caracteres. Obrigatório com document_b64. |
document_type | string | Condicional | Tipo do documento, um dos tipos aceitos. Obrigatório com document_b64. |
related_party_key | string | Não | Anexa o documento novo a esta parte relacionada em vez de ao fornecedor. Só com document_b64. |
attached_document_key | string | Não | Chave de um documento já enviado nesta análise (do fornecedor ou de uma parte). Não pode ser combinado com document_b64. |
Resposta
{
"annotation_key": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
"annotation_message": "Enviar comprovante de endereço atualizado.",
"annotation_response": "Segue o comprovante de endereço atualizado.",
"annotation_datetime": "2026-11-03 10:00:00.527114",
"analysis_key": "8c2a6f0e-1b3d-4f7a-9c1e-2a4b6d8f0c13",
"status": "closed",
"attached_document_key": "f3a4b5c6-d7e8-4f9a-0b1c-2d3e4f5a6b7c",
"response_datetime": "2026-11-03 11:20:07.381946+00:00"
}
Erros
Apontamento já respondido
Você já respondeu a este apontamento.
{
"title": "Annotation Already Responded",
"description": "Annotation with key 9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d is already responded.",
"translation": "Anotacao com chave 9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d esta respondida.",
"code": "VRG000013"
}
Análise fora da revisão manual
A análise não está em in_manual_analysis nem em in_compliance_analysis: por exemplo, já foi concluída ou foi retirada da fila. Um apontamento fechado automaticamente no fim da análise também não aceita mais resposta.
{
"title": "Operation Status does not allow annotations",
"description": "Operation with key 8c2a6f0e-1b3d-4f7a-9c1e-2a4b6d8f0c13 is on status approved, annotations can only be created or responded on in_manual_analysis or in_compliance_analysis.",
"translation": "Operacao com chave 8c2a6f0e-1b3d-4f7a-9c1e-2a4b6d8f0c13 esta no status approved, apontamentos so podem ser criados ou respondidos nos status in_manual_analysis ou in_compliance_analysis.",
"code": "VRG000011"
}
code | Quando acontece |
|---|---|
VRG000007 | A analysis_key não existe. Se a análise é de um fornecedor que você não vê, o código é VRG000014. |
VRG000012 | A annotation_key não existe ou não pertence a esta análise. |
VRG000071 | attached_document_key não é um documento desta análise. |
VRG000053 | related_party_key não está vinculada a esta análise ou está inactive. |
Os erros de tipo, tamanho e formato do documento novo são os de Documentos (VRG000081, VRG000082, VRG000080, VRG000067, VRG000097). Combinar document_b64 com attached_document_key, ou enviar name, document_type ou related_party_key sem document_b64, devolve QIT000001.
Erros de autenticação, permissão e host: veja Erros da API.