> 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/identity-api/identity-api-reference/onboarding/ocr/ocr-document.md). # Leitor de documentos Este serviço é usado para ler informações de uma imagem de documento com **tecnologia OCR da FacePhi** e organizar as informações em campos. O serviço pode lidar com diferentes tipos de documentos, incluindo cédulas de identidade, cartões de estrangeiro, faturas e PDFs. É necessário especificar o **tipo de documento** e o **modelo** para processar o documento corretamente. Para uma lista completa de tipos de documentos e modelos suportados, veja [Documentos suportados por OCR](#documentos-soportados-por-ocr). ### Documentos suportados por OCR #### Tipos de documento O serviço OCR pode processar diferentes tipos de documentos. Use o parâmetro `type` para especificar o tipo de documento a processar: | Tipo | Valor | Descrição | | --------------------- | -------------- | ------------------------------------------- | | Cédula de identidade | `id_card` | Cédulas ou cartões de identidade nacionais | | Cartão de estrangeiro | `foreign_card` | Cartões de identificação de estrangeiros | | PDF | `pdf` | Documentos PDF que exigem processamento OCR | | Fatura | `invoice` | Documentos de faturamento | #### Modelos suportados por tipo de documento *Cédulas de identidade (ID Cards)* Para cédulas de identidade, usar o código do país **ISO 3166-1 alpha-3** como parâmetro `model`: | País | Código ISO | | --------- | ---------- | | Argentina | `ARG` | | México | `MEX` | *Cartões de estrangeiro (Foreign Cards)* Para cartões de estrangeiro, usar os seguintes códigos como parâmetro `model`: | País | Código ISO | | ------ | ---------- | | México | `MEX` | *Faturas (Invoices)* Para faturas, usar o código do fornecedor como parâmetro `model`: | Fornecedor | Código | | ---------- | -------- | | TELMEX | `TELMEX` | | CFE | `CFE` | *Documentos PDF* Para documentos PDF, usar o código do tipo de documento como parâmetro `model`: | Tipo de documento | Código | | ------------------ | ------- | | IVA: El Salvador | `IVA` | | RENTA: El Salvador | `RENDA` | ### Endpoint ``` POST /ocr ``` ### Cabeçalhos | Nome | Tipo | Obrigatório | Descrição | | ------------- | ------ | ----------- | ------------------------------------------------------------- | | **x-api-key** | string | **Sim** | API key de autorização de acesso. | | **family** | string | Não | Valor: **Onboarding**. Obrigatório com o serviço de Tracking. | {% hint style="info" %} Todas as chamadas aos Endpoints para Tracking com **Identity Platform** devem conter o cabeçalho `family`. {% endhint %} ### Corpo da solicitação **Content-Type:** `application/json` #### Parâmetros | Parâmetro | Tipo | Obrigatório | Descrição | | ---------------------- | --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | string | **Sim** | Tipo de documento a processar. Somente podem ser usados os tipos permitidos na configuração do tenant. Valores possíveis: `id_card`, `passport`, `driver_license`, `foreign_card`, `invoice`, `pdf` | | `model` | string | **Sim** | Identificador do modelo de documento a processar. Para documentos de identidade, usar o código do país **ISO 3166-1 alpha-3**. Para faturas ou documentos PDF, usar os códigos específicos fornecidos pela FacePhi. | | `files` | string\[] | **Sim** | Imagens do documento codificadas em **Base64** (RFC4648). **Máximo de duas imagens** por solicitação. A primeira imagem é tratada como o lado frontal. | | `isCropped` | boolean | Não | Indica se as imagens fornecidas já estão recortadas. **Valor padrão:** `false` | | `forceDetection` | boolean | Não | Força a detecção OCR mesmo se a detecção automática do documento falhar. **Valor padrão:** `false` | | `retrieveImages` | boolean | Não | Retorna imagens recortadas na resposta quando suportado para o tenant configurado. **Valor padrão:** `false` | | `tracking` | object | Não | Objeto que representa as informações de rastreamento necessárias. | | `tracking.extraData` | string | Não | Token gerado pelo SDK Mobile/Web. Contém informações de rastreamento tokenizadas com a Plataforma. | | `tracking.operationId` | string | Não | Identificador de operação gerado pelo SDK Mobile/Web. | #### Exemplo de solicitação ```json { "type": "pdf", "model": "IVA", "files": ["JVBERi0xLjQKJeLjz9MKNSAwIG9iago8P..."], "tracking": { "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...", "operationId": "123e4567-e89b-12d3-a456-426614174000" } } ``` ### 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. | | `serviceResultLog` | string | Campo descritivo do resultado da execução do serviço. | | `timestamp` | string | Momento em que o serviço finalizou o processamento. | | `serviceTransactionId` | string | Identificador de transação associado à solicitação processada pela API. | | `serviceResult` | object | Objeto com o resultado do OCR contendo os **campos extraídos**. | | `serviceTime` | string | Tempo total de execução do serviço **(milissegundos)**. | #### Código de Resultado do Serviço O `serviceResultCode` indica o resultado geral da execução do serviço: | serviceResultCode | Descrição | Código HTTP | | ----------------- | -------------------------------------------------------------------------------------- | ----------- | | 0 | A execução do serviço foi bem-sucedida, o módulo processou a solicitação corretamente. | 200 | #### Exemplo de resposta ```json { "serviceResultCode": 200, "serviceResultLog": "Service executed ok", "timestamp": "2024-07-12T09:43:36Z", "serviceTransactionId": "99999999-9999-9999-9999-999999999999", "serviceResult": { "dictionary": { "CommercialName": "Example Comercial Name", "DeclarationNumber": "11111111111", "EconomicActivity": "National Transports", "NIT": "9999-999999-999-9", "NRC": "999999-9", "Name": "John Doe", "TaxedPeriod": "04 2021" }, "model": "IVA", "side": "front", "type": "pdf", "version": "2021" }, "serviceTime": "638" } ``` #### `400` Requisição inválida ```json { "status": 400, "title": "Bad Request", "detail": "Invalid request.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400", "errors": [] } ``` #### `401` Não autorizado ```json { "message": "Unauthorized" } ``` #### `403` Proibido ```json { "Message": "User is not authorized to access this resource with an explicit deny" } ``` #### `502` Gateway inválido ```json { "status": 502, "title": "Bad Gateway", "detail": "Server got an invalid response.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502" } ``` #### `504` Tempo esgotado no gateway ```json { "message": "Endpoint request timed out" } ```