> 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/sdks/backend-sdk/ocr/technical_documentation/api_reference.md). # Guía de referencia de la API ## 1. Introducción Este apartado incluye la descripción de la API del servicio proporcionado en el producto **Facephi OCR Service**. ## 2. API REST De manera resumida, existen los siguientes puntos de entrada disponibles: ### `/api/v1/process` y `/api/v1/process_multi` Estos endpoints se utilizan para leer información de la imagen de un documento mediante la tecnología OCR de Facephi y clasificar la información en campos. La diferencia entre ambos endpoints es que el primero procesa únicamente el alfabeto latino, mientras que el segundo procesa múltiples alfabetos (latino, cirílico, árabe, chino, etc.). Significado de los parámetros: * `type` (opcional): Es necesario especificar el tipo de documento que se desea procesar, ya que nuestro servicio puede gestionar diferentes tipos de documentos. Valores disponibles en el JSON: **id\_card, passport, driver\_license, foreign\_card, invoice, pdf**. * Si no está presente, se utiliza `id_card`. * `model` (opcional): Este parámetro especifica el ID del documento que se va a procesar. En el caso de facturas o documentos PDF, consulte la lista siguiente. En caso contrario, este identificador corresponde al país de origen del documento. Para especificar este país, siga el estándar especificado en [ISO\_3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3). En el caso de **`invoice` o `pdf`**, utilice la clave de las tablas siguientes. * Si no está presente, se consideran todos los países. * `files`: Array de cadenas. Cada posición del array es un buffer de imagen en bruto codificado en base64 *RFC4648*. Máximo dos ficheros. La primera imagen será el anverso de un **id\_card**. * `isCropped` (opcional): Si la `image` ya está recortada y alineada, el servicio puede evitar realizar estas operaciones. Solo aplica a documentos `invoice`. * `forceDetection` (**OBSOLETO**, opcional): Si el documento `invoice` no tiene la relación de aspecto correcta, el servicio puede realizar una operación para corregirla y mejorar la detección del documento. Solo aplica a documentos `invoice`. * `retrieveImages` (opcional): El servicio devolverá la imagen recortada en base64 en el resultado final. * Si no está presente, se utiliza `false`. #### Tipos de documento soportados | Nombre del documento | parámetro `type` | | ---------------------- | ---------------- | | Documento de identidad | `id_card` | | Permiso de conducir | `driver_license` | | Tarjeta de extranjería | `foreign_card` | | PDF | `pdf` | | Factura | `invoice` | #### Modelos soportados por el intérprete v1 * [x] Argentina. `model` a utilizar: **arg** * Documento de identidad * [x] México. `model` a utilizar: **mex** * Documento de identidad * Tarjeta de extranjería #### Modelos soportados por el intérprete v2 Encontrará más información en [documentos soportados por país en la interpretación v2](https://github.com/facephi/facephi-gitbook-docs/tree/master/docs/sdks/backend-sdk/ocr/technical_documentation/api_reference/models_v2.md). #### Facturas soportadas * [x] TELMEX. `model` a utilizar: **telmex** * [x] CFE. `model` a utilizar: **cfe** * [ ] MOVISTAR * [ ] TELCEL * [ ] TELNOR * [ ] AT\&T * [ ] TOTALPLAY * [ ] IZZI #### PDF soportados * [x] IVA: El Salvador: modelo F07 v12, F07 v13 y F07 v14. `model` a utilizar: **IVA** * [x] RENTA: El Salvador: modelo F11 v14, F11 v15, F11 v17 y F11 v18. `model` a utilizar: **RENTA** **Versión y codificación de PDF soportadas** * [x] Versión de PDF: 1.4 o superior * [x] Codificación: iText 2.1.7, macOS Version Quartz PDFContext con la opción de texto incrustado habilitada. ### `/api/v1/health` El objetivo de este endpoint es garantizar que el servicio funciona correctamente. ### `/api/v1/version` Este endpoint devuelve la versión del servicio. ### `/api/v1/config` Este endpoint se utiliza para consultar (GET) y actualizar (POST) la configuración del servicio sin necesidad de reiniciarlo. Solo algunos parámetros son modificables en tiempo de ejecución. Los ajustes de arranque de la autenticación JWT se ocultan intencionadamente en la respuesta GET y se rechazan en la operación POST. La autenticación JWT opcional se puede habilitar en el arranque desde `config.json` o mediante las variables de entorno `FACEPHI_OCR_REST_AUTH_*`. Cuando el JWT está habilitado, `GET /api/v1/version` y `GET /api/v1/health` permanecen públicos, mientras que el resto de endpoints requieren un JWT válido a través de `Authorization: Bearer ` o la cabecera de clave de API configurada. ### `/api/v1/raw` Este endpoint se utiliza para leer información de la imagen de un documento mediante la tecnología OCR de Facephi. Significado de los parámetros: * `type`: Es necesario especificar el tipo de documento que se desea procesar, ya que nuestro servicio puede gestionar diferentes tipos de documentos. Valores disponibles en el JSON: **id\_card, passport, driver\_license, foreign\_card, invoice, pdf**. * `image`: Buffer de imagen en bruto codificado en base64 *RFC4648*. ## 3. Errores | Mensaje | Significado | Solución | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Licencia no válida. Código de estado: `STATUS_CODE` | Error en la licencia | Contacte con el equipo de soporte de Facephi | | No se pudo leer el documento, buffer vacío | El fichero pasado al servicio está vacío | Revise la entrada del servicio | | PDF no válido. Compruebe las codificaciones soportadas | El fichero PDF tiene una codificación no soportada | Revise la documentación para comprobar la codificación soportada | | Imagen no válida para el motor OCR | La imagen pasada al motor OCR es incorrecta | Revise la imagen pasada al servicio o contacte con el equipo de soporte de Facephi | | No se ha extraído texto del motor de PDF | La librería se ha habilitado para extraer el texto del PDF, pero no ha podido interpretarlo | Contacte con el equipo de soporte de Facephi | | No se ha encontrado texto con el motor OCR | El motor OCR no ha podido extraer texto de la imagen | Revise la imagen pasada al servicio, valide el formato de imagen soportado y la calidad, o contacte con el equipo de soporte de Facephi | | No se ha interpretado el texto con el intérprete OCR | La plantilla utilizada para esa imagen no es válida | Contacte con el equipo de soporte de Facephi | | Fichero de pipeline no encontrado | La configuración del servicio es incorrecta | Contacte con el equipo de soporte de Facephi | | Error en el pipeline de factura | La configuración del servicio es incorrecta | Contacte con el equipo de soporte de Facephi | | Error al convertir la configuración del pipeline a JSON desde la ruta: `RESOURCE_PATH` | La configuración del servicio es incorrecta | Contacte con el equipo de soporte de Facephi | | Error al cargar la configuración del pipeline desde la ruta: `RESOURCE_PATH` | La configuración del servicio es incorrecta | Contacte con el equipo de soporte de Facephi | | Modelo no encontrado. Compruebe la ruta del modelo | La configuración del servicio es incorrecta | Contacte con el equipo de soporte de Facephi |