> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/api-rest/midapi-v2/document-services/document-validation/iniciar-validacion.md). # Iniciar validação Inicia uma validação documental enviando as `fileKeys` dos assets previamente [carregados no armazenamento](/docs.facephi-pt-br/api-rest/midapi-v2/document-services/document-validation/subida-de-assets.md). O serviço responde imediatamente com um `transactionId`. O resultado é obtido por meio de [polling](/docs.facephi-pt-br/api-rest/midapi-v2/document-services/document-validation/consultar-estado.md). {% hint style="info" %} 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](/docs.facephi-pt-br/api-rest/midapi-v2/document-services/document-validation/respuesta-de-resultado.md), que inclui o **catálogo completo de códigos de motivo** (geral e granular). {% endhint %} ### Endpoint ``` POST /document/validate ``` ### Cabeçalhos | Nome | Tipo | Obrigatório | Descrição | | ----------------- | ------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Authorization** | string | **Sim** | Token de consumer no formato `Bearer ` (ver [Autenticação](/docs.facephi-pt-br/api-rest/midapi-v2/autenticacion.md)). | | **consumer-id** | string | **Sim** | Identificador do consumer. | | **operation-id** | string | **Sim** | Identificador da [operação](/docs.facephi-pt-br/api-rest/midapi-v2/operations.md) à 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 ```json { "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" } } ``` {% hint style="warning" %} 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`. {% endhint %} 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](/docs.facephi-pt-br/api-rest/midapi-v2/storage.md). ### 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 ```json { "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. |