Cobertura de una API: cómo comunicar fuentes caídas y resultados parciales
Una integración de infracciones necesita informar qué fuentes respondió, cuáles fallaron y si el resultado es completo. Un cero sin cobertura comprobada puede inducir decisiones incorrectas.
Por Marco Ferreiro ·
Una API puede haber consultado correctamente cuatro organismos y no obtener respuesta del quinto. Si devuelve sólo las actas encontradas, sin explicar el hueco, el cliente no sabe si recibió una respuesta completa. Si devuelve cero, el problema es peor: convierte una falla técnica en una conclusión de negocio.
La cobertura no es un dato accesorio. Es parte del resultado.
Definí primero qué fuentes eran esperables
Antes de ejecutar una consulta, el sistema necesita una lista versionada de fuentes aplicables. Esa lista puede depender del tipo de identificador, del producto contratado o de reglas territoriales. No debería depender de qué integraciones estaban disponibles ese minuto: una caída no puede borrar a la fuente del denominador.
Para cada fuente conviene registrar un estado como:
completed, cuando hubo una respuesta interpretable, con o sin actas;timeout, cuando agotó el presupuesto de espera;failed, cuando la respuesta fue inválida o ocurrió otro error;not_applicable, cuando una regla previa y documentada excluyó esa fuente;pending, mientras la operación todavía no terminó.
El estado global puede ser complete, partial o failed. Los nombres son menos importantes que su definición inequívoca.
Separá actas, cobertura y problemas
Una respuesta útil tiene tres capas. La primera contiene resultados normalizados con su procedencia. La segunda resume las fuentes esperadas, completadas y faltantes. La tercera describe problemas accionables.
RFC 9457 ofrece un formato estándar para representar problemas HTTP con campos como tipo, título, estado, detalle e instancia. La especificación también advierte que esos detalles no son un volcado de depuración. Un cliente necesita saber qué puede hacer; no necesita conocer la topología interna ni recibir un stack trace.
Si la operación agrega varios orígenes, el error de uno puede formar parte del recurso de consulta, en vez de anular resultados válidos de los demás. El contrato debe documentar esa decisión y mantener coherencia entre el código HTTP y el cuerpo. RFC 9110 proporciona la semántica de estados como 503 y 504, pero no sustituye el modelo de cobertura del dominio.
No uses una lista vacía como comodín
Hay al menos tres situaciones diferentes:
- todas las fuentes aplicables respondieron y no informaron actas;
- algunas respondieron sin actas y otras fallaron;
- ninguna produjo una respuesta interpretable.
Las tres pueden tener results: [], pero no significan lo mismo. El consumidor debería poder resolver la diferencia sin analizar textos libres. Por ejemplo, una interfaz podría traducir el segundo caso como: “No se informaron infracciones en las fuentes completadas; quedó una fuente sin verificar”.
Ese mensaje evita dos errores operativos: habilitar una acción que exigía cobertura completa o desechar una consulta que todavía puede completarse.
Documentá respuestas conocidas
OpenAPI exige describir al menos una respuesta para cada operación y permite documentar tanto códigos específicos como una respuesta predeterminada. En una API de cobertura variable conviene incluir ejemplos de:
- consulta completa con resultados;
- consulta completa sin resultados;
- consulta parcial con resultados;
- consulta parcial vacía;
- solicitud inválida;
- indisponibilidad total.
Los ejemplos deben ser sintéticos y no contener patentes ni actas reales. Además del esquema, documentá invariantes: qué hace que una consulta sea completa, si habrá reintento y durante cuánto tiempo puede cambiar el estado.
Reintentá conservando la misma consulta
Un reintento técnico no debería crear otra decisión de negocio. Conservá un identificador de consulta, registrá intentos por fuente y actualizá el estado cuando llegue evidencia nueva. Si una acta ya había sido entregada, no dispares otra alerta sólo porque la fuente fue consultada nuevamente.
La política debería fijar un máximo, espera creciente y variación aleatoria. Si la fuente indica Retry-After, evaluá ese dato según el contrato y la semántica HTTP. Cuando se agota la política, el resultado permanece parcial; no se convierte en completo por el paso del tiempo.
Diseñá para personas y para máquinas
El código estable sirve para automatizar. El texto claro sirve para quien opera la flota. Ambos deberían responder:
- qué parte se verificó;
- qué parte falta;
- si los resultados encontrados siguen siendo válidos;
- cuál es la próxima acción disponible;
- cuándo se obtuvo cada respuesta.
Una pantalla puede permitir reintentar o suscribirse a una actualización. Un proceso automático puede frenar una venta, abrir una tarea o continuar con una advertencia según su política interna.
Minimizá datos y exposición
La Ley 25.326 exige que los datos sean adecuados, pertinentes, no excesivos, exactos y seguros. Aplicado a una integración, eso implica no copiar cuerpos crudos “por las dudas”, definir retención, proteger logs y limitar quién ve identificadores personales.
La cobertura puede auditarse con códigos, marcas de tiempo y referencias opacas. Las credenciales, las respuestas completas de terceros y los datos no necesarios deben quedar fuera del DTO público.
Una API confiable no promete que cada fuente estará siempre disponible. Promete algo más verificable: nunca confundir una caída con ausencia de infracciones y explicar con precisión qué parte de la consulta pudo completar.
Metodología
- Alcance
- Patrón de contrato para APIs que agregan respuestas de varias fuentes de infracciones con disponibilidad independiente.
- Unidad de análisis
- Una consulta lógica, sus resultados normalizados y un estado terminal independiente por cada fuente prevista.
- Cobertura
- Semántica HTTP, documentación OpenAPI, errores estructurados y obligaciones generales de calidad y seguridad de datos.
Limitaciones
- No define los acuerdos de nivel de servicio ni códigos internos de un proveedor particular.
- La aplicabilidad de una fuente debe surgir de reglas de cobertura versionadas, no de una suposición del consumidor.
Fuentes
- RFC 9457 — Problem Details for HTTP APIs — RFC Editor (consultada el )
- RFC 9110 — HTTP Semantics — RFC Editor (consultada el )
- OpenAPI Specification 3.1.2 — OpenAPI Initiative (consultada el )
- Ley 25.326 de Protección de los Datos Personales — Argentina.gob.ar (consultada el )
Preguntas frecuentes
¿Una API debería devolver 200 cuando el resultado es parcial?
Puede hacerlo si el contrato representa explícitamente la consulta y sus estados por fuente; también puede usar otros patrones documentados. Lo imprescindible es que el código HTTP, el cuerpo y la semántica no se contradigan.
¿Una lista vacía puede significar que una fuente tuvo una caída?
No debería. Una lista vacía describe ausencia de elementos dentro de una respuesta válida; una fuente caída necesita un estado distinto, con cobertura parcial y una acción de reintento o revisión.
¿Qué información de error conviene exponer al cliente?
Un código estable, la fuente lógica afectada, el estado y una orientación operativa. No deberían exponerse stack traces, credenciales, URLs internas ni cuerpos crudos del proveedor.
Notas relacionadas
Timeout no significa “sin multas”: cómo informar resultados parciales en una integración
Cuando una fuente no responde, el resultado es parcial o indeterminado, nunca cero. Un contrato explícito permite reintentar, alertar y decidir sin producir falsos negativos.
Build vs buy para consultar infracciones de una flota
Construir integra control y costos de mantenimiento; comprar acelera cobertura pero agrega dependencia. La decisión mejora cuando se evalúa evidencia, seguridad, salida y resultados parciales.
Polling de consultas sin saturar la API: Retry-After, ETag y espera con jitter
Consultar el estado cada segundo no hace que una búsqueda termine antes. Un contrato con Retry-After, ETag y una espera aleatoria reduce solicitudes repetidas, bytes y picos de clientes sincronizados.