API vs integración por archivos

Dos mecanismos, una misma responsabilidad

Una integración mueve información entre sistemas bajo un contrato. Mediante API, un consumidor envía una solicitud a un endpoint y recibe una respuesta o confirmación. Mediante archivos, un productor genera un conjunto —por ejemplo CSV— y lo entrega en una ubicación o canal acordado para que otro proceso lo consuma.

La diferencia visible es técnica; la obligación de fondo es la misma: definir campos, significado, identificadores, formato, seguridad, frecuencia, errores, reintentos, duplicados y responsables. Sin este contrato, una API sólo produce fallas más rápidas y un archivo sólo produce ambigüedad en lote.

La especificación OpenAPI ayuda a describir operaciones HTTP, parámetros y esquemas. RFC 4180 documenta un formato común para CSV, aunque en la práctica siguen existiendo variaciones de delimitador, codificación y encabezados. Elegir un estándar reduce interpretaciones, pero no sustituye acuerdos empresariales.

Criterios para comparar

• Oportunidad. Una API puede responder en segundos; un archivo suele corresponder a ventanas programadas. Si el negocio decide una vez al día, tiempo real puede no aportar valor.
• Volumen. Un archivo puede transferir millones de filas con eficiencia. Una API paginada puede distribuir la carga y consultar sólo lo necesario.
• Acoplamiento. Una llamada síncrona depende de disponibilidad y tiempos del otro sistema. Un lote desacopla el momento de producción y consumo, aunque exige almacenamiento y conciliación.
• Recuperación. Un archivo conservado puede reprocesarse. Una API necesita idempotencia, reintentos y mecanismos para reconstruir cambios omitidos.
• Operación. API requiere monitoreo de disponibilidad, latencia, límites y versiones; archivos requieren vigilar entrega, nombre, integridad, duplicados y procesamiento.

El criterio principal es el proceso. No se justifica mantener infraestructura de baja latencia para una conciliación mensual; tampoco conviene esperar un archivo nocturno para confirmar una operación crítica ante un cliente.

Errores, reintentos e idempotencia

HTTP distingue clases de respuesta y semántica de métodos, pero el código de estado no explica por sí solo qué ocurrió en el negocio. Una respuesta exitosa puede indicar recepción, no procesamiento final. El contrato debe separar validación, aceptación y resultado, con identificadores que permitan seguimiento.

Los reintentos pueden duplicar una operación si el consumidor no sabe si la primera solicitud se aplicó. Una clave idempotente o un identificador empresarial estable permite reconocer el mismo intento. Para archivos, nombre y fecha no bastan: conviene usar identificador de lote, hash, cantidad de registros y registro de recepción.

Seguridad y trazabilidad

Una API autentica al consumidor y autoriza cada operación. Debe limitar alcance, proteger credenciales, cifrar transporte, validar entradas y registrar eventos útiles. El principio de mínimo privilegio evita que una integración de consulta pueda modificar información.

Un archivo también necesita controles. Se define quién puede producirlo y leerlo, cómo se cifra en tránsito y reposo, cuánto tiempo se conserva y cómo se verifica integridad. El correo manual suele ser un canal débil para datos recurrentes porque dificulta automatizar permisos, retención y evidencia de procesamiento.

Los logs no deben copiar indiscriminadamente credenciales o datos sensibles. Deben permitir responder quién intercambió qué conjunto, cuándo, con qué contrato y cuál fue el resultado. La trazabilidad pertenece al diseño, no a una búsqueda posterior en carpetas.

Cuándo elegir cada opción

Una API es adecuada para consultas puntuales, validaciones interactivas, operaciones de baja latencia y capacidades reutilizadas por varios consumidores. Funciona mejor cuando ambos equipos pueden operar disponibilidad, versiones, autenticación y observabilidad.

Los archivos son apropiados para lotes grandes, intercambios periódicos, conciliaciones, sistemas legados y escenarios donde se necesita una evidencia completa reprocesable. No son un mecanismo inferior; son inadecuados cuando la oportunidad del negocio no tolera la espera o cuando el proceso manual alrededor del archivo elimina su trazabilidad.

También existe un diseño híbrido. Una API puede iniciar una exportación y devolver un identificador; el archivo se produce de forma asíncrona y el consumidor consulta o recibe un evento cuando está listo. Otra opción es usar archivos para carga inicial y eventos o API para cambios posteriores.

Una decisión explícita y reversible

1. Definir evento empresarial, productor, consumidor y plazo útil.
2. Estimar volumen, frecuencia, picos y recuperación histórica.
3. Especificar contrato, versión y compatibilidad.
4. Diseñar autenticación, autorización, integridad y retención.
5. Probar fallas, duplicados, retrasos y cambios de esquema.
6. Asignar monitoreo, soporte y procedimiento de reproceso.

La mejor integración no es la más novedosa. Es la que cumple el tiempo del negocio, conserva significado, falla de forma visible y puede recuperarse sin improvisación.