> 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/api-rest/identity-api/identity-api-reference/onboarding/ocr/ocr-document.md). # Document Reader Este servicio se utiliza para leer información de una imagen de documento con **tecnología OCR de FacePhi** y organizar la información en campos. El servicio puede manejar diferentes tipos de documentos incluyendo cédulas de identidad, tarjetas de extranjería, facturas y PDFs. Es necesario especificar el **tipo de documento** y el **modelo** para procesar el documento correctamente. Para una lista completa de tipos de documentos y modelos soportados, ver [Documentos soportados por OCR](#documentos-soportados-por-ocr). ### Documentos soportados por OCR #### Tipos de documento El servicio OCR puede procesar diferentes tipos de documentos. Usa el parámetro `type` para especificar el tipo de documento a procesar: | Tipo | Valor | Descripción | | ---------------------- | -------------- | ---------------------------------------------- | | Cédula de identidad | `id_card` | Cédulas o tarjetas de identidad nacionales | | Tarjeta de extranjería | `foreign_card` | Tarjetas de identificación de extranjeros | | PDF | `pdf` | Documentos PDF que requieren procesamiento OCR | | Factura | `invoice` | Documentos de facturación | #### Modelos soportados por tipo de documento *Cédulas de identidad (ID Cards)* Para cédulas de identidad, usar el código de país **ISO 3166-1 alpha-3** como parámetro `model`: | País | Código ISO | | --------- | ---------- | | Argentina | `ARG` | | México | `MEX` | *Tarjetas de extranjería (Foreign Cards)* Para tarjetas de extranjería, usar los siguientes códigos como parámetro `model`: | País | Código ISO | | ------ | ---------- | | México | `MEX` | *Facturas (Invoices)* Para facturas, usar el código del proveedor como parámetro `model`: | Proveedor | Código | | --------- | -------- | | TELMEX | `TELMEX` | | CFE | `CFE` | *Documentos PDF* Para documentos PDF, usar el código del tipo de documento como parámetro `model`: | Tipo de documento | Código | | ------------------ | ------- | | IVA: El Salvador | `IVA` | | RENTA: El Salvador | `RENTA` | ### Endpoint ``` POST /ocr ``` ### Headers | Nombre | Tipo | Requerido | Descripción | | ------------- | ------ | --------- | ------------------------------------------------------------- | | **x-api-key** | string | **Sí** | API key de autorización de acceso. | | **family** | string | No | Valor: **OnBoarding**. Requerido con el servicio de tracking. | {% hint style="info" %} Todas las llamadas a los Endpoints para tracking con **Identity Platform** deben contener el header `family`. {% endhint %} ### Cuerpo de la solicitud **Content-Type:** `application/json` #### Parámetros | Parámetro | Tipo | Requerido | Descripción | | ---------------------- | --------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | string | **Sí** | Tipo de documento a procesar. Solo se pueden utilizar los tipos permitidos en la configuración del tenant. Valores posibles: `id_card`, `passport`, `driver_license`, `foreign_card`, `invoice`, `pdf` | | `model` | string | **Sí** | Identificador del modelo de documento a procesar. Para documentos de identidad, usar el código de país **ISO 3166-1 alpha-3**. Para facturas o documentos PDF, usar los códigos específicos proporcionados por FacePhi. | | `files` | string\[] | **Sí** | Imágenes del documento codificadas en **Base64** (RFC4648). **Máximo de dos imágenes** por solicitud. La primera imagen se trata como el lado frontal. | | `isCropped` | boolean | No | Indica si las imágenes proporcionadas ya están recortadas. **Valor predeterminado:** `false` | | `forceDetection` | boolean | No | Fuerza la detección OCR incluso si la detección automática del documento falla. **Valor predeterminado:** `false` | | `retrieveImages` | boolean | No | Retorna imágenes recortadas en la respuesta cuando está soportado para el tenant configurado. **Valor predeterminado:** `false` | | `tracking` | object | No | Objeto que representa la información de seguimiento necesaria. | | `tracking.extraData` | string | No | Token generado por el SDK Mobile/Web. Contiene información de seguimiento tokenizada con la Plataforma. | | `tracking.operationId` | string | No | Identificador de operación generado por el SDK Mobile/Web. | #### Ejemplo de solicitud ```json { "type": "pdf", "model": "IVA", "files": ["JVBERi0xLjQKJeLjz9MKNSAwIG9iago8P..."], "tracking": { "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...", "operationId": "123e4567-e89b-12d3-a456-426614174000" } } ``` ### Respuestas #### `200` Éxito #### Parámetros de respuesta | Parámetro | Tipo | Descripción | | ---------------------- | ------- | -------------------------------------------------------------------------- | | `serviceResultCode` | integer | Código que indica el **resultado general** de la ejecución del servicio. | | `serviceResultLog` | string | Campo descriptivo del resultado de la ejecución del servicio. | | `timestamp` | string | Momento en que el servicio finalizó el procesamiento. | | `serviceTransactionId` | string | Identificador de transacción asociado a la solicitud procesada por la API. | | `serviceResult` | object | Objeto con el resultado del OCR conteniendo los **campos extraídos**. | | `serviceTime` | string | Tiempo total de ejecución del servicio **(milisegundos)**. | #### Service Result Code El `serviceResultCode` indica el resultado general de la ejecución del servicio: | serviceResultCode | Descripción | Código HTTP | | ----------------- | ------------------------------------------------------------------------------------ | ----------- | | 0 | La ejecución del servicio fue exitosa, el módulo procesó la solicitud correctamente. | 200 | #### Ejemplo de respuesta ```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` Bad Request ```json { "status": 400, "title": "Bad Request", "detail": "Invalid request.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400", "errors": [] } ``` #### `401` Unauthorized ```json { "message": "Unauthorized" } ``` #### `403` Forbidden ```json { "Message": "User is not authorized to access this resource with an explicit deny" } ``` #### `502` Bad Gateway ```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` Gateway Timeout ```json { "message": "Endpoint request timed out" } ```