InvoiCy OCR Internacional¶

InvoiCy OCR Internacional es una solución de inteligencia artificial desarrollada para empresas que necesitan procesar, traducir y extraer datos estructurados de facturas y documentos fiscales emitidos en cualquier país o idioma.

Al recibir un archivo (PDF o imagen) que contiene una factura internacional, el producto aplica tecnología OCR combinada con modelos avanzados de lenguaje para interpretar el contenido del documento y devolver un JSON estructurado con todos los datos principales de la factura, independientemente del idioma original, del formato visual o del país de origen.

El resultado es la eliminación del trabajo manual asociado a la validación y carga de datos de importación, acelerando el proceso de registro y conciliación de documentos internacionales en los sistemas de gestión del cliente.

Casos de Uso¶

InvoiCy OCR Internacional está especialmente indicado para empresas que:

Importan productos o servicios y reciben facturas en idiomas extranjeros (japonés, árabe, alemán, mandarín, entre otros) que necesitan ser registradas en sistemas locales.
Operan en múltiples países y requieren estandarizar el formato de facturas provenientes de distintos orígenes en un único esquema de datos.
Automatizan procesos de cuentas por pagar y necesitan eliminar la carga manual de datos de las facturas recibidas.
Realizan auditorías fiscales y requieren trazabilidad y extracción confiable de información de documentos internacionales.

Ejemplo práctico: Una empresa en Uruguay recibe regularmente facturas de proveedores japoneses, redactadas en idioma japonés. Con InvoiCy OCR Internacional, puede enviar el archivo de la factura a través de la API y recibir como respuesta un JSON estructurado con todos los datos relevantes —número de factura, importe, ítems, fechas, datos del emisor y del destinatario— traducidos y organizados, listos para ser importados en su sistema de gestión.

Cómo Funciona¶

El flujo de procesamiento de InvoiCy OCR Internacional sigue cuatro etapas principales:

1. Registro de la empresa Antes de enviar documentos para su procesamiento, es necesario registrar la empresa importadora en la plataforma InvoiCy OCR. Este registro devuelve un identificador único (EmpAK), que será utilizado en todas las solicitudes posteriores.

2. Envío del documento Una vez registrada la empresa, el cliente envía el archivo de la factura (en formato Base64) al endpoint de importación de documentos. Es posible seleccionar el procesador de inteligencia artificial más adecuado según el tipo de documento.

3. Procesamiento asíncrono La API procesa el documento en segundo plano, aplicando tecnología OCR y modelos de lenguaje para interpretar, traducir y estructurar la información contenida en la factura. La respuesta inmediata al envío es un número de protocolo para el seguimiento del procesamiento.

4. Consulta del resultado Utilizando el protocolo recibido, el cliente puede consultar la API para obtener el JSON estructurado con todos los datos extraídos del documento.

Requisitos Previos¶

Importante: Requisito Comercial
InvoiCy OCR Internacional es un producto de acceso controlado. Para utilizar la solución, es obligatorio que el modelo comercial y la negociación hayan sido previamente formalizados con el equipo de Migrate. Una vez contratada la solución, el equipo comercial proporcionará las credenciales y las claves de autenticación necesarias para acceder a la API. Para iniciar una negociación, póngase en contacto con el equipo comercial de Migrate.

Requisitos técnicos

Credenciales de acceso proporcionadas después de la formalización de la negociación comercial.
Capacidad para realizar llamadas HTTP REST desde su aplicación.
Capacidad para convertir archivos (PDF o imágenes) al formato Base64.
La integración técnica es responsabilidad del cliente, quien se conectará directamente con la API del producto.

Ambientes Disponibles¶

El producto dispone de dos entornos de integración diferenciados. Se recomienda utilizar ampliamente el entorno de homologación para realizar pruebas y validaciones antes de habilitar las operaciones en producción.

Homologación¶

Entorno destinado a pruebas y validaciones técnicas. Las solicitudes realizadas en este endpoint no afectan datos reales ni oficiales.

URL Base: https://apibrhomolog.invoicy.com.br/ocrdocuments/api/v1/

Producción¶

Entorno oficial para operaciones reales. Este endpoint debe utilizarse únicamente después de la finalización y validación de todas las pruebas en el entorno anterior.

URL Base: https://apibr.invoicy.com.br/ocrdocuments/api/v1/

La URL base (BASE_URL) debe ser sustituida por la URL correspondiente al entorno deseado. Por ejemplo:

1	`https://apibr.invoicy.com.br/ocrdocuments/api/v1/Company`

Autenticación¶

Todas las solicitudes a la API de InvoiCy OCR Internacional utilizan un mecanismo de autenticación basado en hash MD5, enviado a través del header.

Generación del hash en el registro de empresa¶

Para el registro de empresa, el hash MD5 se genera a partir de la concatenación de la clave del socio con el JSON del cuerpo de la solicitud:

1	`MD5(clave_del_socio + json_del_cuerpo)`

Generación del hash en las demás solicitudes¶

Para las solicitudes de importación y consulta de documentos, el hash MD5 se genera a partir de la concatenación del EmpAK (retornado en el registro de empresa) con un timestamp Unix en UTC:

1	`MD5(empAK + timestamp_unix_utc)`

Ejemplo de cadena antes de la generación: x99Xxxxxx+XX9/xxXXxX9xXXXXXx+9xx1740080360

Importante: El hash MD5 tiene una validez de 5 minutos a partir de su generación. Las solicitudes enviadas con un hash expirado serán rechazadas con el código de error 403 Forbidden.

Headers obligatorios¶

Todas las solicitudes deben incluir los siguientes encabezados:

1 2	`X-Client-MD5-Hash: [MD5 generado] Content-Type: application/json; api-version=1.0`

Guía de Integración¶

Esta sección describe el paso a paso para integrar con InvoiCy OCR Internacional.

Paso 1 — Consulta de Países (opcional)¶

Antes de registrar una empresa, puede ser necesario obtener el countryId correspondiente al país de operación. Utilice el endpoint de consulta de países pasando el nombre del país.

Ejemplo: GET BASE_URL/Country?Nome=Uruguai

El campo id devuelto en la respuesta debe utilizarse en el campo countryId del registro de la empresa.

Paso 2 — Registro de la Empresa¶

Realice el registro de la empresa en la plataforma InvoiCy OCR. Este paso se realiza una única vez por empresa.

Genere el hash MD5 según lo descrito en la sección de autenticación.
Envíe la solicitud POST a BASE_URL/Company con el JSON de registro.
Almacene de forma segura el EmpAK devuelto. Este será utilizado en todas las solicitudes futuras.

Ejemplo de estructura JSON para el registro de la empresa:

{
  "name": "Nombre de la Empresa S.A.",
  "cnpj": "00.000.000/0001-00",
  "partnerId": "{{partnerId}}",
  "email": "contacto@empresa.com.br",
  "phone": "(11) 3333-4444",
  "address": {
    "street": "Calle Ejemplo",
    "number": "100",
    "city": "São Paulo",
    "state": "SP",
    "zipCode": "01310-100",
    "countryId": "{{countryId}}"
  }
}

Paso 3 — Importación del Documento¶

Con la empresa registrada, envíe el archivo de la factura para su procesamiento.

Convierta el archivo (PDF o imagen) a Base64.
Genere el hash MD5 utilizando el EmpAK y el timestamp Unix actual.
Envíe la solicitud POST a BASE_URL/DocumentHandler/AddDocument.
Almacene el protocolo devuelto en la respuesta.

Importante: La fecha y hora devueltas en la respuesta se proporcionan en formato UTC.

Ejemplo de estructura JSON para el envío del documento:

{
  "companyId": 1,
  "fileBase64": "Base64_Document",
  "mimeType": "application/pdf",
  "processor": 8,
  "targetLanguage": "pt-BR"
}

Paso 4 — Consulta del Resultado¶

Utilice el protocolo obtenido en el paso anterior para consultar el resultado del procesamiento.

Envíe la solicitud GET a BASE_URL/DocumentHandler/SearchDocument?companyId={id}&protocol={protocolo}.
La respuesta será un JSON estructurado con todos los datos extraídos de la factura.

Referencia de Endpoints¶

Para ejemplos interactivos, payloads completos y pruebas, acceda a la documentación completa en Postman.

Consulta de Países ¶

Devuelve el identificador (id) de un país por su nombre. El valor devuelto se utiliza en el campo countryId durante el registro de la empresa. El nombre del país debe informarse como parámetro al final de la URL.

1	`GET BASE_URL/Country?Nome={nome_do_pais}`

Registro de Empresa ¶

Registra una empresa en la plataforma InvoiCy OCR, habilitándola para procesar documentos. La respuesta contiene el EmpAK, que debe ser almacenado de forma segura por el cliente y utilizado en todas las solicitudes posteriores.

1	`POST BASE_URL/Company`

Importación de Documento ¶

Recibe el archivo de la factura en formato Base64 e inicia el procesamiento mediante OCR e IA. La respuesta contiene un protocolo para el seguimiento del procesamiento asíncrono.

1	`POST BASE_URL/DocumentHandler/AddDocument`

Campos del cuerpo de la solicitud:

Campo	Tipo	Descripción
`companyid`	string	ID de la empresa devuelto en el registro.
`fileBase64`	string	Contenido del archivo en Base64 (PDF o imagen).
`mimeType`	string	Tipo MIME del archivo enviado. Ver formatos soportados.
`processor`	integer	Identificador del procesador de IA. Ver procesadores disponibles.

Consulta de Documento ¶

Consulta el resultado del procesamiento de un documento previamente importado. Devuelve el JSON estructurado con todos los datos extraídos de la factura.

1	`GET BASE_URL/DocumentHandler/SearchDocument?companyId={id}&protocol={protocolo}`

Parámetros de consulta:

Parámetro	Descripción
`companyId`	ID de la empresa devuelto en el registro.
`protocol`	Protocolo devuelto en el momento de la importación del documento.

Estructura de Retorno: Detalle de los Campos¶

El JSON de respuesta de la consulta de documento contiene los siguientes campos:

Datos del Emisor¶

ID	Campo	Descripción	Tipo	Tam. Máx.
A01	`documentType`	Tipo de documento.	int	—
A02	`issuerDocument`	Número del documento fiscal del emisor.	string	50
A03	`nameFantasy`	Nombre comercial de la empresa emisora.	string	100
A04	`corporateName`	Razón social de la empresa emisora.	string	150
A05	`address`	Dirección de la empresa emisora.	string	200
A06	`postalCode`	Código postal de la dirección del emisor.	string	20
A07	`city`	Ciudad de la empresa emisora.	string	100
A08	`state`	Estado/Provincia de la empresa emisora.	string	50
A09	`country`	País de la empresa emisora.	string	50
A36	`taxID`	Identificación fiscal del emisor (ej: RUT, CNPJ, CPF).	string	50

Datos de la Factura¶

ID	Campo	Descripción	Tipo	Tam. Máx.
A10	`invoiceNumber`	Número de la factura.	string	50
A11	`invoiceSeries`	Serie de la factura.	string	20
A12	`purchaseOrder`	Número de la orden de compra (OC).	string	—
A13	`documentLetter`	Letra del documento.	string	—
A14	`issueDate`	Fecha de emisión de la factura.	DateTime	—
A15	`dueDate`	Fecha de vencimiento de la factura.	DateTime	—
A16	`caeDueDate`	Fecha de vencimiento del CAE.	DateTime	—
A17	`inclusionDate`	Fecha y hora de inclusión del documento en el sistema.	DateTime	—
A23	`caeNumber`	Número del CAE.	string	—
A34	`referenceNumber`	Número de referencia adicional.	string	50

Valores y Condiciones Comerciales¶

ID	Campo	Descripción	Tipo	Tam. Máx.
A18	`netAmount`	Subtotal (valor neto).	decimal	—
A19	`totalAmount`	Valor total de la factura.	decimal	—
A20	`ivaPercentage`	Porcentaje de IVA/impuesto.	decimal	—
A21	`exchangeRate`	Tipo de cambio.	decimal	—
A24	`currency`	Moneda de la factura.	string	10
A25	`paymentMethod`	Método de pago.	string	50
A26	`taxCondition`	Condición frente al IVA.	string	—
A35	`paymentDetails`	Detalles sobre el pago de la factura.	string	200
A58	`incoterm`	Incoterm aplicable a la transacción.	string	20
A22	`observation`	Observaciones adicionales sobre la factura.	string	500

Datos del Destinatario¶

ID	Campo	Descripción	Tipo	Tam. Máx.
A27	`clientName`	Nombre del cliente destinatario.	string	100
A28	`clientAddress`	Dirección del cliente destinatario.	string	200
A29	`clientPostalCode`	Código postal del cliente.	string	20
A30	`clientCity`	Ciudad del cliente.	string	100
A31	`clientState`	Estado/Provincia del cliente.	string	50
A32	`clientCountry`	País del cliente.	string	50
A33	`clientDocumentNumber`	Número del documento del cliente (ej: RUT, CPF, CNPJ).	string	50

Ítems de la Factura (lista — campo `items`)¶

ID	Campo	Descripción	Tipo	Tam. Máx.
A38	`itemCode`	Código del artículo en la factura.	string	50
A39	`quantity`	Cantidad del artículo.	decimal	-
A40	`dispatchDate`	Fecha de despacho del artículo.	DateTime	-
A41	`unitOfMeasure`	Unidad de medida (ej: KG).	string	20
A42	`iclPricePerLiter`	ICL por litro.	decimal	-
A43	`unitPrice`	Precio unitario del artículo.	decimal	-
A44	`itemDiscount`	Descuento aplicado al artículo.	decimal	-
A45	`itemDiscountPercentage`	Porcentaje de descuento aplicado.	decimal	-
A46	`totalPrice`	Precio total del artículo después de descuentos.	decimal	-
A47	`itemName`	Nombre/descripción del artículo.	string	100
A48	`eanOrDun`	Código EAN o código de barras.	string	50
A49	`referenceNumberItem`	Número de referencia del artículo.	string	50
A50	`origin`	Origen del artículo.	string	50
A51	`ncmOrHts`	Código NCM (mercadería) o HTS (tarifa aduanera).	string	50
A52	`stockID`	Identificación del stock del artículo.	string	50
A53	`packingUnit`	Unidad de embalaje.	string	20
A54	`packingQuantity`	Cantidad de artículos por embalaje.	decimal	-

Cargos Adicionales (lista — campo `additionalCharges`)¶

ID	Campo	Descripción	Tipo	Tam. Máx.
A56	`additionalChargeDescription`	Descripción del cargo adicional.	string	200
A57	`additionalChargeValue`	Valor del cargo adicional.	decimal	-

Formatos de Archivo Soportados¶

El campo mimeType de la solicitud de importación acepta los siguientes valores:

Valor	Formato
`application/pdf`	Documento PDF
`image/png`	Imagen PNG
`image/jpeg`	Imagen JPEG
`image/jpg`	Imagen JPG
`image/bmp`	Imagen BMP
`image/pjpeg`	Imagen PJPEG
`image/x-png`	Imagen X-PNG

Procesadores Disponibles¶

El campo processor define qué motor de inteligencia artificial será utilizado para el procesamiento del documento. La elección del procesador puede afectar la precisión y el tiempo de procesamiento.

Valor	Procesador
`1`	DocumentAI
`3`	Gemini 2.5 Pro
`5`	DocumentAI + Gemini 2.5 Pro
`6`	Gemini 3.0 Flash
`7`	Gemini 3.0 Flash Lite
`8`	Gemini 3.0 Pro
`9`	DocumentAI + Gemini 3.0 Flash
`10`	DocumentAI + Gemini 3.0 Flash Lite
`11`	DocumentAI + Gemini 3.0 Pro
`12`	Gemini 3.5 Flash
`13`	Gemini 3.1 Flash Lite
`14`	DocumentAI + Gemini 3.5 Flash
`15`	DocumentAI + Gemini 3.1 Flash Lite

Buenas Prácticas y Limitaciones¶

Un documento por archivo: No se recomienda importar más de una factura en un mismo archivo PDF. Los documentos con múltiples facturas pueden reducir la precisión del procesamiento.
Calidad del archivo: Los documentos con buena resolución y contraste suelen generar resultados más precisos en la extracción de datos.
Validez del hash: El hash MD5 de autenticación expira en 5 minutos. Asegúrese de generar un nuevo hash en cada solicitud.
Procesamiento asíncrono: El procesamiento de los documentos no es instantáneo. Implemente una lógica de polling (consultas periódicas) para verificar el resultado de la extracción.
Almacenamiento del EmpAK: El EmpAK devuelto en el registro de la empresa debe almacenarse de forma persistente y segura, ya que es necesario para todas las operaciones posteriores.