> ## Documentation Index
> Fetch the complete documentation index at: https://docs-platform.services-valid.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Como Usar a API

> Fluxo técnico ponta a ponta: envie um documento e receba o resultado da análise.

Esta página mostra o caminho completo de uma integração, do envio do documento até o resultado da análise chegar até você.

## Pré-requisitos

<Steps>
  <Step title="Projeto criado na plataforma">
    Todo documento enviado pertence a um projeto. Veja [Projetos](/plataforma/projetos).
  </Step>

  <Step title="Chave de API ativa">
    A chave identifica a organização e o projeto em cada requisição. Veja [Chaves de API](/plataforma/chaves-de-api).
  </Step>
</Steps>

## Visão geral do fluxo

<Steps>
  <Step title="Envie o documento" icon="file-arrow-up" iconType="regular">
    Uma chamada com o CPF e as imagens em base64. Você recebe um `documentId` na
    hora.
  </Step>

  <Step title="Receba o resultado" icon="badge-check" iconType="regular">
    Por webhook, se você configurou uma URL, ou por consulta ao `documentId`.
  </Step>
</Steps>

## 1. Envie o documento

Uma chamada a [Enviar Documentos](/plataforma/documentoscopia/api/post-documents-import) com o CPF do titular e as imagens em data URI base64:

```json theme={"theme":"catppuccin-latte"}
{
  "cpf": "12345678909",
  "documents": {
    "identification.front": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
    "identification.back": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
  },
  "selfie": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
}
```

Apenas `cpf` e `identification.front` são obrigatórios.

### Rastreando o envio com seu próprio identificador

O header opcional `x-client-id` aceita até 255 caracteres e é devolvido no webhook, em `metadata.clientId`. Use-o para correlacionar o resultado com o registro do seu lado sem precisar guardar o `documentId`.

A resposta traz o `documentId`, que identifica o documento em todas as consultas seguintes:

```json theme={"theme":"catppuccin-latte"}
{
  "requestId": "7d7a6f2b-8d9f-4f55-9a2d-ec8e7b4f1d0c",
  "documentId": "123e4567-e89b-12d3-a456-426614174000",
  "batchExternalId": "7d7a6f2b-8d9f-4f55-9a2d-ec8e7b4f1d0c",
  "backofficeBatchId": "229462"
}
```

## 2. Receba o resultado

### Por webhook

Com `PARAMETER_WEBHOOK_URL` configurado, a plataforma faz um `POST` nessa URL assim que a análise termina, com o documento e o resultado completos. O campo `event.type` distingue os dois produtos:

| `event.type`                     | Origem                              |
| :------------------------------- | :---------------------------------- |
| `docs-gateway.document.finished` | Análise de autenticidade documental |
| `docs-gateway.ocr.finished`      | Extração de dados (OCR)             |

O envelope completo, os headers da chamada, a validação da assinatura e o que o seu endpoint deve responder estão em [Webhook de Resultado](/plataforma/documentoscopia/api/webhook-resultado).

<Warning>
  Responda com um status HTTP de sucesso. A entrega não é repetida em caso de
  falha — se o seu endpoint estiver indisponível, recupere o resultado pela
  consulta ao `documentId`.
</Warning>

### Por consulta

Sem webhook configurado, consulte o documento pelo identificador em [Consultar Documento por ID](/plataforma/documentoscopia/api/get-document-by-id). O campo `result` fica preenchido quando o status chega em `COMPLETED`.

### Lendo o resultado

| `result.status` | O que fazer                                              |
| :-------------- | :------------------------------------------------------- |
| `APPROVED`      | Documento considerado autêntico. Siga com a jornada      |
| `REJECTED`      | Documento reprovado                                      |
| `MANUAL_REVIEW` | Análise inconclusiva. O caso precisa de avaliação humana |
| `ERROR`         | Não foi possível concluir a análise                      |

O campo `result.confidenceScore` traz o índice de avaliação de autenticidade apurado na análise, e `result.raw_response` traz o retorno completo. Em uma rejeição, o motivo está em `result.raw_response.penalidades` — veja o detalhamento dos campos em [Consultar Documento por ID](/plataforma/documentoscopia/api/get-document-by-id).

<Note>
  `MANUAL_REVIEW` não é um erro. Ele indica que a análise não reuniu evidência
  suficiente para aprovar nem para rejeitar. Trate esse caso na sua jornada
  desde o início da integração.
</Note>

## Próximos passos

<Columns cols={2}>
  <Column>
    <Card title="Enviar Documentos" icon="file-arrow-up" href="/plataforma/documentoscopia/api/post-documents-import">
      A referência completa do endpoint de envio
    </Card>
  </Column>

  <Column>
    <Card title="Webhook de Resultado" icon="webhook" href="/plataforma/documentoscopia/api/webhook-resultado">
      O envelope completo e a validação da assinatura
    </Card>
  </Column>

  <Column>
    <Card title="Presets de Workflow" icon="sliders" href="/plataforma/documentoscopia/api/get-workflow-presets">
      Os modos de análise e prazos disponíveis
    </Card>
  </Column>
</Columns>