Saltar al contenido
TrackJet

tjvt2 · especificación

Cronología verificable de TrackJet

Un sello a prueba de manipulación para los historiales de eventos de envío. Cada evento se hashea en una cadena SHA-256 solo-añadir en el momento en que se registra; cualquier edición, reordenación o borrado posterior de eventos pasados rompe la verificación. Comprueba cualquier cadena rastreada en /verify.

Construcción

h(0) = SHA256( "<spec>:" || shipment_uuid || ":" || primary_tracking )
h(n) = SHA256( h(n-1) || canonical(event_n) )          n = 1..N

canonical(event) es JSON determinista con este orden exacto de claves, sin espacios insignificantes, con UTF-8 y barras sin escapar:

{"v":"tjvt2","seq":<n>,"leg_order":<int>,"occurred_at":"<RFC3339>",
 "status":"<string>","description":"<string>","location":<string|null>,
 "country_code":<string|null>,"provenance":"sourced|estimated|declared"}

Los eventos se ordenan por (occurred_at, leg_order, índice de ingesta) — el mismo orden estable que renderiza la UI de la cronología. seq liga cada evento a su posición, así que intercambiar dos eventos por lo demás idénticos también rompe la cadena.

tjvt2 (actual, desde el 27-07-2026) añade provenance como última clave — la clase de un evento (sourced / estimated / declared) queda sellada y ya no se puede cambiar a posteriori. tjvt1 (desde el 10-06-2026) es idéntica sin esa clave y sigue siendo verificable para siempre: la versión de spec se guarda por sello en la base de datos, no en el código en ejecución. Una cadena nacida bajo tjvt1 conserva su génesis tjvt1 aunque los eventos posteriores se sellen bajo tjvt2.

Qué prueba un resultado válido — y qué no

  • Prueba: el historial de eventos almacenado hoy es byte-idéntico a lo que TrackJet registró al ingerirlo — nada se editó, reordenó ni borró después.
  • No prueba: que los datos originales del transportista fueran correctos. El sello cubre el registro de TrackJet desde el momento de la ingesta, no la realidad anterior.
  • Los sellos se escriben tras el commit de la base de datos, solo-añadir. Los eventos que llegaron hace segundos pueden estar brevemente sin sellar («cola sin sellar») — se informa como tal, no como manipulación.
  • El verificador y la API de prueba exponen solo metadatos de integridad (validez, recuentos, digests) — nunca el contenido de los eventos.

Acceso programático

  • GET /api/v1/shipments/{uuid}/proof — lista de sellos (solo hashes) + veredicto de verificación (requiere clave API; ver doc de la API).
  • Servidor MCP verify_timeline — el mismo veredicto para agentes de IA (doc de MCP).

Versión de spec actual tjvt2 · función hash SHA-256 · tjvt1 publicada el 2026-06-10, tjvt2 el 2026-07-27. Los cambios en la forma canónica incrementan el prefijo de versión; los sellos existentes siguen siendo verificables bajo su versión original.