Muchos problemas de integración que aparecen meses después se decidieron mal en la primera conversación, normalmente sin que nadie notara que estaba tomando una decisión. Nadie escribió qué sistema era responsable del correo del cliente. Ahora ambos creen serlo y lo actualizan en direcciones opuestas cuando alguien de soporte olvida en qué pantalla está.
Un brief de integración API, el contrato de datos del que hablo en la página del servicio, es el documento breve que evita esto. Se escribe antes de desarrollar y responde a una pregunta: ¿qué estamos acordando construir exactamente?
¿Qué debe incluir un brief de integración API?
Una fuente de verdad para cada campo que se mueve, su dirección y frecuencia, una clave de idempotencia que define un duplicado, una persona responsable de autorización y errores, y criterios de aceptación que se puedan comprobar sin otra conversación. Esa es la lista completa.
Esta plantilla reúne esas decisiones en una o dos páginas para acordarlas antes de desarrollar.
El objetivo del proceso y los sistemas implicados
El brief responde a algo más concreto que «conectar el sistema A con el B». Dos o más sistemas rara vez necesitan todo lo que contiene el otro. Normalmente uno necesita unos pocos campos del otro, ante un desencadenante y en una dirección.
La primera sección nombra los sistemas y la tarea en lenguaje sencillo: cuáles intervienen, qué activa el intercambio y qué significa «terminado» para una ejecución. Un cliente se registra, llega un webhook o alguien de soporte necesita ver el estado de entrega de otro sistema. Esta sección es breve a propósito. Evita que la petición crezca en silencio hasta convertirse en «conectar todo con todo», que es donde empiezan el coste y los duplicados.
Para el caso hipotético de CRM y facturación que usamos abajo: Sistemas: un CRM y una herramienta de facturación. Desencadenante: se emite una factura o cambia una dirección de facturación. Terminado: el otro sistema guarda el valor nuevo una sola vez.
Fuente de verdad y campos
Para cada campo que se mueve entre sistemas, el brief establece quién es responsable de él. No es el sistema del que resulta más fácil leerlo, sino aquel cuyo valor se considera correcto cuando ambos discrepan.
Ejemplo hipotético: un CRM y una herramienta de facturación guardan la dirección de facturación del cliente. Si el comercial la corrige en el CRM tras una llamada, el CRM es la fuente de verdad, aunque la herramienta de facturación la necesite para imprimir una factura. Escribir «el CRM es responsable de la dirección; facturación la recibe» resuelve en una línea una discusión que aparecería en la primera discrepancia.
Cada campo tiene también una dirección, qué sistema escribe y cuál lee, y una frecuencia: en tiempo real ante un evento, por consultas periódicas o por lotes durante la noche. Una sincronización bidireccional suele ser varios flujos unidireccionales que comparten conexión. Nombrarlos por separado evita que una petición bienintencionada de «sincronizar todo» termine con dos sistemas sobrescribiéndose mutuamente.
Este es el ejemplo completado para el caso anterior:
Tabla comparativa — desplázate horizontalmente para ver todas las columnas
| Campo | Responsable, fuente de verdad | Dirección | Frecuencia | Clave de idempotencia |
|---|---|---|---|---|
| Dirección de facturación del cliente | CRM | CRM → herramienta de facturación | Al cambiar, mediante webhook | ID de cliente + versión de la dirección |
| Total y líneas de la factura | Herramienta de facturación | Herramienta de facturación → CRM | Al emitir, mediante webhook | ID de factura |
| Estado del pago | Herramienta de facturación | Herramienta de facturación → CRM | Cada 30 minutos, mediante consulta | ID de factura + marca de tiempo del estado |
La clave de idempotencia es lo que muchos borradores omiten. Evita el fallo más común: que el mismo evento llegue y se procese dos veces. No tiene que ser compleja; a menudo basta el ID de factura. Debe quedar escrita antes de desarrollar, no descubrirse cuando una factura duplicada aparece en una bandeja de entrada.
Autorización, errores y responsabilidad
El brief debe decir qué ocurre si algo falla. Una integración que solo funciona cuando todo va bien no está terminada.
La autorización indica quién gestiona las credenciales de cada lado, dónde se guardan y quién puede revocarlas si hay que desactivar la integración con urgencia. Los errores cubren tres preguntas: qué fallo permite un reintento y cuál es permanente, dónde termina una ejecución que agota sus reintentos, y a quién se avisa. La cola o registro de fallos definitivos, la vía dead-letter, debe revisarla alguien. «Un correo al desarrollador» es una respuesta válida si está escrita; el fallo habitual es que nadie decidió, no que se eligiera a la persona equivocada.
Para el ejemplo de CRM y facturación: Credenciales: una clave de API por lado, gestionada por la persona responsable de operaciones en el gestor de contraseñas de la empresa; cada lado puede revocar la suya. Reintentable: tiempos de espera agotados y respuestas 5xx, hasta el límite acordado. Permanente: una respuesta 4xx por un ID de cliente desconocido. Registro de fallos definitivos: una tabla de ejecuciones fallidas en la base de datos de la integración. Aviso: a la persona responsable de operaciones, por correo, por cada ejecución que termina en ese registro.
Un caso documentado públicamente: Shopify advierte que la entrega de webhooks no siempre está garantizada y recomienda dos medidas. Ignorar duplicados mediante la cabecera X-Shopify-Webhook-Id de cada evento y ejecutar una conciliación periódica que consulte la API para no depender solo de webhooks. Estos detalles explican por qué hacen falta una clave de idempotencia y una vía de fallos definitivos, en esta API y en muchas otras que envían webhooks.
Criterios de aceptación
El brief define qué significa «terminado» de forma que una tercera persona pueda comprobarlo sin preguntarte qué querías decir. Para el mismo ejemplo:
- Cada factura emitida aparece en el cliente correspondiente del CRM dentro del plazo de la frecuencia acordada.
- Un webhook entregado dos veces con el mismo ID de factura genera exactamente un registro.
- Un cambio de dirección de facturación hecho en el CRM se refleja en la siguiente factura emitida para ese cliente.
- Una entrega que agota sus reintentos aparece en el registro de fallos definitivos con el ID de factura y genera una alerta a la persona indicada; no queda solo en un log.
- Volver al proceso manual, desactivando el webhook, requiere un paso documentado y ningún cambio de código.
Cada punto nombra un hecho comprobable: un recuento, un registro o una entrada de log. No una impresión de que la integración «funciona bien».
Qué no decide este brief
El documento tiene un alcance concreto. No fija precio ni plazo; se acuerdan cuando el alcance permite presupuestar.
Tampoco elige entre webhook, consultas periódicas o exportación programada más allá de lo que implique la frecuencia de la tabla. Esa decisión suele depender de restricciones que el brief no recoge, como límites de solicitudes o un planificador ya existente. Y no evalúa tu configuración de tracking o analítica: sincronizar CRM y facturación y medir un evento de compra de GA4 son preguntas distintas. Este documento no trata la segunda.
Un ejemplo completado y una plantilla en blanco
La tabla y los criterios anteriores son un ejemplo para dos sistemas hipotéticos, un CRM y una herramienta de facturación. Nada procede de la implementación de un cliente. El único comportamiento real de plataforma citado es el de Shopify, tal como lo describe su documentación pública.
La plantilla en blanco, descarga Markdown, tiene las mismas secciones y tabla con las filas vacías, para que la completes con tus sistemas antes de hablar de desarrollo. Si prefieres prepararla conmigo, eso forma parte del trabajo de integración API y automatización, dentro de la lista de servicios. En sobre mí explico brevemente cómo abordo este trabajo.
Si prefieres hablarlo primero, contacta conmigo con los sistemas implicados y lo que hoy no funciona.
