Integrar una API de terceros cuando la documentación no alcanza

La documentación de una API rara vez cubre los casos que aparecen en producción. Límites de tasa que no coinciden con lo publicado, respuestas de error con formatos distintos según el endpoint, campos que cambian de nombre sin aviso en una versión menor. Cuando integras un proveedor de logística o una pasarela de pagos para una pyme, ese desfase entre lo documentado y lo real termina costando horas de soporte.

En este artículo repasamos cómo estructuramos una capa de integración en Node que aísla al resto del sistema de esas variaciones. La idea central es simple: el código de negocio no debería saber que existe un proveedor externo con sus rarezas. Todo lo que hable con el exterior pasa por un adaptador propio.

Reintentos con backoff exponencial

No todos los errores merecen un reintento. Un 400 por payload mal formado no se arregla repitiendo la llamada. Un 429 o un timeout de red sí. Distinguimos entre fallos transitorios y definitivos antes de decidir si volvemos a intentar, y aplicamos un backoff exponencial con jitter para no sincronizar reintentos entre workers.

Claves de idempotencia para no duplicar

Cuando un reintento llega después de que el proveedor ya procesó la operación original, el resultado puede ser un pedido duplicado o un cobro doble. Enviamos una clave de idempotencia generada por nosotros en cada request y la persistimos junto al estado de la operación. Si el proveedor la respeta, perfecto. Si no, al menos tenemos con qué reconciliar manualmente.

Logs que sirven a las tres de la mañana

Un log útil no es el que imprime el stack trace completo. Es el que permite reconstruir qué pasó sin abrir el código. Registramos el identificador de correlación, el endpoint, el código de respuesta, el tiempo de la llamada y el cuerpo de la respuesta cuando hay error. Nada de datos sensibles en claro, pero sí lo suficiente para saber si el problema fue nuestro, del proveedor o de la red.

Cuándo vale la pena un adaptador propio

Envolver una API externa en una capa propia tiene un costo: más código, más superficie que mantener. Vale la pena cuando el proveedor cambia con frecuencia, cuando hay varios consumidores internos del mismo servicio o cuando necesitamos traducir su modelo de datos al nuestro. No vale la pena cuando es una llamada puntual, aislada y sin probabilidad de repetirse. En ese caso, un cliente HTTP directo con manejo de errores básico es suficiente.