Qué cubre esta guía, y qué no cubre
Esta guía describe la integración técnica de una API de reconocimiento de documentos en un software de gestión existente — no el diseño de tu producto en su conjunto, ni la lógica contable que trata los datos una vez extraídos. Parte de la base de que ya tienes un software en producción, con usuarios que hoy suben documentos de alguna manera — manualmente, tecleando de nuevo, o mediante otra herramienta que buscas sustituir.
Ocho pasos forman el núcleo de la integración, seguidos de secciones prácticas sobre los roles internos, el cumplimiento normativo, un ejemplo cifrado completo, y los errores más frecuentes observados en este tipo de proyecto.
Qué necesitas antes de empezar
| Requisito | Por qué |
|---|---|
| Una muestra de documentos reales | Probar con ejemplos ficticios oculta los casos reales: foto borrosa, extracto multipágina, ticket arrugado |
| Un modelo de datos ya definido | Saber a qué campos mapear la respuesta evita idas y venidas de diseño en mitad de la integración |
| Un presupuesto aproximado de volumen mensual | Estimar el coste antes de comprometerte, no después de haber desplegado ya en producción |
| Acceso para crear una clave API | El primer paso técnico concreto de la guía |
Decidir construir o comprar, con honestidad
Antes de escribir la primera línea de integración, pon el cálculo completo sobre la mesa: cuánto costaría un equipo interno de reconocimiento de documentos —contratación, infraestructura de cálculo, mantenimiento continuo frente a formatos nuevos— comparado con una tarifa por página que sigue directamente tu volumen real. Este cálculo se desarrolla en detalle en la página API para proveedores de software de gestión.
Crear una clave y probar con documentos reales
Una cuenta gratuita basta para obtener una clave API y enviar un primer lote de tus propios documentos históricos —facturas, extractos, tickets ya en tus archivos. Compara los campos devueltos con lo que esperabas antes de escribir la primera línea de código de producción: es el momento más barato para descubrir una diferencia entre tus expectativas y la realidad de la extracción.
Mapear la respuesta a tu modelo de datos
Conecta cada campo devuelto (emisor, importe, fecha, líneas de detalle) con tu esquema de gestión ya existente, en lugar de adaptar tu modelo de datos a la estructura de la respuesta. La mayoría de campos corresponden directamente a un equivalente ya presente en un software de gestión — factura, asiento o nota de gastos.
Diseñar el flujo de subida pensando en documentos reales
Un usuario final fotografía un ticket con el móvil, a menudo con mala iluminación y ligeramente torcido — no es un escaneo ideal. Tu interfaz de subida debe anticipar esa realidad en lugar de asumir una calidad de documento constante.
Construir el circuito de verificación para casos inciertos
Enruta hacia una verificación humana solo lo que realmente esté por debajo del umbral de confianza que hayas definido — enrutar sistemáticamente todo hacia una revisión manual anula la ventaja de la automatización, mientras que aceptar todo sin distinción expone a errores silenciosos en tus datos financieros.
Añadir los extractos bancarios y la conciliación
Una vez estable el camino de las facturas o tickets, añade la extracción de extractos bancarios y la conciliación con los documentos ya en base de datos. Un extracto multipágina vuelve en forma de una única tabla de movimientos coherente, lista para compararse con las facturas y notas de gastos ya extraídas.
Gestionar documentos multidivisa y multiidioma
Para un proveedor con clientes fuera de España, la moneda y los importes se devuelven tal como aparecen impresos en el documento original — la conversión hacia una moneda de referencia queda de tu lado, según tu propia fuente de tipos de cambio, en lugar de venir impuesta por la propia extracción.
Supervisar la exactitud y el coste en producción
Tras el lanzamiento, muestrea regularmente un porcentaje de extracciones para un control humano, y sigue en el tiempo la tasa de campos señalados con baja confianza. Un aumento repentino de esa tasa suele indicar un formato de documento nuevo —un banco nunca visto, por ejemplo— más que un deterioro general de la extracción.
Quién debe llevar cada paso internamente
| Paso | Rol habitual |
|---|---|
| Decisión construir-o-comprar | Dirección técnica o de producto |
| Integración de la API y mapeo de campos | Desarrollador backend |
| Diseño del flujo de subida y verificación | Diseñador de producto o desarrollador frontend |
| Definición de los umbrales de confianza | Product owner, con retroalimentación de soporte |
| Supervisión continua en producción | Equipo técnico de guardia o soporte de nivel 2 |
Residencia de datos y requisitos regulatorios
Para un proveedor que vende a empresas españolas o europeas, la cuestión de la residencia de datos aparece sistemáticamente en una revisión de seguridad por parte del cliente. Los documentos se procesan en servidores situados en la Unión Europea y se eliminan inmediatamente tras la extracción — un punto que conviene documentar explícitamente en tu propia respuesta a un cuestionario de seguridad, en lugar de descubrirlo a mitad de una negociación con un gran cliente.
Una integración completa, de principio a fin
Un proveedor de software de contabilidad para pequeñas estructuras integra la extracción de facturas de proveedores. El prototipo (pasos 1 a 3) lleva tres días; el circuito de verificación y el flujo de subida (pasos 4 y 5) llevan una semana más; la conciliación bancaria (paso 6) se entrega dos semanas después, una vez estable el primer módulo en producción con un grupo piloto de clientes.
| Fase | Duración |
|---|---|
| Prototipo (pasos 1 a 3) | 3 días |
| Flujo de subida y verificación (pasos 4 y 5) | 1 semana |
| Conciliación bancaria (paso 6) | 2 semanas |
| Estabilización y supervisión (pasos 7 y 8) | Continuo |
Preguntas que hacer a cualquier proveedor, no solo a FlowParse
¿Dónde se alojan y procesan los documentos?
Una respuesta vaga o fuera de la Unión Europea merece investigarse si tus propios clientes están sujetos al RGPD.
¿Cómo evoluciona la tarifa con el volumen?
Una tarifa decreciente clara vale más que una negociación caso por caso en cada escalón alcanzado.
¿Qué ocurre con un documento que falla?
Un proveedor serio no factura un documento que no se ha extraído.
¿Está versionado el esquema de respuesta?
Una evolución del motor nunca debería romper silenciosamente una integración ya en producción.
Versionado de la API, disponibilidad y comportamiento ante fallos
Una integración en producción debe sobrevivir a una indisponibilidad breve sin perder ningún documento: ponerlo en cola en lugar de bloquear al usuario, reintentar automáticamente con una lógica de espera exponencial, y registrar cada fallo para investigación en lugar de dejarlo pasar silenciosamente.
Errores frecuentes en esta integración
Ignorar la puntuación de confianza y aceptarlo todo automáticamente
Un error de campo no detectado acaba en un asiento contable real, descubierto mucho después.
Probar solo con documentos limpios y bien escaneados
Un conjunto de prueba que no se parece a los documentos reales de los usuarios oculta los problemas reales hasta producción.
Bloquear al usuario en una llamada síncrona para un lote voluminoso
Una importación de varios cientos de documentos merece un procesamiento asíncrono con notificación, no una página que da vueltas.
No revisar nunca los umbrales de confianza tras el lanzamiento
Un umbral fijado en el lanzamiento y nunca reajustado acaba sobrecargando la verificación humana o dejando pasar casos realmente ambiguos.
Buenas prácticas para una integración duradera
Hacer funcionar un proveedor nuevo en paralelo al existente sobre una muestra real antes de cambiar por completo, documentar explícitamente los umbrales de confianza elegidos y por qué, y revisar esos umbrales cada pocos meses a medida que el volumen y la diversidad de documentos evolucionan — tres hábitos sencillos que evitan la mayoría de sorpresas desagradables observadas en este tipo de proyecto.
Cuánto tiempo lleva cada paso
| Paso | Tiempo estimado |
|---|---|
| 1. Decisión construir-o-comprar | Unas horas |
| 2. Prueba con documentos reales | 1 día |
| 3. Mapeo del modelo de datos | 1 a 2 días |
| 4. Flujo de subida | 2 a 4 días |
| 5. Circuito de verificación | 2 a 4 días |
| 6. Extractos bancarios y conciliación | 1 a 2 semanas |
| 7. Multidivisa y multiidioma | 2 a 4 días |
| 8. Supervisión en producción | Continuo |
Una checklist imprimible
Clave API creada y probada con un lote de documentos reales
Campos de respuesta mapeados al modelo de datos existente
Flujo de subida diseñado para fotos imperfectas, no escaneos ideales
Umbral de confianza definido y circuito de verificación humana construido
Extractos bancarios y conciliación añadidos una vez estable el primer módulo
Comportamiento multidivisa y multiidioma verificado con documentos reales
Comportamiento ante fallo probado (cola, sin bloqueo)
Panel de supervisión de exactitud y coste en marcha antes del lanzamiento
Hacerlo solo o en equipo
Un desarrollador solo puede completar los ocho pasos en secuencia en tres a cuatro semanas. Un equipo de tres a cinco personas puede paralelizar el flujo de subida, el mapeo de datos y el diseño del circuito de verificación, reduciendo el plazo total a una a dos semanas — la secuencia lógica de los pasos sigue siendo la misma en ambos casos, solo cambia el paralelismo.
Para quién es esta guía
Esta guía se dirige a equipos técnicos de proveedores de software de gestión que integran un reconocimiento de documentos por primera vez, o que sustituyen un proveedor existente. El detalle técnico del formato de respuesta y la puntuación de confianza se desarrolla en la página reconocimiento de documentos para desarrolladores.
Pasar de un piloto a producción completa
Una integración validada con un grupo piloto de unos pocos clientes pasa al conjunto de la base sin cambio estructural — la tarifa por página sigue directamente al volumen, sin un escalón contractual que renegociar en cada duplicación del uso. Es una diferencia concreta frente a un equipo interno, cuyo coste fijo se mantiene idéntico aunque el volumen procesado se duplique o se reduzca a la mitad.
Un breve glosario
| Término | Definición |
|---|---|
| Puntuación de confianza | Probabilidad, entre 0 y 1, de que el campo extraído sea exacto |
| Webhook | Notificación enviada automáticamente a tu sistema cuando un resultado está listo |
| Procesamiento asíncrono | El documento se pone en cola en lugar de procesarse durante una llamada bloqueante |
| Línea de detalle | Una línea individual de una tabla de factura o extracto (referencia, cantidad, precio) |
Un hábito que mantener tras el lanzamiento
Revisa cada trimestre la tasa de campos señalados con baja confianza, incluso cuando todo parece funcionar correctamente — suele ser la única forma de detectar una deriva lenta antes de que se convierta en un problema visible para tus usuarios.
Costes ocultos que anticipar antes de comprometerse
La tarifa por página es la parte visible del coste, pero otras dos partidas merecen anticiparse desde el principio en lugar de descubrirse a mitad del proyecto. La primera es el tiempo de diseño del circuito de verificación humana —a menudo subestimado, porque afecta a la interfaz, a la lógica de negocio y a veces a un cambio en la forma de trabajar de los usuarios que hoy validan los documentos de otra manera. La segunda es el tiempo de prueba sobre un volumen representativo de documentos reales, que siempre lleva más tiempo del previsto la primera vez que un equipo lo hace en serio.
Ninguna de estas dos partidas es propia de esta integración en particular — acompañan a cualquier proyecto que automatice una tarea antes manual. Nombrarlas explícitamente en la planificación, en lugar de dejarlas como un imprevisto, evita la decepción de un presupuesto sobrepasado en un proyecto cuyo coste directo por página estaba, sin embargo, correctamente estimado.
| Partida a menudo subestimada | Cómo anticiparla |
|---|---|
| Diseño del circuito de verificación | Prever un presupuesto de diseño dedicado, no solo de desarrollo |
| Prueba sobre volumen representativo | Reservar un tiempo explícito por adelantado, no al final del sprint |
| Formación de usuarios internos | Documentar el nuevo flujo antes del lanzamiento, no tras los primeros tickets |
| Ajuste de umbrales de confianza | Revisar los umbrales tras las primeras semanas reales, no solo en el lanzamiento |
Gestión de claves API y entornos
Una clave de prueba y una de producción separadas evitan que una llamada de desarrollo afecte accidentalmente a las estadísticas o a la facturación de producción. La mayoría de equipos crean una clave dedicada por entorno (desarrollo, pruebas, producción), revocable de forma independiente — útil si una clave se filtra accidentalmente en un repositorio de código o un registro de aplicación, un incidente que ocurre más a menudo de lo que se piensa.
Documentar con claridad, dentro de tu propio proyecto, qué clave sirve para qué entorno evita el error clásico de un desarrollador que prueba por descuido contra la clave de producción — un incidente menor en sí mismo, pero que puede distorsionar unas estadísticas de supervisión construidas con cuidado.
Casos de uso avanzados una vez estable la integración
Una vez estable el circuito principal en producción durante varias semanas, algunos equipos añaden refinamientos que no eran prioritarios en el lanzamiento: una detección de documentos duplicados para evitar una doble contabilización, un enriquecimiento automático del tercero a partir de un catálogo interno una vez extraído el nombre, o un panel que muestra directamente a los usuarios la tasa de documentos procesados sin intervención humana.
Estos refinamientos tienen en común no ser nunca necesarios para un lanzamiento inicial exitoso — añadirlos demasiado pronto retrasa la puesta en producción sin un beneficio proporcional, mientras que se vuelven naturales una vez probado el núcleo básico con usuarios reales.
Documentación y recursos complementarios
La documentación técnica completa de los endpoints y esquemas de respuesta está disponible en inglés; el equipo de soporte responde en español para cualquier duda de integración concreta que no esté cubierta explícitamente en esta guía. El detalle del formato de respuesta y la puntuación de confianza, desde un punto de vista puramente técnico, se desarrolla en la página reconocimiento de documentos para desarrolladores.
Checklist de seguridad antes del lanzamiento
Antes de activar la integración para el conjunto de tus clientes, una verificación breve pero sistemática evita los incidentes más frecuentes observados en este tipo de proyecto: clave API almacenada en una variable de entorno en lugar de en el código fuente, registros de aplicación comprobados para no contener nunca el contenido en bruto de un documento sensible, y acceso a la clave de producción restringido a los servicios que realmente lo necesitan.
Clave API almacenada en variable de entorno, nunca subida al código fuente.
Registros de aplicación comprobados para no registrar nunca el contenido de un documento.
Acceso a la clave de producción restringido a los servicios que realmente lo necesitan.
Comportamiento de reserva probado explícitamente ante una indisponibilidad de la API.
Formar al equipo de soporte en el nuevo flujo
Un equipo de soporte que descubre el nuevo flujo de subida al mismo tiempo que los primeros clientes responde más lento y con menos precisión que un equipo informado de antemano sobre lo que cambia, lo que sigue igual, y las preguntas más probables que anticipar — por qué se señaló un campo concreto para verificación, qué significa un documento fallido, cómo relanzar una extracción manualmente si hace falta.
Un documento interno breve, dos o tres páginas, que explique estos casos más frecuentes suele bastar, complementado con una sesión de preguntas y respuestas antes del lanzamiento en lugar de después de los primeros tickets.
Ese mismo documento sirve a menudo de base para una respuesta tipo que el soporte puede adaptar rápidamente a un cliente que hace una pregunta recurrente, en lugar de redactar una explicación completa en cada nuevo aviso similar — un ahorro de tiempo modesto individualmente, pero real a la escala del volumen de tickets que un equipo de soporte gestiona cada semana.
Los tres primeros meses tras el lanzamiento
| Periodo | Qué vigilar |
|---|---|
| Semanas 1-2 | Volumen de tickets de soporte relacionados con el nuevo flujo, comparado con el periodo anterior |
| Semanas 3-6 | Tasa de campos señalados con baja confianza, ajustada si está demasiado alta o baja |
| Meses 2-3 | Primeras impresiones cualitativas de los usuarios, más allá de los tickets de soporte |
Estos tres meses suelen bastar para distinguir un ajuste menor de umbral de un problema estructural que merecería revisar parte de la integración — la mayoría de equipos no necesitan ningún cambio importante pasado ese plazo.
Superado ese hito de los tres meses, la frecuencia de seguimiento puede bajar a una revisión mensual en lugar de semanal — la integración está entonces suficientemente probada sobre un volumen real como para que las sorpresas sean poco frecuentes, sin por ello abandonar por completo la supervisión descrita en el paso 8.
Mantén de todas formas un registro escrito de cada ajuste de umbral realizado durante estos tres primeros meses — el motivo que llevó a cada cambio se olvida rápido, mientras que un historial breve permite a quien retome el proyecto más adelante entender de inmediato por qué los umbrales actuales son los que son, en lugar de redescubrirlo a tanteos.
Un simple documento compartido, actualizado con cada cambio con la fecha, el umbral anterior, el nuevo umbral y el motivo, basta ampliamente — el objetivo no es un proceso pesado, solo no perder una decisión que parecía evidente en el momento pero que ya no lo será en absoluto seis meses después para otra persona del equipo.
Presentar el proyecto internamente y conseguir presupuesto
Un desarrollador convencido de la integración rara vez basta por sí solo para que el proyecto avance — normalmente hace falta convencer a una dirección técnica o de producto de que dedique un tiempo de equipo que hoy se reparte entre otras prioridades. El argumento que mejor funciona no es técnico sino económico: una comparación cifrada entre el coste actual —horas de introducción manual, errores de tecleo que generan trabajo de corrección aguas abajo— y el coste de la integración más la tarifa por página, sobre el volumen real de documentos que procesa hoy el software.
El paso 2 de esta guía —probar con un lote de documentos históricos reales, gratis, antes de cualquier compromiso— es también el mejor argumento para conseguir ese presupuesto: una demostración con datos propios convence más que cualquier cifra genérica de una página comercial. Muchos equipos presentan directamente el resultado de esa prueba, con los campos extraídos junto a los documentos originales, en la misma reunión donde piden el tiempo de equipo necesario para la integración completa.
| Argumento | Cómo presentarlo |
|---|---|
| Coste actual de la introducción manual | Horas mensuales estimadas × coste horario cargado del equipo |
| Coste de la nueva integración | Tiempo de desarrollo estimado + tarifa por página sobre el volumen actual |
| Prueba con documentos reales | Resultado concreto del paso 2, no una promesa genérica de exactitud |
| Riesgo de no actuar | Coste de introducción manual que crece linealmente con el volumen de clientes |
Comunicar el cambio a los clientes existentes
Para un proveedor de software ya en producción con una base de clientes activa, la propia integración es solo la mitad del trabajo — la otra mitad consiste en explicar el cambio sin generar inquietud innecesaria. Un cliente que sube documentos hoy de una manera y los verá procesados de otra mañana agradece una comunicación breve y concreta: qué cambia exactamente en su flujo de trabajo diario, qué sigue exactamente igual, y a quién dirigirse si algo no funciona como se esperaba durante las primeras semanas.
Un lanzamiento progresivo, primero con un grupo piloto voluntario de clientes antes de activarlo para el conjunto de la base, reduce el riesgo de un incidente visible a gran escala y da tiempo a ajustar la comunicación según las primeras preguntas reales recibidas, en lugar de anticiparlas todas de antemano sin retroalimentación real. La mayoría de proveedores que siguen este patrón informan de una fase piloto de dos a tres semanas antes de la activación general, tiempo suficiente para detectar y corregir cualquier fricción inesperada en el nuevo flujo.