Iniciar validação

Inicia uma validação documental enviando as fileKeys dos assets previamente carregados no armazenamento. O serviço responde imediatamente com um transactionId. O resultado é obtido por meio de polling.

O diagnóstico final (APPROVED, DECLINED ou DOUBTFUL), o motivo (rejectionReason) e os sinais de verificação individuais (diagnostics[]) são detalhados na resposta de resultado, que inclui o catálogo completo de códigos de motivo (geral e granular).

Endpoint

POST /document/validate

Cabeçalhos

Nome	Tipo	Obrigatório	Descrição
Authorization	string	Sim	Token de consumer no formato Bearer <token> (ver Autenticação).
consumer-id	string	Sim	Identificador do consumer.
operation-id	string	Sim	Identificador da operação à qual pertencem os assets, conforme devolvido por POST /operation. Todas as fileKey da solicitação devem nomear esta mesma operação.

Corpo da solicitação

Content-Type: application/json

Cada asset é referenciado por uma chave de função fixa (document_front, document_back, face), com seu type de contexto e seu fileKey:

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
document_front	object	Sim	Asset da frente do documento.
document_front.type	string	Sim	TOKEN_FRONT_DOCUMENT.
document_front.fileKey	string	Sim	fileKey retornada por POST /storage, com o formato {operationId}/TOKEN_FRONT_DOCUMENT, enviada sem modificações.
document_back	object	Não	Asset do verso do documento.
document_back.type	string	Não	TOKEN_BACK_DOCUMENT.
document_back.fileKey	string	Não	fileKey com o formato {operationId}/TOKEN_BACK_DOCUMENT.
face	object	Não	Asset da selfie do titular.
face.type	string	Não	TOKEN_FACE_IMAGE.
face.fileKey	string	Não	fileKey com o formato {operationId}/TOKEN_FACE_IMAGE.

O campo type só admite esses três contextos, cada um em seu espaço.

Exemplo de solicitação

{
  "document_front": {
    "type": "TOKEN_FRONT_DOCUMENT",
    "fileKey": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_FRONT_DOCUMENT"
  },
  "document_back": {
    "type": "TOKEN_BACK_DOCUMENT",
    "fileKey": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_BACK_DOCUMENT"
  },
  "face": {
    "type": "TOKEN_FACE_IMAGE",
    "fileKey": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_FACE_IMAGE"
  }
}

A fileKey é enviado tal como foi retornada por POST /storage, com o formato {operationId}/{CONTEXTO}. Adicionar o contexto por conta própria o deixa duplicado e o asset não resolve.

O type de cada espaço tem que coincidir com o contexto que declara seu fileKey. Se não coincidirem, a solicitação é rejeitada com 400.

Document Validation só admite referência: sua solicitação não traz o campo source e a cabeçalho operation-id é obrigatória sempre.

Validações de entrada

• document_front é obrigatório, com type = TOKEN_FRONT_DOCUMENT e uma fileKey resolúvel.

• Se forem incluídos document_back ou face, seu type deve coincidir com o esperado nesse espaço e com o contexto que declara seu fileKey.

• consumer-id e operation-id não podem estar vazios.

• Cada fileKey deve ter o formato {operationId}/{CONTEXTO}, nomear a operação declarada no cabeçalho, trazer o contexto correspondente ao seu espaço e ter um asset realmente armazenado.

• Se a solicitação for inválida (bad request), ela é rejeitada com um erro 4xx e a transação não é criada. Outras falhas ao iniciar o processamento criam a transação com status = ERROR.

O formato da chave e os contextos disponíveis estão em Armazenamento.

Respostas

202 Aceito

Parâmetros de resposta

Parâmetro	Tipo	Descrição
transactionId	string	Identificador único da transação de validação.
status	string	PROCESSED (aceita corretamente) ou ERROR (não foi possível iniciar).
timestamp	string	Marca temporal de criação da transação no formato ISO 8601.

Exemplo de resposta

{
  "transactionId": "1c7d...e9",
  "status": "PROCESSED",
  "timestamp": "2026-06-26T12:00:00.000Z"
}

Outras respostas

Código	Significado
400	A solicitação não passa nas validações de entrada: asset obrigatório ausente, type que não coincide com o contexto da chave, cabeçalho vazio, chave que não tem o formato {operationId}/{CONTEXTO}, ou contexto que não corresponde a esse espaço. A transação não é criada.
401	Token ausente, inválido ou expirado.
403	O consumer não está provisionado com o serviço DOCUMENT_ANTIFRAUD.
404	A operação não existe ou pertence a outro consumer.
409	Um asset referenciado contém um conteúdo que já foi processado em outra operação.
410	A operação expirou.
422	Uma fileKey nomeia uma operação diferente da declarada no cabeçalho, ou não há nenhum asset armazenado nesse contexto.
429	O consumer excedeu seu limite de taxa de requisições, ou um asset referenciado esgotou seu orçamento de invocações neste Endpoint. No primeiro caso a resposta inclui Retry-After, X-RateLimit-Limit e X-RateLimit-Burst, e esperar resolve; no segundo, não.
503	A persistência do serviço não está disponível temporariamente.