Lo que ve un desarrollador que integra esta API
La documentación de marketing de una herramienta de reconocimiento de documentos siempre promete una extracción perfecta. Un desarrollador que realmente tiene que integrarla en un software de producción hace otras preguntas: cuál es la forma exacta de la respuesta, cómo se sabe si un campo es fiable, qué pasa cuando un documento es ilegible, y cuánto hay que esperar por una respuesta bajo carga real. Esta página responde a esas preguntas, no a las de un folleto comercial.
El problema que resuelve este motor
Un documento financiero real —factura, extracto bancario, ticket— no es un formulario estructurado. La maquetación varía de un emisor a otro, la calidad del escaneo varía de una subida a otra, y un mismo campo (el importe total, por ejemplo) puede aparecer en lugares completamente distintos según el documento. Un motor de reconocimiento debe generalizar más allá de un conjunto fijo de ejemplos, algo que una simple plantilla de posiciones no puede hacer en cuanto aparece un formato nuevo.
Cómo funciona el reconocimiento
El documento enviado se analiza primero para identificar su estructura general —cabecera, cuerpo, tabla de líneas si la hay— y después cada campo se localiza y extrae con su propio nivel de certeza. Este enfoque por campo, en lugar de una puntuación única para todo el documento, es lo que permite a tu integración tomar decisiones finas: aceptar automáticamente un importe extraído con una puntuación de 0,98 mientras se señala un número de factura extraído a 0,61 para confirmación humana.
La forma de la respuesta
Una llamada exitosa devuelve un objeto JSON con los campos de cabecera del documento (emisor, fecha, número de documento, importe total, moneda), un array line_items cuando el documento los contiene, y un objeto confidence que refleja cada campo individualmente. La documentación técnica completa de los endpoints está en la documentación de la API, en inglés; el equipo de soporte responde en español para cualquier duda de integración.
La puntuación de confianza, campo a campo
| Rango de puntuación | Comportamiento recomendado |
|---|---|
| 0,90 – 1,00 | Aceptar automáticamente sin intervención humana |
| 0,70 – 0,89 | Aceptar, pero mostrar el campo destacado para una revisión rápida |
| Por debajo de 0,70 | Enrutar hacia una verificación humana explícita antes de integrarlo |
Estos umbrales son orientativos, no impuestos — cada integración ajusta su propia tolerancia según lo crítico que sea el campo en cuestión: un importe total suele merecer un umbral más estricto que una descripción de línea secundaria.
Formatos de documentos soportados
| Formato de entrada | Observación |
|---|---|
| PDF nativo | Procesado directamente, incluidos los de varias páginas |
| PDF escaneado | Procesado como imagen, sin necesitar texto seleccionable |
| JPEG / PNG | Foto tomada con el móvil, incluso ligeramente inclinada |
| HEIC | Formato nativo de iPhone, convertido automáticamente en el servidor |
Latencia y procesamiento asíncrono
Un documento corto suele volver en pocos segundos en llamada síncrona. Para una importación por lotes —varios cientos de documentos históricos que procesar de golpe, por ejemplo durante una migración— un modo asíncrono evita mantener una conexión abierta: cada documento se procesa en cola y se envía una notificación por webhook a medida que cada resultado está disponible, en lugar de dejar al cliente esperando en una llamada bloqueante.
Antes y después de la integración
Antes
Un usuario sube un documento y después vuelve a teclear manualmente cada campo en tu software — un paso lento y propenso a errores de tecleo.
Después
El documento se sube, los campos aparecen precumplimentados con su puntuación de confianza, y el usuario solo corrige lo que realmente aparece señalado como incierto.
Casos de uso concretos
Precumplimentado de asientos contables
Factura de proveedor subida, campos extraídos, asiento propuesto antes de la validación del usuario.
Conciliación bancaria
Extracto bancario multipágina transformado en líneas de movimiento estructuradas para conciliación automática.
Nota de gastos móvil
Foto de un ticket tomada con el teléfono, línea de gasto estructurada disponible en segundos.
Importación masiva en una migración
Varios cientos de documentos históricos procesados por lotes con notificación por webhook en cada resultado.
Notificaciones y webhooks
Un documento enviado en modo asíncrono dispara una notificación hacia una URL de webhook que tú configuras, con el resultado completo de la extracción en el cuerpo de la petición. Esto evita que tu integración tenga que consultar la API en bucle para saber si un documento está listo — tu sistema recibe la notificación en cuanto el resultado existe.
Gestión de errores y documentos ilegibles
Un documento realmente ilegible —demasiado borroso, cortado, corrupto— devuelve un estado de fallo explícito en lugar de un dato inventado que pareciera plausible. Ningún documento fallido se factura. Del lado de la integración, este caso se gestiona normalmente ofreciendo al usuario repetir la foto o introducir el documento manualmente, en lugar de dejar entrar silenciosamente un dato incorrecto en el sistema.
Límites y volumetría
Un límite de tasa por defecto protege la infraestructura compartida entre todos los clientes; se ajusta al alza bajo solicitud para una integración en producción de alto volumen. No existe un límite duro sobre el volumen mensual total — la tarifa simplemente sigue el número de páginas procesadas con éxito, detallado en la página de precios.
Autenticación y seguridad
Cada llamada se autentica mediante una clave API propia de tu cuenta, revocable y regenerable independientemente desde el panel. Los documentos viajan cifrados en TLS y se procesan en servidores situados en la Unión Europea — el detalle completo está en la página de seguridad.
Comparado con un motor OCR genérico
Un motor de OCR genérico normalmente devuelve texto en bruto, línea a línea, sin entender que un grupo de cifras es un importe total y no un número de teléfono. Este motor va más allá: identifica la estructura del documento —qué campos pertenecen a la cabecera, cuáles forman una línea de detalle— y devuelve una respuesta ya estructurada, lista para mapear a tu modelo de datos, sin un paso de postprocesado adicional en tu lado.
Probar y validar antes de pasar a producción
El método más fiable para validar una integración antes de exponerla a usuarios reales consiste en volver a procesar un lote de documentos históricos ya conocidos —de los que ya sabes el valor esperado— y comparar campo a campo la respuesta de la API con esos valores de referencia. Esta comparación revela inmediatamente los desajustes de mapeo del lado de la integración, antes de que afecten a un usuario real.
Un entorno de pruebas que usa las mismas credenciales que una cuenta de producción, pero con un seguimiento de consumo separado, permite hacer esta validación sin mezclar las cifras de prueba con el volumen realmente facturado. La mayoría de equipos conservan este conjunto de prueba como suite de no regresión, ejecutada de nuevo con cada evolución significativa de su propio código de integración.
Idempotencia y deduplicación
Un documento enviado dos veces por error —un doble clic, una petición reintentada tras un timeout de red por tu parte— no debe producir dos resultados divergentes ni facturar dos veces el mismo documento. Un identificador de petición que generas en tu lado y transmites en cada llamada permite a la API reconocer un duplicado y devolver el resultado ya calculado en lugar de relanzar un procesamiento completo.
Esta protección importa especialmente para una integración que reintenta automáticamente una llamada ante un fallo de red temporal —un comportamiento recomendado por robustez, pero que sin idempotencia arriesgaría multiplicar el procesamiento de un mismo documento.
Campos personalizados y casos particulares
El esquema de respuesta estándar cubre los campos más comúnmente usados por un software de gestión — pero un sector concreto puede necesitar un campo adicional específico, por ejemplo un número de expediente interno presente en ciertos documentos de un cliente dado. Este tipo de necesidad se resuelve normalmente con un mapeo personalizado del lado de la integración, en lugar de una modificación del esquema estándar, lo que mantiene este último estable para el resto de clientes.
Un documento que no corresponde a ninguno de los tipos cubiertos de forma nativa —un caso raro pero real para un proveedor con un alcance muy amplio— devuelve los campos genéricos que ha podido identificar, con una puntuación de confianza que refleja esa incertidumbre estructural, en lugar de una simple negativa a procesar el documento.
Rendimiento a gran escala
Un pico de subidas —el fin de mes para un software de notas de gastos, el cierre de ejercicio fiscal para un software de contabilidad— a veces multiplica el volumen diario varias veces en un periodo corto. La infraestructura está dimensionada para absorber este tipo de variación sin degradación notable del tiempo de respuesta, a diferencia de una infraestructura interna dimensionada para un volumen medio y sometida a tensión durante esos picos.
| Situación | Modo recomendado |
|---|---|
| Subida individual de un usuario | Llamada síncrona |
| Importación de unas pocas decenas de documentos | Llamadas síncronas en serie |
| Importación de varios cientos a miles de documentos | Modo asíncrono con webhook |
| Pico estacional imprevisible | No requiere ninguna adaptación de tu lado |
Versionado y estabilidad en el tiempo
El esquema de respuesta está versionado explícitamente, lo que significa que una evolución del motor —la incorporación de un nuevo campo, una mejora de precisión sobre un tipo de documento— no altera nunca silenciosamente la estructura que tu integración ya espera. Un cambio estructural, más infrecuente, se anuncia con antelación en lugar de desplegarse sin previo aviso sobre una integración en producción.
Vigilar la calidad de extracción con el tiempo
Una integración que funciona bien el primer mes no garantiza que siga funcionando igual de bien el duodécimo — un nuevo formato de factura en un proveedor, un nuevo banco usado por un cliente, o simplemente una evolución de la mezcla de documentos procesados pueden hacer derivar silenciosamente la tasa de campos señalados con baja confianza. Seguir esa tasa en el tiempo, aunque sea de forma somera, permite detectar esa deriva antes de que se vuelva visible para los usuarios finales.
Un panel sencillo, actualizado cada semana —número de documentos procesados, tasa de campos aceptados automáticamente, tasa enrutada a verificación humana— basta para que la mayoría de integraciones detecten una anomalía antes de que un usuario la señale él mismo por soporte.
| Indicador seguido | Frecuencia recomendada |
|---|---|
| Volumen de documentos procesados | Diaria o semanal |
| Tasa de campos aceptados automáticamente | Semanal |
| Tasa enrutada a verificación humana | Semanal |
| Tasa de fallo total de extracción | Semanal, con alerta si es anormalmente alta |
Entornos de desarrollo, pruebas y producción
Una clave distinta por entorno —desarrollo, pruebas, producción— evita que una llamada de prueba afecte a las estadísticas de producción o aparezca en la facturación real. Cada clave puede revocarse y regenerarse de forma independiente desde el panel, lo que limita el impacto si alguna de ellas se filtra accidentalmente en un repositorio de código o un registro de aplicación compartido.
La mayoría de equipos mantienen un entorno de pruebas permanente, separado de producción, para probar cada evolución de su propio código de integración antes de desplegarla — exactamente la misma disciplina que para cualquier otro servicio externo del que dependa el software.
Casos límite encontrados en la práctica
Un documento compuesto con varias piezas distintas
Una factura y su albarán escaneados juntos en un único archivo vuelven con los campos de cada pieza identificados por separado cuando es detectable.
Una anotación manuscrita parcial sobre un documento impreso
Un importe corregido a mano sobre una factura impresa puede hacer bajar la confianza en ese campo concreto, señalando correctamente la incertidumbre en lugar de elegir un valor arbitrariamente.
Un documento girado 90 grados
La orientación se detecta y corrige automáticamente antes de la extracción en la gran mayoría de los casos.
Una marca de agua o un sello superpuesto al texto
El texto subyacente suele seguir siendo legible; una puntuación de confianza más baja señala los casos en los que la superposición es demasiado grande.
Ninguno de estos casos límite se resuelve rechazándolo sin más: cada uno vuelve con los campos que el motor ha podido identificar, acompañados de una puntuación de confianza que refleja honestamente el nivel real de incertidumbre, en lugar de forzar una respuesta binaria entre éxito perfecto y fallo total. Es este matiz, más que la gestión de un caso particular aislado, lo que distingue un motor pensado para producción de un prototipo probado únicamente con documentos limpios.
Bibliotecas cliente y ejemplos de código
Un desarrollador no necesita una biblioteca cliente dedicada para empezar: la API se llama con cualquier cliente HTTP capaz de subir un archivo multipart y leer una respuesta JSON, lo que en la práctica cubre cualquier lenguaje de backend usado hoy en un software de gestión — Node.js, Python, PHP, Java, .NET, Ruby. La documentación técnica incluye ejemplos de la llamada mínima en los lenguajes más usados por los equipos que integran hoy la API, lo suficiente para obtener una primera respuesta en minutos, no en días.
Para un equipo que prefiere evitar reescribir la lógica de reintento, backoff y verificación de firma de webhook desde cero, un pequeño envoltorio interno —unas pocas decenas de líneas alrededor del cliente HTTP ya usado en el resto del software— suele bastar y evita añadir una dependencia externa más al proyecto solo para esta integración. Los equipos que ya tienen una capa de integraciones genérica para otros servicios externos —pasarela de pago, proveedor de email— suelen encajar esta API en esa misma capa sin fricción adicional.
Migrar desde otro proveedor de OCR
Un software que ya usa otro proveedor de reconocimiento de documentos rara vez migra de un día para otro: el patrón más seguro consiste en ejecutar ambos motores en paralelo sobre el mismo flujo de documentos entrantes durante varias semanas, comparando campo a campo los resultados sin que el usuario final note ningún cambio de comportamiento. Esta comparación revela rápidamente si el nuevo motor generaliza mejor sobre los formatos que peor cubría el proveedor anterior — casi siempre el motivo real de la migración, más que un simple ahorro de coste por página.
El mapeo del esquema de salida de tu integración existente hacia el esquema de esta API suele ser el trabajo más largo de la migración, no la propia llamada a la API — un motivo más para probar con un lote representativo de documentos reales antes de comprometer una fecha de corte definitiva con el proveedor saliente. Una vez validado ese mapeo, apagar el proveedor anterior es normalmente una operación de un solo cambio de configuración, sin ningún despliegue adicional del lado del cliente final.