Conectar una API suele dar una sensación engañosa de progreso: hacemos una petición, llegan los datos y el servidor responde 200 OK. Eso solo comprueba que dos sistemas pueden comunicarse en condiciones normales. Una API funcionando no es lo mismo que una integración funcionando.
Si necesitás llevar esta lógica a sistemas reales, también hacemos integraciones API para conectar herramientas existentes sin reemplazarlas por defecto.
La diferencia aparece cuando dejamos de probar el caso feliz.
200 OK solamente dice que esa petición salió bien
Una respuesta exitosa confirma algo bastante limitado. El servidor recibió una solicitud y decidió responder correctamente. No necesariamente significa que:
- El dato enviado era el correcto
- El otro sistema lo procesó como esperábamos
- No se duplicó una operación
- El estado quedó sincronizado
- La próxima petición va a funcionar igual
- Podemos recuperar el proceso si algo falla después
Incluso puede ocurrir que una API responda correctamente y que el proceso real continúe de forma asíncrona detrás de escena. Desde nuestro lado todo parece terminado. Del otro lado, recién empezó.
Los errores fáciles son los menos interesantes
Un 500 es relativamente simple: algo falló, así que lo registramos, reintentamos o mostramos un error. Los problemas más complicados son los que parecen éxitos.
Supongamos que enviamos un pedido a un sistema externo. La API responde 200. Pero el producto asociado ya no existe. El sistema acepta el pedido, lo deja en un estado intermedio y una hora después falla un proceso interno.
Nuestra integración ya marcó la operación como completada. Ahora tenemos dos sistemas con versiones distintas de la realidad. Ese tipo de fallo es mucho más difícil de detectar que una respuesta directamente incorrecta.
Hay que entender qué significa éxito para cada operación
Antes de integrar conviene definir cuál es el resultado que realmente necesitamos confirmar. Puede ser: "el servidor recibió la solicitud". O:
"el registro fue creado". O: "el pago fue procesado". O: "el pedido llegó al sistema de fulfillment y ya puede prepararse". No son lo mismo. Una respuesta HTTP solamente cubre una parte del flujo. La integración tiene que saber cuándo una operación puede considerarse realmente terminada.
Las APIs tienen límites
Muchos servicios limitan cuántas solicitudes podemos hacer en determinado período. Durante el desarrollo, con diez productos, veinte usuarios y cinco pedidos, eso casi nunca importa.
Cinco pedidos. En producción aparecen cien mil registros y la misma estrategia deja de funcionar. Empiezan los 429 Too Many Requests. Ahí necesitamos pensar en:
- Procesamiento por lotes
- Colas
- Pausas entre solicitudes
- Límites dinámicos
- Reintentos
- Prioridades
Una integración diseñada con datos de prueba puede comportarse de una forma completamente distinta cuando llega volumen real.
Reintentar no significa repetir ciegamente
Si una petición falla por timeout, la reacción natural es volver a enviarla. Pero hay una pregunta importante:
¿sabemos que la primera operación no ocurrió?
Puede haber sucedido esto:
- Enviamos una solicitud
- El servidor externo procesa correctamente la operación
- La respuesta se pierde por un problema de red
- Nuestro sistema interpreta que falló
- Volvemos a enviar exactamente lo mismo
Ahora tenemos dos operaciones. Si era una consulta, probablemente no pase nada. Si era crear un pago, un pedido o una suscripción, tenemos otro problema.
Idempotencia
La idempotencia permite repetir una operación sin que el resultado se duplique. Algunas APIs ofrecen claves de idempotencia. Podemos enviar algo parecido a:
order-5821 y aunque la petición llegue dos veces, el servicio reconoce que ambas representan la misma operación. Cuando la API no ofrece ese mecanismo, puede ser necesario implementarlo de nuestro lado guardando identificadores externos y registrando las operaciones procesadas.
Comprobar estados antes de crear nuevos registros. El mecanismo exacto cambia. La idea no. Una integración debería poder sobrevivir a que una misma operación ocurra más de una vez.
Los webhooks tampoco son mensajes perfectos
Los webhooks son útiles para reaccionar rápidamente cuando algo cambia. Si el mecanismo todavía no está resuelto, esta comparación entre webhooks y polling desarrolla sus costos y modos de fallo. Pero no deberíamos asumir que llegarán una sola vez, en el orden correcto, inmediatamente o siquiera que llegarán. Un proveedor puede reenviar un webhook porque nuestro servidor tardó demasiado en responder. Dos eventos pueden llegar invertidos.
Una caída temporal puede hacer que una notificación aparezca varios minutos después. Por eso el webhook debería comunicar que algo cambió, pero el estado real debería poder verificarse contra la fuente original cuando sea necesario.
El orden puede romper cosas
Imaginemos dos eventos:
- Pedido creado
- Pedido cancelado
Por algún motivo llegan al sistema receptor en el orden contrario. Primero procesamos la cancelación. Después llega la creación. Si aplicamos los eventos sin validar nada, terminamos con un pedido activo que en origen está cancelado.
Las integraciones que manejan estados necesitan considerar que una red no garantiza necesariamente que la información llegue en el mismo orden en que ocurrió. A veces alcanza con timestamps. Otras veces necesitamos versiones, secuencias o consultar nuevamente el objeto antes de actualizarlo.
Sincronizar no siempre significa copiar todo
Una estrategia tentadora es pedir todos los registros cada cierto tiempo y comparar. Puede funcionar con cien elementos. Con cientos de miles empieza a ser caro. Una integración madura suele necesitar alguna forma de saber qué cambió.
Los cambios pueden detectarse por fecha de modificación, cursor, eventos, páginas incrementales o identificadores ya procesados. El objetivo es evitar revisar constantemente información que sabemos que no cambió.
Los logs deberían contar una historia
Guardar:
API error no ayuda demasiado. Un buen registro debería permitir reconstruir qué ocurrió. Qué sistema inició la operación. Qué entidad estaba involucrada.
El registro debería mostrar qué intentamos hacer, los identificadores local y externo, cuándo ocurrió, qué respondió el servicio y cuántas veces se reintentó. No significa guardar información sensible sin control, sino registrar suficiente contexto para entender el proceso.
Cuando una integración falla tres meses después de haber sido desarrollada, ese contexto vale muchísimo más que una descripción genérica del error.
También necesitamos saber que algo dejó de funcionar
Hay fallos que generan errores. Otros simplemente dejan de generar actividad. Un proceso que normalmente sincroniza mil registros por día puede pasar a sincronizar cero. No hay 500.
No hay excepción. Simplemente dejó de hacer lo que tenía que hacer. Por eso algunas integraciones necesitan monitoreo sobre comportamiento, no solamente sobre errores. ¿Cuándo fue la última sincronización?
Conviene controlar cuántos registros se procesaron o fallaron, si una cola está creciendo y cuánto tiempo pasó desde el último webhook. Una integración silenciosamente detenida puede ser peor que una que falla de forma visible.
Hay que pensar en cómo se arregla
No alcanza con detectar el problema. También hay que poder recuperar el sistema. Reprocesar un pedido. Volver a ejecutar un rango de fechas.
La recuperación puede requerir reenviar una operación, vaciar una cola, sincronizar nuevamente una entidad o corregir una relación y continuar. Si la única forma de arreglar una integración es modificar manualmente la base de datos, tenemos poca capacidad de recuperación. Las herramientas internas para operar una integración rara vez aparecen en la demo. Son las que terminan importando cuando el sistema lleva meses funcionando.
Las APIs cambian
Las APIs publican versiones nuevas, marcan campos como obsoletos, retiran métodos de autenticación y eliminan endpoints.
Cambios en límites de uso. Una integración externa siempre depende de decisiones que no controlamos. Por eso conviene saber qué versión estamos usando, seguir los avisos del proveedor y evitar depender de comportamientos accidentales que no están documentados. Si una API es crítica para el negocio, su mantenimiento también forma parte del producto.
La mejor integración no es la que nunca falla
Esa integración no existe: los servicios externos se caen, las redes fallan, los datos llegan mal, las credenciales vencen y las personas cambian configuraciones. Lo que importa es qué ocurre después. ¿Sabemos que falló?
¿Podemos entender por qué? ¿La operación puede reintentarse? ¿Existe riesgo de duplicarla? ¿Podemos recuperar el estado correcto? Ahí se empieza a medir la calidad real de una integración. Conseguir el primer 200 OK puede llevar una tarde. Diseñar cómo detectar, entender y recuperar los fallos es lo que convierte esa conexión en una integración operable.