La elección depende del flujo, no de la moda
CSV, API y webhook pueden transportar la misma información, pero no ofrecen la misma experiencia operativa. Un CSV puede ser la opción más robusta para un intercambio semanal revisado por una persona. Una API permite consultar datos cuando se necesitan. Un webhook reduce latencia al avisar de que algo ha ocurrido.
Elegir la alternativa más moderna sin considerar frecuencia, permisos y recuperación suele añadir coste. La pregunta adecuada es qué nivel de actualización necesita la decisión y qué capacidad existe para mantener la integración.
Qué es un CSV
CSV es un formato de texto tabular. Cada registro ocupa una línea y los campos se separan mediante un delimitador. RFC 4180 documenta un formato común y el tipo de medio text/csv, aunque en la práctica existen variantes de delimitador, codificación, encabezados y comillas.
Un CSV puede descargarse desde una aplicación, depositarse en una carpeta, enviarse por un canal acordado o generarse automáticamente. Su principal ventaja es la inspección: una persona puede abrirlo y entender columnas y filas. También desacopla horarios; el receptor procesa el archivo cuando está preparado.
Sus límites aparecen cuando se necesita actualización frecuente, alto volumen, cambios parciales o confirmación inmediata. El formato no define autenticación, reintentos, versión del esquema ni significado de los campos. Todo eso debe acordarse alrededor del archivo.
Qué es una API
Una API expone operaciones para consultar o modificar información mediante un contrato. En una API HTTP, el cliente realiza solicitudes a endpoints, se autentica y recibe respuestas estructuradas, normalmente JSON.
La API permite seleccionar recursos, filtrar por fechas, paginar y repetir consultas. Puede servir para sincronizaciones periódicas o interacciones en tiempo real. Su disponibilidad real depende del proveedor, contrato, permisos, límites de uso y documentación.
Una especificación como OpenAPI puede describir rutas, parámetros, respuestas y esquemas. No garantiza por sí sola que la integración sea fiable: siguen siendo necesarios manejo de errores, reintentos, observabilidad y compatibilidad de versiones.
Qué es un webhook
Un webhook es una notificación HTTP enviada por un sistema cuando ocurre un evento. En lugar de preguntar cada minuto si existe un pedido nuevo, el receptor recibe un aviso al crearse.
El webhook reduce latencia y consultas innecesarias, pero exige un endpoint disponible, autenticación o verificación de firma, respuestas rápidas, reintentos y protección frente a eventos duplicados o fuera de orden.
La notificación no siempre contiene todos los datos. Un patrón habitual es recibir un identificador y consultar después la API para obtener el estado actual. Así se combina evento con lectura autorizada.
Comparación rápida
| Criterio | CSV | API | Webhook |
|---|---|---|---|
| Frecuencia ideal | Periódica o puntual | Bajo demanda o periódica | Al producirse eventos |
| Latencia | Minutos, horas o días | Depende de la consulta | Habitualmente baja |
| Complejidad inicial | Baja a media | Media | Media a alta |
| Inspección manual | Muy sencilla | Requiere herramienta | Requiere registros |
| Cambios parciales | Poco eficiente | Natural | Natural como aviso |
| Reintentos | Reprocesar archivo | Control del cliente | Coordinados entre emisor y receptor |
| Duplicados | Archivo o filas repetidas | Consultas repetidas controlables | Deben esperarse y deduplicarse |
| Disponibilidad receptora | Puede procesar después | Debe alcanzar al servidor | Debe recibir o recuperar eventos |
| Seguridad | Canal, cifrado y acceso al archivo | Token, scopes y transporte seguro | Firma, secreto, HTTPS y protección anti-replay |
| Mantenimiento | Esquema y canal | Versiones, límites y credenciales | Eventos, firmas, reintentos y orden |
| Mejor uso | Lotes revisables | Consulta y sincronización | Notificación de cambios |
Cuándo elegir CSV
CSV suele ser adecuado cuando el intercambio es diario, semanal o mensual; el volumen cabe en un archivo manejable; existe revisión humana; y no se necesita respuesta inmediata.
Ejemplos:
- importar tarifas cada noche;
- recibir el cierre semanal de rendimiento;
- migrar datos entre sistemas;
- entregar un conjunto a un analista;
- cargar una plantilla inicial.
Para que sea fiable debe existir una convención:
- nombre y versión del archivo;
- codificación y delimitador;
- encabezados obligatorios;
- formato de fechas y decimales;
- unidad de cada campo;
- clave única;
- forma de representar vacíos;
- canal de entrega;
- respuesta ante errores.
El proceso debería validar antes de importar y producir un informe de filas aceptadas y rechazadas. No conviene corregir silenciosamente columnas desconocidas.
Cuándo elegir API
Una API encaja cuando el receptor necesita seleccionar periodos, consultar cambios frecuentes, acceder a muchos recursos o integrar una operación dentro de una aplicación.
Ejemplos:
- consultar disponibilidad antes de confirmar una reserva;
- sincronizar clientes modificados desde la última ejecución;
- recuperar sesiones por fecha;
- crear un pedido desde otro sistema;
- actualizar el estado de una incidencia.
Antes de adoptarla hay que comprobar:
- autenticación y alcance de credenciales;
- límites de solicitudes;
- paginación;
- filtros disponibles;
- versionado;
- códigos de error;
- idempotencia;
- entorno de pruebas;
- política de cambios;
- soporte y condiciones contractuales.
La sincronización debe guardar un cursor o marca fiable. “Consultar los últimos siete días” puede perder cambios antiguos corregidos hoy o duplicar datos en cada ejecución.
Cuándo elegir webhook
Un webhook aporta valor cuando la reacción debe comenzar poco después del evento y consultar continuamente sería ineficiente.
Ejemplos:
- iniciar preparación tras un pago confirmado;
- actualizar un expediente al recibir una firma;
- avisar de una carga completada;
- sincronizar un cambio de estado;
- invalidar una caché cuando cambia contenido.
Debe diseñarse asumiendo entrega repetida. El receptor registra un identificador de evento y responde de forma idempotente: procesar dos veces no duplica la acción.
También debe asumir retrasos y desorden. La hora del evento y la versión del recurso ayudan a decidir si una notificación antigua debe aplicarse. Si el endpoint estuvo caído más tiempo que la retención del proveedor, hace falta una consulta de reconciliación.
Patrones combinados
Webhook más API
El webhook informa de un cambio y la API entrega el estado completo. Reduce datos sensibles en la notificación y evita depender de un payload que puede quedar obsoleto.
API más exportación de respaldo
La API mantiene el flujo diario y una exportación periódica permite reconciliar totales o recuperar un periodo. No debe duplicar registros; ambas rutas comparten identificadores.
CSV con carga automatizada
Un archivo depositado en una ubicación controlada dispara validación e importación. Es una automatización por lotes, no una API, y puede ser suficiente durante años.
CSV para arranque y API para cambios
Una migración inicial utiliza un archivo completo. Después, la API sincroniza altas y modificaciones. Esto evita miles de consultas históricas.
Fiabilidad: diseñar para fallos
Ningún mecanismo elimina errores. La diferencia es cómo se detectan y recuperan.
En CSV, conservar el archivo original, registrar su huella y no importarlo dos veces. En API, aplicar reintentos con límites, distinguir errores temporales de definitivos y guardar progreso. En webhooks, verificar autenticidad, deduplicar y disponer de una reconciliación posterior.
Todos necesitan observabilidad: última ejecución correcta, número de registros, rechazos, retraso y motivo de fallo. Una integración que sólo avisa cuando un usuario nota datos ausentes no está operada.
Seguridad y permisos
El transporte debe ser seguro, pero también importa el alcance. Un CSV completo puede exponer más datos que una consulta filtrada. Una API con token global puede exceder la necesidad. Un webhook puede revelar información en registros si el payload se almacena sin control.
Buenas prácticas generales:
- credenciales distintas por integración;
- permisos mínimos;
- secretos fuera del código y de los archivos;
- rotación y revocación;
- validación de firma cuando exista;
- registro sin datos sensibles innecesarios;
- cifrado en tránsito y almacenamiento;
- retención definida;
- pruebas con datos sintéticos.
Coste total
CSV suele tener menor coste inicial, pero puede acumular trabajo manual. Una API requiere desarrollo y mantenimiento, aunque reduce tareas repetidas. Un webhook añade operación continua y gestión de eventos, pero evita sondeo frecuente.
El coste debe incluir personas que atienden incidencias, cambios de proveedor, monitorización y recuperación. La integración más barata de construir puede ser la más cara de operar si falla sin aviso.
Regla de decisión
Elegir CSV cuando un lote periódico, verificable y sencillo cubre la necesidad. Elegir API cuando hay que consultar o modificar recursos de forma controlada. Añadir webhook cuando la latencia del evento importa y existe capacidad para operar un receptor fiable.
Si hay dudas, empezar con el mecanismo más simple que cumpla frecuencia y seguridad, definir identificadores y controles, y dejar preparada una evolución. Una arquitectura de datos bien separada permite cambiar el transporte sin rehacer las reglas de negocio.