> 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/form-ocr.md).

# OCR de formulário

Serviço que extrai os campos de impressos não identitários: faturas, recibos e PDFs genéricos.

É um serviço exclusivamente online: `source` aceita apenas o valor `FILE`, não leva cabeçalho `operation-id` e seus assets não participam do ciclo de operação. Um impresso é identificado por seu emissor (`issuerCode`) e não por seu país.

### Endpoint

```
POST /form/ocr
```

### Cabeçalhos

| Nome              | Tipo   | Obrigatório | Descrição                                                                                                                   |
| ----------------- | ------ | ----------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string | **Sim**     | Token de consumer no formato `Bearer <token>`. Ver [Autenticação](/docs.facephi-pt-br/api-rest/midapi-v2/autenticacion.md). |
| **consumer-id**   | string | **Sim**     | Identificador do consumer.                                                                                                  |

### Corpo da solicitação

**Content-Type:** `application/json`

#### Parâmetros

| Parâmetro        | Tipo    | Obrigatório | Descrição                                                                                 |
| ---------------- | ------- | ----------- | ----------------------------------------------------------------------------------------- |
| `source`         | string  | **Sim**     | Apenas `FILE`. Qualquer outro valor é rejeitado com `400`.                                |
| `files`          | array   | **Sim**     | Páginas do impresso em ordem, em Base64. Um impresso pode ter qualquer número de páginas. |
| `formType`       | string  | **Sim**     | Tipo de impresso: `INVOICE` ou `PDF`.                                                     |
| `issuerCode`     | string  | **Sim**     | Código do emissor do impresso, acordado com o emissor. Não é um código de país.           |
| `retrieveImages` | boolean | Não         | Retorna as imagens recortadas na resposta. Por padrão `false`.                            |

#### Exemplo de solicitação

```json
{
  "source": "FILE",
  "files": ["<base64 página 1>", "<base64 página 2>"],
  "formType": "INVOICE",
  "issuerCode": "TELMEX"
}
```

### Respostas

#### `200` Sucesso

#### Parâmetros de resposta

| Parâmetro              | Tipo    | Descrição                                                                  |
| ---------------------- | ------- | -------------------------------------------------------------------------- |
| `serviceResultCode`    | integer | Código que indica o resultado geral da execução do serviço. `0` é sucesso. |
| `serviceResultLog`     | string  | Campo descritivo do resultado da execução do serviço.                      |
| `serviceTransactionId` | string  | Identificador de transação associado à solicitação processada.             |
| `serviceTime`          | string  | Tempo total de processamento **(milissegundos)**.                          |
| `timestamp`            | string  | Momento em que o processamento foi concluído, em formato **ISO 8601**.     |
| `serviceResult`        | object  | Resultado do OCR com os campos extraídos do impresso.                      |

{% hint style="warning" %}
`FORM_OCR` é um provisionamento próprio, separado de `DOCUMENT_OCR`. Um consumer que processe faturas precisa que este serviço seja habilitado.
{% endhint %}

#### Outras respostas

| Código | Descrição                                                                                                                                                                                 |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `source` diferente de `FILE`, `formType` desconhecido ou campo obrigatório ausente.                                                                                                       |
| `401`  | Token ausente, inválido ou expirado.                                                                                                                                                      |
| `403`  | O consumer não está provisionado com o serviço `FORM_OCR`.                                                                                                                                |
| `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. |

O corpo de uma resposta de erro tem o formato descrito em [MIDAPI v2](/docs.facephi-pt-br/api-rest/midapi-v2.md#respuestas-de-error).