Integración de APIs de terceros: autenticación, reintentos y mantenimiento

Cada proveedor elige su mecanismo: claves de API estáticas, OAuth 2.0 con credenciales de cliente, certificados de cliente o firmas de cada petición. En OAuth 2.0, el marco descrito en la RFC 6749, la concesión por credenciales de cliente es la habitual para integraciones entre servidores, y los tokens de acceso caducan, de modo que tu sistema tiene que obtener uno nuevo sin intervención humana. Sea cual sea el mecanismo, las decisiones de diseño son parecidas.

• Guardar credenciales en un gestor de secretos o almacén cifrado, nunca en el código ni en ficheros del repositorio.
• Usar credenciales distintas para pruebas y producción, y si el proveedor lo permite, una por integración.
• Pedir los permisos mínimos: si solo consultas envíos, la credencial no debería poder crear ni cancelar.
• Planificar la rotación: quién la hace, con qué periodicidad y cómo se despliega sin cortar el servicio.
• Vigilar fechas de caducidad de certificados y avisar con antelación suficiente.
• Registrar el uso de cada credencial para detectar llamadas inesperadas.

Casi todas las APIs públicas imponen límites: peticiones por segundo, por minuto o por día, tamaño máximo de lote o número de conexiones simultáneas. Cuando se superan, el estándar HTTP prevé el código 429, definido en la RFC 6585, que puede acompañarse de una cabecera Retry-After indicando cuánto esperar. Algunos proveedores además facturan por llamada, por lo que un bucle descontrolado puede costar dinero, algo que OWASP también señala en su riesgo de consumo de recursos sin restricciones.

• Leer las cuotas en la documentación y en el contrato, y diseñar el volumen previsto por debajo con margen.
• Aplicar un limitador en tu lado para no depender de que el proveedor te frene.
• Agrupar operaciones cuando la API ofrece endpoints por lotes.
• Guardar en caché las respuestas que cambian poco, como catálogos o tablas de códigos.
• Separar el tráfico urgente del diferible para que una sincronización masiva no bloquee operaciones de usuario.

Un fallo temporal, como un tiempo de espera agotado o un error 503, invita a reintentar. Pero reintentar sin criterio puede empeorar las cosas: saturar a un proveedor que ya tiene problemas, o duplicar una operación que en realidad sí se completó. La guía sobre cómo conectar un MES con un ERP explica la idempotencia en mensajes internos; con terceros, la diferencia es que dependes de lo que ofrezca su API.

Para operaciones con efecto económico o legal, como un cobro o el envío de un documento a una administración, lo prudente es asignar un identificador propio a cada operación, guardarlo antes de llamar y, ante una respuesta dudosa, consultar al proveedor si esa operación ya existe. Si su API no permite consultarlo, conviene dejar el caso en una bandeja de revisión en lugar de reintentar a ciegas.

Los proveedores publican versiones nuevas, marcan las antiguas como obsoletas y acaban retirándolas. También hacen cambios menores que consideran compatibles, como añadir campos o nuevos valores en un estado, y que pueden romper un cliente que no los esperaba. La defensa principal es aislar la integración detrás de un adaptador propio: el resto de tu sistema trabaja con tu modelo de datos y solo el adaptador conoce la API externa.

• Fijar explícitamente la versión de la API que se usa, si el proveedor lo permite.
• Tolerar campos desconocidos y valores nuevos en enumeraciones sin romper el procesamiento.
• Suscribirse a los avisos de cambios del proveedor y asignar a alguien su lectura.
• Mantener pruebas automáticas contra el entorno de pruebas del proveedor y ejecutarlas periódicamente, no solo al desplegar.
• Anotar en el inventario de integraciones la fecha de retirada anunciada de cada versión en uso.

Una integración con un tercero puede fallar en silencio: el proveedor responde, pero con datos vacíos, o un webhook deja de llegar sin error alguno. La monitorización debe vigilar tanto los fallos visibles como las ausencias.

• Tasa de errores y latencia por endpoint, con umbrales de alerta razonables.
• Tiempo desde el último mensaje o webhook recibido, para detectar silencios anómalos.
• Tamaño de la cola de reintentos y de la bandeja de errores pendientes de revisión.
• Consumo frente a la cuota contratada.
• Registro de cada petición y respuesta con un identificador de correlación, cuidando no guardar datos sensibles innecesarios.

Parte del riesgo de una integración se gestiona en el contrato, no en el código. Antes de depender de un proveedor para una función crítica conviene revisar qué compromete por escrito y qué no.

• Nivel de servicio comprometido, si existe, y qué compensación o recurso hay si no se cumple.
• Plazo de preaviso ante cambios incompatibles o retirada de versiones.
• Condiciones de uso de los datos que envías: finalidad, retención, ubicación y subencargados, especialmente si son datos personales.
• Límites de uso incluidos y coste de superarlos.
• Qué ocurre al terminar la relación: exportación de datos y periodo de transición.

La valoración jurídica corresponde a vuestra asesoría, pero conviene que el equipo técnico participe: sabe qué compromisos son relevantes para el diseño y cuáles no.

1. ¿Qué ocurre en tu negocio si la API no responde durante una hora? ¿Hay un modo degradado definido?
2. ¿Están las credenciales en un almacén seguro, con permisos mínimos y rotación planificada?
3. ¿Se conocen las cuotas y hay un limitador propio por debajo de ellas?
4. ¿Las operaciones con efecto tienen identificador propio y una regla clara ante respuestas ambiguas?
5. ¿La integración está aislada tras un adaptador y cubierta por pruebas periódicas?
6. ¿Alguien lee los avisos de cambios del proveedor y vigila los silencios, no solo los errores?
7. ¿El contrato cubre preaviso, tratamiento de datos y salida?

Cada «no» es una partida de mantenimiento futura. No siempre hay que resolverlas todas al principio, pero sí saber cuáles se aceptan y quién se ocupará de ellas.