Frescura mínima de un dato de multas por contrato

Un contrato de integración suele ser preciso con la disponibilidad y los tiempos de respuesta. Sobre las multas aparece, en cambio, una fórmula vaga: “información actualizada”. Esa frase no se puede auditar, y cada parte la firma entendiendo otra cosa.

Llamamos frescura mínima a la antigüedad máxima que una integración acepta para la observación que respalda cada acta. Es una cláusula, no una sensación: dice cuánto puede haber pasado entre el momento en que miramos la fuente y el momento en que entregamos el resultado, y qué hacer si ese límite no se sostiene.

Negociarla exige tres definiciones previas: qué se mide, sobre qué unidad y con qué evidencia. Sin las tres, el número acordado es decorativo.

La frescura del dato no es la de la respuesta

HTTP ya tiene un concepto formal de frescura. RFC 9111 define la vida útil de una respuesta almacenada y su edad: mientras la edad sea menor que esa vida útil, la respuesta es fresca, y el campo Age estima cuánto lleva guardada. RFC 9110 define Date como el momento en que se originó el mensaje.

Todo eso describe el mensaje, no el momento en que consultamos el portal. Una respuesta puede generarse recién y transportar una observación de ayer, porque se calculó sobre un escaneo anterior. Ese malentendido está desarrollado en respuesta reutilizada o consulta fresca.

Por eso la cláusula se apoya en un dato del cuerpo y no en cabeceras de transporte: una marca de observación por jurisdicción, con desplazamiento horario explícito, como describe RFC 3339. Con esa marca el cliente calcula la antigüedad por su cuenta.

La unidad: un resultado vale lo que su fuente más vieja

Una consulta puede combinar varias jurisdicciones. Si tres responden en el momento y una fue observada hace horas, hay que definir la frescura del conjunto.

La regla conservadora es tomar la peor: la del componente más antiguo. Promediar produce un número que ninguna decisión puede usar, porque diluye la fuente atrasada. De ahí que el compromiso se escriba por jurisdicción y no por endpoint:

• cada ítem lleva la marca de observación de la fuente que lo originó;
• cada fuente consultada aparece en la respuesta aunque no haya devuelto nada;
• el resumen agregado, si existe, declara la más antigua de esas marcas.

Lo que se firma no es un número solo

Un compromiso verificable tiene cuatro partes:

• el objetivo, como antigüedad máxima aceptada por fuente y por tipo de consulta;
• la ventana de evaluación, porque una promesa llamada por llamada no sobrevive al primer corte ajeno;
• las exclusiones, como mantenimiento anunciado de la fuente o límites de cuota del propio cliente;
• la conducta ante el incumplimiento, es decir qué se entrega cuando el dato es más viejo que lo pactado.

La última suele faltar y es la que más cambia el comportamiento del sistema. Hay dos conductas razonables y opuestas: entregar igual el dato viejo, marcado como tal, o negarse a responder para esa fuente. Un tablero interno suele preferir la primera; un proceso que bloquea la entrega de un vehículo, la segunda. La API debería permitir elegir.

Hay además un techo que ninguna cláusula supera: no se puede prometer más frescura que la frecuencia con la que la fuente publica cambios. Si una jurisdicción actualiza una vez por día, consultarla cada diez minutos no vuelve más nuevo el dato, sino la observación. Distinguir esos relojes es el trabajo previo, y lo tratamos en los tres relojes de una integración.

Pedirla en la solicitud es una preferencia

Del lado del cliente aparece la tentación de resolverlo con una cabecera. RFC 9111 prevé directivas de solicitud parecidas: una pide que la respuesta siga fresca al menos cierto tiempo, otra declara cuánta caducidad se tolera. RFC 7240 define un mecanismo general de preferencias y una cabecera que declara cuáles se aplicaron.

Son señales útiles, pero comparten una propiedad decisiva: el servidor puede no atenderlas. Una preferencia expresa lo que el cliente quiere; el contrato define a qué se obliga el proveedor. Conviene que ambos usen el mismo criterio y que la respuesta declare siempre la frescura efectiva.

Cómo se audita sin creerle a nadie

El compromiso se verifica del lado del cliente, con datos que ya recibe: para cada respuesta, la diferencia entre su hora y la marca de observación más antigua que transporta. Ese valor se guarda junto al identificador de la consulta y de la jurisdicción.

Con ese registro la discusión deja de ser sobre percepciones: se ve qué jurisdicciones concentran el atraso y si los desvíos caen dentro de ventanas de mantenimiento declaradas.

Antes de firmar, verificá tres cosas: que cada ítem traiga su marca de observación con zona horaria, que la respuesta liste las jurisdicciones consultadas y no sólo las que devolvieron algo, y que exista una forma de pedir el dato fresco o ninguno. Una cláusula que no se mide no se cumple ni se incumple: se discute.

Preguntas frecuentes

¿Frescura mínima y disponibilidad son el mismo compromiso?

No. La disponibilidad describe si el servicio responde; la frescura describe qué tan vieja es la observación que respalda lo que devuelve. Un servicio puede responder siempre y entregar datos atrasados, o estar caído justo cuando la fuente publicó un cambio. Conviene medirlas y pactarlas por separado.

¿El header Age alcanza para medir la frescura del dato?

No. RFC 9111 cuenta esa edad desde que el servidor de origen generó o revalidó la respuesta, no desde que se consultó la fuente que produjo el dato. Una respuesta recién generada puede transportar una observación anterior. La antigüedad que importa en el contrato se calcula con una marca de tiempo de observación incluida en el cuerpo.

¿Se puede pedir la frescura deseada en la propia solicitud?

Sí, y conviene que el parámetro use el mismo criterio que la cláusula. Pero un pedido en la solicitud es una preferencia que el servidor puede no atender. Lo que obliga es el contrato, y sólo si la respuesta declara qué frescura efectiva entregó.

¿Qué corresponde hacer si una jurisdicción está caída y el dato queda viejo?

Depende de la conducta que se haya pactado. Hay dos opciones razonables y opuestas: entregar el dato disponible marcado como más antiguo que lo acordado, o negarse a responder para esa fuente. La API debería permitir elegir según el uso, y en ambos casos identificar qué fuente quedó atrasada.

Notas relacionadas