La fiabilidad también depende de la integración
Una API de IA puede responder correctamente a una petición y, aun así, fallar dentro de la aplicación que la consume. El motivo puede estar en un campo que cambia de nombre, una respuesta que ya no cumple el formato esperado, una petición limitada por cuota o una demora que supera el tiempo de espera configurado. El contrato de integración define qué intercambian los sistemas y cómo interpretan cada resultado; no hace que el modelo sea más exacto ni garantiza que el proveedor esté disponible.
Conviene distinguir dos cuestiones. La calidad de una inferencia depende, entre otros factores, del modelo, sus instrucciones y los datos de entrada. La integridad del canal depende de que la aplicación envíe peticiones válidas, interprete respuestas y errores de forma controlada y preserve el estado cuando una operación no termina. Un contrato claro puede reducir fallos de acoplamiento, pero no elimina la variabilidad del modelo ni sustituye las pruebas de producto.
Las APIs conectan productores y consumidores que pueden cambiar a ritmos distintos. Un contrato formal describe operaciones, parámetros, formatos de entrada y salida, errores, autenticación y reglas de evolución. Para una API HTTP, una especificación OpenAPI puede documentar rutas y esquemas; JSON Schema puede definir la forma de un objeto JSON. Esas herramientas permiten validar ciertas propiedades, pero la aplicación todavía debe comprobar reglas semánticas que el esquema no representa.
En una integración con un modelo, por ejemplo, el JSON puede tener la estructura correcta y contener una recomendación que no corresponde al caso. La validación estructural detecta tipos incorrectos o campos obligatorios ausentes; no demuestra que el contenido generado sea verdadero, seguro o adecuado. Separar ambas capas evita presentar una validación técnica como garantía de calidad.
El diseño también debe reflejar el alcance real de la evidencia. Las guías prácticas sobre contratos e integración describen patrones generales; no establecen una política universal para todos los proveedores de IA. Los límites de tasa, tiempos de espera, identificadores de modelo, formatos de error y garantías de compatibilidad dependen de cada servicio y pueden cambiar. Antes de fijar el contrato de una integración concreta, hay que verificar la documentación aplicable al proveedor, la versión y el entorno que se utilizarán.
Qué debe fijar un contrato de integración
Un contrato útil empieza por el propósito de la operación, no por una lista de campos. Identifica quién llama a quién, qué resultado necesita el proceso y qué consecuencias tiene cada respuesta. Para una petición de generación, puede definir el objetivo de la operación, los datos que se envían, el formato esperado y qué debe hacer la aplicación si el proveedor devuelve un error o no responde a tiempo.
La especificación debe separar lo que la aplicación exige de lo que el proveedor permite omitir. Los campos obligatorios deberían ser mínimos y estar justificados por el flujo. Los opcionales necesitan una conducta definida cuando falten. Los valores enumerados deben describir estados cuyo significado se mantenga estable, y las restricciones de longitud o rango deben corresponder a límites reales, no a cifras supuestas.
También se deben precisar aspectos que suelen quedar implícitos: codificación, unidades, fechas, zona horaria, tratamiento de cadenas vacías, claves desconocidas, paginación si existe y límites del cuerpo de la petición. Cuando el sistema intercambia datos sensibles, el contrato operativo debe indicar qué información no se registra y quién puede acceder a credenciales y trazas. Autenticar una aplicación no autoriza automáticamente cada operación sobre cada recurso.
Los errores merecen el mismo cuidado que la respuesta exitosa. La aplicación necesita distinguir, por ejemplo, un rechazo de validación, un fallo de autorización, un límite de consumo, un error temporal del servicio y un resultado ambiguo debido a una interrupción. Las categorías exactas y sus códigos deben ajustarse a la documentación del proveedor; no conviene asumir que todos los servicios usan la misma estructura.
Un contrato puede describir el formato, pero no resolver por sí solo qué hacer con la respuesta. Si el proceso necesita una decisión humana, una puntuación que supere cierto umbral o una operación con efectos, esa regla pertenece a la lógica del producto y debe probarse por separado. Una interfaz bien descrita facilita la coordinación; la autorización y las reglas de negocio siguen siendo responsabilidad de la aplicación.
Elementos del contrato y su propósito
| Elemento | Qué conviene especificar | Límite |
|---|---|---|
| Operación | Ruta o acción, método y finalidad | No determina si la operación es correcta para el negocio |
| Petición | Campos, tipos, obligatoriedad y restricciones | No valida por sí sola permisos ni significado |
| Respuesta | Estructura, campos opcionales y variantes esperadas | No demuestra la veracidad del contenido generado |
| Errores | Categorías, datos seguros y conducta de la aplicación | Los códigos y formatos dependen del servicio concreto |
| Evolución | Compatibilidad, deprecación y coordinación de consumidores | La compatibilidad debe comprobarse con los clientes reales |
Validar entradas y respuestas sin confundir forma y significado
La validación de entrada debe impedir que una petición mal formada llegue al límite externo, cuando la aplicación puede detectar el problema antes. Comprueba tipos, campos requeridos, longitudes, rangos y relaciones entre campos. La validación del proveedor sigue siendo necesaria: las reglas locales no sustituyen los controles del servicio y pueden quedar desactualizadas si cambia su interfaz.
La respuesta requiere una comprobación equivalente antes de que otros componentes la consuman. Una respuesta JSON válida no necesariamente tiene el esquema previsto; una respuesta que sí tiene ese esquema no necesariamente satisface las reglas del dominio. Valida primero la estructura y después las condiciones específicas del producto. Si una salida incumple una condición crítica, el sistema debe rechazarla, aislarla o enviarla a revisión, en vez de transformarla silenciosamente en una respuesta aparentemente válida.
En las salidas de modelos generativos, los campos opcionales deben seguir siendo opcionales en el código consumidor. No conviene asumir que el modelo siempre incluirá una propiedad solo porque aparezca en ejemplos anteriores. Si una propiedad resulta necesaria para continuar el flujo, la aplicación debe establecer qué ocurre cuando falta: reintento limitado, respuesta alternativa, revisión humana o error controlado.
Cuando una salida estructurada participa en una operación con consecuencias, el formato no debe confundirse con un control determinista. Un validador puede rechazar un valor fuera de rango; un clasificador probabilístico que produzca ese valor no se convierte por ello en un mecanismo de autorización. Las acciones sensibles requieren controles explícitos en el sistema que ejecuta la operación.
Las pruebas deben incluir respuestas válidas, campos ausentes, tipos inesperados, valores desconocidos y cargas excesivas. También conviene probar errores parciales y respuestas truncadas si el proveedor o el transporte pueden producirlas. Los casos de prueba deben representar el contrato y los riesgos del flujo real, no solo repetir ejemplos de documentación.
Evolucionar la interfaz sin romper consumidores
Una interfaz cambia cuando se añade una operación, se altera un tipo, se renombra un campo o se modifica el significado de un valor existente. El criterio práctico es preguntar si los consumidores actuales pueden seguir funcionando sin cambios. Añadir un campo opcional puede ser compatible si los clientes toleran campos desconocidos; renombrar un campo o convertirlo en obligatorio suele exigir coordinación.
No basta con etiquetar un cambio como menor o mayor mediante versionado semántico. La etiqueta solo ayuda si el equipo ha definido qué significa y la aplica de forma coherente. Un cambio aditivo no es automáticamente seguro: un consumidor estricto puede fallar ante una propiedad nueva, y un cambio aparentemente compatible puede alterar la interpretación de una respuesta.
Antes de desplegar, identifica productores y consumidores, incluidos trabajos en segundo plano, paneles, integraciones externas y versiones de cliente que sigan activas. Compara la especificación nueva con la anterior y somete los cambios incompatibles a revisión. Las pruebas de contrato pueden comprobar que el productor mantiene las respuestas acordadas y que los consumidores aceptan las variantes previstas.
Para cambios que requieren migración, un despliegue por etapas puede reducir la dependencia de una actualización simultánea: ampliar el esquema, preparar datos existentes cuando corresponda, cambiar lectores y escritores y retirar la forma anterior solo después de comprobar que ya no se usa. La retirada depende de observar a los consumidores, no de que el código nuevo esté desplegado.
En APIs de IA, la interfaz del proveedor y la identidad del modelo son conceptos relacionados, pero distintos. No debe suponerse que un identificador estable implica respuestas idénticas, ni que cambiar de modelo siempre exige una nueva ruta. Esas condiciones dependen del proveedor. La aplicación puede, en cambio, versionar su propio contrato y registrar qué configuración emplea, siempre que lo haga de forma compatible con la documentación y las obligaciones aplicables.
Evaluar un cambio de contrato
| Cambio | Riesgo que revisar | Acción práctica |
|---|---|---|
| Añadir un campo opcional | Clientes estrictos pueden rechazar campos desconocidos | Probar consumidores y mantener una conducta definida si el campo falta |
| Renombrar o eliminar un campo | Consumidores existentes pueden dejar de interpretar la respuesta | Ofrecer transición compatible o coordinar una versión nueva |
| Cambiar el significado de un valor | El sistema puede seguir funcionando con una interpretación incorrecta | No reutilizar el valor con otra semántica; documentar y migrar |
| Hacer obligatorio un campo | Peticiones antiguas pueden ser rechazadas | Comprobar adopción y acordar el cambio antes de exigirlo |
Gestionar errores, límites y tiempos de espera
Una integración debe decidir qué hacer cuando el servicio rechaza una petición, responde lentamente o no permite más solicitudes por el momento. La política concreta depende de los códigos y encabezados documentados por el proveedor. Si esa documentación no está confirmada para el servicio y la versión usados, los valores de límite y las señales de reintento deben mantenerse como configuración por verificar, no presentarse como hechos universales.
Los reintentos pueden ayudar ante fallos temporales, pero también pueden duplicar una operación, aumentar la carga o consumir cuota. Antes de repetir una petición, determina si es seguro hacerlo y si el servicio ofrece un mecanismo de idempotencia. Un timeout no confirma que la operación no haya ocurrido: el proveedor puede haber procesado la solicitud aunque la respuesta no llegara al cliente.
Los tiempos de espera deben corresponder al flujo. Una interacción que espera una respuesta inmediata necesita un límite distinto de un trabajo asíncrono de larga duración. Si la aplicación agota el tiempo, debe conservar información suficiente para decidir si consulta el estado, reintenta con seguridad o deriva el caso a recuperación. No conviene bloquear indefinidamente ni volver a enviar a ciegas una operación con efectos.
Un circuit breaker puede dejar de enviar temporalmente solicitudes a una dependencia que falla de forma repetida. Es un patrón de protección local, no una reparación del proveedor ni una garantía de disponibilidad. Debe definirse cómo se abre, cuándo vuelve a probar y qué recibe el usuario durante la interrupción. La lógica de reintento, el límite de concurrencia y el breaker deben coordinarse para no amplificar una caída.
Un fallback puede ser una respuesta previamente aprobada, una función determinista más limitada o una revisión manual. Cambiar automáticamente a otro modelo solo es apropiado si la política del producto permite esa sustitución y se entienden las diferencias de datos, comportamiento, coste y tratamiento. Una alternativa no es equivalente por defecto; la aplicación debe comunicar degradaciones relevantes y evitar aparentar una respuesta normal cuando el resultado procede de un camino distinto.
Respuesta operativa ante fallos
| Situación | Qué verificar | Respuesta de diseño |
|---|---|---|
| Entrada inválida | Qué regla local se incumple | Rechazar antes de llamar al proveedor y devolver un error controlado |
| Límite de consumo | Señales y política documentadas para el servicio concreto | Aplicar espera o cola según el contrato y evitar reintentos en ráfaga |
| Timeout | Si la operación pudo completarse y si es idempotente | Consultar estado, reintentar con seguridad o activar recuperación |
| Fallo temporal repetido | Patrón y duración de fallos observados | Limitar solicitudes y considerar un circuit breaker con recuperación definida |
| Respuesta con formato inesperado | Cambio de interfaz, truncamiento o incumplimiento del contrato | Validar, aislar y registrar el fallo sin propagar datos no conformes |
Probar la integración antes y después del despliegue
Una prueba de contrato comprueba que productores y consumidores respetan una interfaz acordada. Puede validar solicitudes y respuestas contra una especificación o registrar las interacciones concretas de un consumidor y comprobarlas frente al proveedor. Estas pruebas reducen el riesgo de divergencia entre contrato e implementación, pero no cubren todas las condiciones de producción.
Los dobles de prueba permiten simular respuestas, errores, demoras y límites sin depender de que el proveedor genere esas condiciones a voluntad. Deben representar tanto el camino normal como las situaciones que pueden dejar el proceso en un estado ambiguo. Una prueba que solo comprueba que el endpoint responde con éxito no evalúa la recuperación.
Incluye pruebas de autorización, repetición de peticiones, campos desconocidos, fallos de parseo y concurrencia cuando sean pertinentes. Para operaciones mutativas, comprueba explícitamente qué ocurre si se pierde la respuesta después de que el servidor haya podido procesarla. Para resultados probabilísticos, prueba la validación y las reglas de negocio por separado, sin tratar una muestra de respuestas como prueba exhaustiva.
La carga de prueba debe parecerse al patrón de uso esperado y respetar las condiciones del servicio. No uses pruebas de carga para inferir límites o garantías que la documentación no declara. Comprueba latencia, errores, consumo de recursos y acumulación de trabajos, con el volumen y el entorno adecuados. Una prueba de carga caracteriza una configuración y unas condiciones concretas, no demuestra rendimiento universal.
Después del despliegue, la telemetría debe ayudar a localizar dónde falla la cadena: aplicación, red o servicio externo. Registra identificadores de correlación, duración, categoría de error y versión de contrato cuando sea seguro hacerlo. No registres prompts, respuestas completas, credenciales o datos personales por defecto; cualquier registro de contenido necesita una justificación y controles apropiados.
Ciclo de prueba y operación
- 01Describe la operación, sus consumidores y el resultado que el producto necesita.
- 02Define el esquema de petición, respuesta y errores con límites aplicables al servicio concreto.
- 03Valida entradas antes de llamar y valida respuestas antes de propagarlas.
- 04Prueba cambios compatibles e incompatibles frente a los consumidores que siguen activos.
- 05Simula límites, timeouts, respuestas inválidas, repetición de peticiones y recuperación.
- 06Despliega con monitorización, límites de concurrencia y una forma definida de detener o revertir el cambio.
Lista práctica para revisar una integración existente
Una revisión útil comienza por una operación concreta, no por una auditoría abstracta de toda la plataforma. Sigue el recorrido desde la entrada hasta el efecto final: quién aporta los datos, qué se envía, qué devuelve el proveedor, qué componente interpreta la respuesta y qué ocurre si el flujo se interrumpe. Así se distinguen los errores de transporte de los errores de contrato y de las decisiones de negocio.
Confirma que el esquema refleja la documentación vigente del servicio usado y que identifica el alcance aplicable: versión, configuración, entorno y, cuando corresponda, mercado o modalidad. Si el proveedor no documenta un comportamiento necesario, la integración debe manejar esa incertidumbre explícitamente. No conviertas una expectativa local en una promesa atribuida al proveedor.
Comprueba que cada campo tenga una finalidad, una regla de validación y una conducta ante ausencia o valor inesperado. Revisa si los cambios de contrato se comparan automáticamente y si existe una política para deprecar campos. Asegúrate de que los consumidores toleran cambios solo cuando esa tolerancia forma parte de su diseño.
Prueba también la capacidad operativa: límites de concurrencia, expiración de credenciales, revocación, alertas, recuperación de solicitudes ambiguas y gestión de tareas pendientes. La guía técnica institucional sobre integración de APIs destaca la importancia de la documentación, las versiones, la autenticación y la posibilidad de probar operaciones; esos elementos ayudan a descubrir cómo usar una interfaz, pero no sustituyen las decisiones de resiliencia propias de cada aplicación.
Por último, clasifica las garantías que realmente ofrece el sistema. Una validación local puede ser determinista para una regla codificada; un mecanismo probabilístico produce resultados variables; una prueba demuestra solo lo que ejecutó bajo sus condiciones. Mantener esas categorías separadas mejora las decisiones de lanzamiento y evita confundir una configuración prudente con una garantía de exactitud, seguridad o disponibilidad.
Checklist de revisión
| Pregunta | Señal de control |
|---|---|
| ¿La interfaz está descrita para el servicio y la versión realmente usados? | La especificación y las condiciones aplicables están identificadas |
| ¿Se validan tanto petición como respuesta? | Hay comprobaciones estructurales y reglas de dominio separadas |
| ¿Se clasifican los errores y se limita la repetición? | Los reintentos no son indiscriminados y contemplan operaciones ambiguas |
| ¿Se comprueban cambios incompatibles? | La comparación de contratos y las pruebas cubren consumidores activos |
| ¿Hay una ruta de recuperación cuando el proveedor falla? | La alternativa está definida, es observable y no aparenta equivalencia sin confirmarla |
| ¿La telemetría protege los datos? | Se registran señales operativas sin exponer contenido sensible innecesario |
Continúa explorando
Fuentes consultadas
Correcciones y transparencia
Si detectas un dato incorrecto o desactualizado, puedes enviarnos una corrección indicando la página y la fuente que debemos revisar.
Proponer una corrección