Documentar un flujo de integración de API

Qué incluir

• Los actores como carriles: usuario, frontend, tu backend y cada servicio externo.
• Las llamadas en orden, con método y ruta.
• Decisiones sobre las respuestas: éxito, error del cliente, error del servidor, tiempo agotado.
• Los reintentos y sus límites.
• Los pasos asíncronos: webhooks, consultas periódicas, colas.
• Los estados finales: qué ve el usuario y qué se guarda en cada caso.

Ejemplo: pago con tarjeta

1. Frontend: el cliente confirma el pedido.
2. Backend: crea un pago en el proveedor (POST /payments).
3. Decisión: ¿qué respuesta llega?
   • Creado → esperar la confirmación.
   • Rechazado → mostrar «tarjeta rechazada», fin.
   • Tiempo agotado o error del servidor → reintentar.
4. Reintentar hasta 3 veces con una espera creciente; después, marcar el pedido como «pago pendiente» y avisar a soporte.
5. Proveedor: envía un webhook cuando el pago se completa o falla.
6. Backend: verifica la firma del webhook, actualiza el pedido y envía el recibo.

Dibujado en carriles, el diagrama deja claro que el estado del pedido depende del webhook y no de la primera respuesta, una fuente habitual de errores.

Representa bien los reintentos

Un reintento es un bucle, y todo bucle necesita salida, como se explica en decisiones y bucles. Escribe el límite en el diagrama («máx. 3 intentos») y dibuja qué pasa tras el último fallo. Si una llamada se puede repetir sin riesgo, indica cómo se garantiza la idempotencia, por ejemplo con una clave de idempotencia, para que quien lo lea sepa que los duplicados están controlados.

Webhooks y esperas

Representa la espera de forma explícita con un paso de espera («Esperar el webhook del proveedor») y una rama de tiempo agotado («Sin webhook tras 15 minutos → consultar el estado del pago»). Sin ese plazo, el diagrama da a entender que el sistema puede esperar indefinidamente.

Diagrama de flujo, de secuencia o ambos

El diagrama de flujo responde a «¿qué pasa en cada caso?». El de secuencia, a «¿quién llama a quién y en qué orden?». En integraciones complejas, guarda los dos juntos en el repositorio, como código Mermaid en GitHub.

Parte de la especificación

Si la API de terceros publica un archivo OpenAPI, impórtalo para tener los nombres exactos de los endpoints en cada paso automático; consulta de OpenAPI a diagrama de flujo. Para el inicio de sesión, el registro y la renovación de tokens, la guía de flujos de autenticación recoge las ramas que suelen olvidarse.

Esboza tu diagrama de integración.