Consultar status (polling)

Consulte o status de uma transação de validação até obter um estado terminal. Enquanto a transação não tiver sido finalizada, a resposta contém apenas o identificador e o status. Ao atingir um estado terminal com diagnóstico, inclui também a resposta de resultado completa.

Endpoint

GET /document/validate/{transactionId}

Cabeçalhos

Nome	Tipo	Obrigatório	Descrição
Authorization	string	Sim	Token de consumer no formato Bearer <token> (veja Autenticação).
consumer-id	string	Sim	Identificador do consumer.
operation-id	string	Sim	Identificador da operação da validação, o mesmo que foi enviado ao iniciá-la.

Parâmetros de rota

Parâmetro	Tipo	Obrigatório	Descrição
transactionId	string	Sim	Identificador de transação retornado por POST /document/validate.

Respostas

200 Sucesso (transação em andamento)

{
  "transactionId": "1c7d...e9",
  "status": "IN_PROGRESS"
}

200 Sucesso (transação terminal)

Quando a transação atinge um estado terminal com diagnóstico (COMPLETED), a resposta inclui também o diagnóstico completo. Veja Resposta de resultado.

Estados da transação

Status	Significado	Terminal?
PROCESSED	A transação foi criada e aceita para processamento.	Não
ERROR	Não foi possível criar/iniciar a transação (falha na solicitação inicial).	Sim
IN_PROGRESS	A validação está em andamento.	Não
COMPLETED	Há um diagnóstico disponível (APPROVED, DECLINED ou DOUBTFUL).	Sim
FAILED	Falha irrecuperável durante o processamento. Inclui failureReason.	Sim

O estado terminal COMPLETED é único para qualquer resultado com diagnóstico. Diante ERROR ou FAILED, não haverá diagnóstico nem OCR na resposta. O status FAILED inclui failureReason e timestamp.

failureReason

Quando status = FAILED, o campo failureReason descreve a causa da falha com uma mensagem genérica e estável. Estes são os valores possíveis:

failureReason	Significado / ação recomendada
A validação não pôde ser concluída	Falha transitória do processamento. É seguro tentar novamente iniciando uma nova transação com os mesmos ativos; se persistir, contate o suporte.
Erro interno de processamento	Erro inesperado durante o processamento. Tente novamente mais tarde; se persistir, contate o suporte.
Ativo não encontrado no armazenamento: <fileKey>	Não foi possível resolver um dos ativos referenciados. Verifique se as fileKeys existem e foram enviados corretamente antes de tentar novamente.
Token de ativo <front|back|face> inválido	O ativo indicado não é um token de captura válido. Capture/enviar novamente esse ativo e reinicie o processo.

failureReason é deliberadamente genérico: diferentes causas internas (incluindo os timeouts da análise) são agregadas em A validação não pôde ser concluída. O detalhe específico fica nos registros internos do serviço; se precisar diagnosticar um caso, compartilhe-o com o suporte junto com o transactionId.

Outras respostas

Código	Descrição
400	O cabeçalho operation-id está ausente ou vazia.
401	Token ausente, inválido ou expirado.
403	O consumer não está provisionado com o serviço DOCUMENT_ANTIFRAUD.
404	A transação não existe ou pertence a outro consumidor.
429	O consumer ultrapassou seu limite de taxa de requisições. A resposta inclui Retry-After com os segundos de espera, e X-RateLimit-Limit e X-RateLimit-Burst com os limites vigentes.
503	A persistência do serviço não está disponível temporariamente.

O corpo de uma resposta de erro tem o formato descrito em MIDAPI v2.

O 429 deste endpoint é o do limite de taxa, e convém levá-lo em conta ao escolher a cadência de sondagem: sondar a cada poucos milissegundos o provoca. A estratégia recomendada, por fases e com backoff, está em Boas práticas.