> 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-ocr.md). # OCR de documentos Serviço que extrai os campos do Documento de identidade. Admite a frente e, opcionalmente, o verso. Os assets são fornecidos em linha ou por referência, de acordo com o valor de `source`. ### Endpoint ``` POST /document/ocr ``` ### 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 | Condicional | Identificador da operação à qual pertencem os assets referenciados. Obrigatório quando `source` é `FILE_KEY`. Ver [Armazenamento](/docs.facephi-pt-br/api-rest/midapi-v2/storage.md). | ### Corpo da solicitação **Content-Type:** `application/json` #### Parâmetros | Parâmetro | Tipo | Obrigatório | Descrição | | ---------------- | ------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `source` | string | **Sim** | Modo como os assets são fornecidos: `FILE_KEY` para chaves de assets armazenados, `FILE` para conteúdo em Base64. Ver [Armazenamento](/docs.facephi-pt-br/api-rest/midapi-v2/storage.md). | | `files` | array | **Sim** | Uma ou duas entradas: índice `0` a frente, índice `1` o verso. Chaves de asset ou conteúdos em Base64, de acordo com `source`. | | `documentType` | string | **Sim** | Tipo de documento: `ID_CARD`, `PASSPORT`, `DRIVING_LICENSE` ou `FOREIGN_CARD`. | | `countryCode` | string | **Sim** | País emissor do documento, como código **ISO 3166-1 alpha-3**. | | `isCropped` | boolean | Não | Indica que as imagens já vêm recortadas. Por padrão `false`. | | `forceDetection` | boolean | Não | Força a detecção mesmo que a detecção automática do documento falhe. Por padrão `false`. | | `retrieveImages` | boolean | Não | Retorna as imagens recortadas na resposta. Por padrão `false`. | `files` aceita no máximo duas entradas. Os impressos multipágina são processados em [Form OCR](/docs.facephi-pt-br/api-rest/midapi-v2/document-services/form-ocr.md). #### Exemplo de solicitação ```json { "source": "FILE_KEY", "files": [ "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_FRONT_DOCUMENT", "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_BACK_DOCUMENT" ], "documentType": "ID_CARD", "countryCode": "ARG" } ``` ### 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 documento. | #### Exemplo de resposta ```json { "serviceResultCode": 0, "serviceResultLog": "Service executed ok", "serviceTime": "820", "serviceResult": { "side": "front", "type": "passport", "model": "ESP", "version": "1", "dictionary": { "LastName": "DOE", "FirstName": "JANE", "DocumentNumber": "PAL140268", "DateOfBirth": "10/07/1987" } } } ``` #### Outras respostas | Código | Descrição | | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | Campo obrigatório ausente ou valor não admitido; falta o cabeçalho `operation-id` havendo referências; ou uma chave não tem a forma `{operationId}/{CONTEXTO}` ou declara um contexto que o espaço reservado não admite. | | `403` | O consumer não está provisionado com o serviço `DOCUMENT_OCR`. | | `404` | A operação declarada em `operation-id` não existe ou pertence a outro consumer. | | `409` | Um asset referenciado contém um conteúdo já processado em outra operação. | | `410` | A operação declarada em `operation-id` expirou. | | `422` | Uma chave nomeia uma operação diferente da declarada em `operation-id`, ou o contexto não tem nenhum asset armazenado. | | `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. O serviço subjacente não é invocado e a chamada não é faturada. | 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).