Una API, interfaz de programación de aplicaciones, es simplemente una forma documentada de que un software pida datos a otro software, o de que haga que algo ocurra. Cuando un CRM envía un nuevo contacto a una plataforma de email, o una tienda online publica un pedido en un sistema contable, están usando APIs.
Tres patrones habituales
Petición / respuesta
Un sistema pregunta, el otro responde: "dame este cliente", "crea este pedido". Sencillo y predecible, pero requiere que una de las partes sepa cuándo preguntar.
Webhooks
En lugar de preguntar repetidamente, el sistema de origen envía un evento a una URL cuando ocurre algo: "se ha creado una nueva factura", "un pago se ha completado". Menor latencia y mayor eficiencia para flujos basados en eventos.
Sincronización programada
Tareas periódicas mueven datos por lotes, cada hora, cada noche, cada semana. Útil cuando la frescura no es crítica y un envío es poco práctico.
La mayoría de las integraciones reales combinan al menos dos de estos patrones.
Qué hace que una integración sea fiable
- Propiedad clara de los datos. Un sistema es la fuente de verdad para cada pieza de datos. Los demás reciben copias.
- Operaciones idempotentes. Repetir la misma llamada dos veces produce el mismo resultado, esencial para webhooks y redes inestables.
- Gestión de errores visible. Los fallos van a algún sitio donde una persona pueda verlos, no a un registro silencioso que nadie lee.
- Límites de tasa respetados. Las buenas integraciones reducen el ritmo cuando la otra parte va lenta o limitada.
- Conciencia del versionado. Las APIs cambian. Trata la integración como código que necesita actualizaciones, no como un cableado de una sola vez.
Qué hace que una integración sea frágil
- Exportaciones CSV enviadas por email por toda la empresa y reimportadas manualmente.
- Credenciales escritas a mano en lugares que nadie recuerda.
- Un único script largo que lo hace todo sin lógica de reintentos.
- Fallos silenciosos, los datos dejan de fluir y nadie se da cuenta durante semanas.
- Sincronización bidireccional sin reglas de conflicto claras: ¿qué lado gana cuando ambos han cambiado?
¿Middleware o integración directa?
Hay tres enfoques principales:
- Integración directa: el sistema A habla directamente con el sistema B. Lo más simple para un único enlace, se complica cuando hay muchos.
- Plataforma de integración (iPaaS): una herramienta dedicada como una plataforma de flujos de trabajo gestiona los conectores. Buena para flujos simples y comunes; puede ser cara y opaca para lógica compleja.
- Middleware personalizado: un pequeño servicio interno que asume la lógica de integración, las traducciones y la gestión de errores. A menudo es la opción correcta cuando la lógica es específica del negocio.
La mejor respuesta depende de cuántos sistemas necesitan comunicarse entre sí, cuánta lógica personalizada hay implicada, y si quieres las reglas de negocio en la interfaz de un proveedor o en código que tú posees.
Un ejemplo concreto de webhook
Supón que una plataforma de comercio electrónico debe notificar a tu sistema contable cada vez que se paga un pedido. En lugar de consultar cada minuto, la tienda llama a tu endpoint con una pequeña carga JSON:
{
"event": "order.paid",
"event_id": "evt_8f3c21a9",
"occurred_at": "2024-11-12T09:41:07Z",
"order": {
"id": "ORD-10427",
"total": 1499.00,
"currency": "PLN",
"customer_email": "k.nowak@example.com"
}
}El servicio receptor debe aceptar la petición, verificar una cabecera de firma, almacenar el event_id y devolver 200 rápidamente. El trabajo real, como crear una factura, ocurre en una tarea en segundo plano. Si el mismo evento llega dos veces, el event_id almacenado evita una factura duplicada.
Regla general: los gestores de webhooks deben confirmar rápido y hacer el trabajo de forma asíncrona. Cualquier cosa lenta o frágil, una llamada a una API de terceros, una renderización de PDF, pertenece a una cola, no al gestor HTTP.
Gestionar reintentos sin duplicados
Toda integración fiable necesita una clave de idempotencia. Un patrón mínimo en pseudocódigo:
async function handleOrderPaid(event) {
if (await seen(event.event_id)) return; // already processed
await markSeen(event.event_id);
await queue.enqueue('create-invoice', event.order);
}Errores habituales
- Integrar demasiado pronto. Si el proceso no es estable, la integración codificará el desorden y hará más difícil cambiarlo.
- Sincronización bidireccional por defecto. La unidireccional es más simple y a menudo suficiente, opta por la bidireccional solo si el negocio realmente lo necesita.
- Sin monitorización. Una integración sin alertas es un fallo silencioso esperando a ocurrir.
- Acoplamiento fuerte. Los cambios en un sistema no deberían romper todos los demás. Mantén una capa de traducción.
Un enfoque realista
- Dibuja el flujo de datos: qué sistema posee qué campo y quién necesita copias.
- Empieza por el flujo individual más doloroso y constrúyelo primero de forma unidireccional.
- Usa webhooks donde importe la baja latencia, y sincronización programada donde no.
- Añade monitorización desde el primer día, no después del primer fallo.
- Documenta credenciales, endpoints y propiedad, para que la integración sobreviva a los cambios de personal.
