Política de versionado

• La versión es una fecha, la actual es 2026-10-01, y viaja en la cabecera Nouron-Version.
• Al crear una llave se le fija una versión. Si la petición no manda la cabecera, se usa la de la llave: un agente que no se toca no se rompe por una actualización.
• Si mandas una versión que existe, vale solo para esa petición. Si mandas una que no existe, la respuesta es 400 unsupported_version.
• Toda respuesta lleva Nouron-Version (la que de verdad se usó) y Request-Id.

• Agregar un campo opcional a una respuesta o a una petición.
• Agregar un endpoint o un método nuevo.
• Agregar un tipo de evento (los destinos de webhook solo reciben los que pidieron).
• Agregar un código de error nuevo.
• Agregar un valor a una enumeración abierta (x-open-enum: true en openapi.json).
• Agregar un parámetro opcional.

• Quitar o renombrar un campo, un endpoint o un parámetro.
• Cambiar el tipo de un campo.
• Hacer obligatorio un campo o un parámetro que antes no lo era.
• Agregar un valor a una enumeración cerrada, como el estado de un pago.
• Quitar un valor de cualquier enumeración.
• Volver cerrada una enumeración abierta.
• Cambiar el significado de un estado o de un motivo.
• Cambiar la descripción o los argumentos de una herramienta MCP.

• Todo cambio compatible se anota en la sección «Historial de cambios» de la página de versionado.
• Un cambio que rompe sale como una versión nueva con fecha (Nouron-Version: AAAA-MM-DD); la anterior sigue funcionando.
• Cada llave queda fijada a una versión: un agente que no se toca no se rompe por una actualización.
• Antes de retirar una versión se avisa a los dueños con anticipación; el plazo se publica con la primera versión nueva.

Cinco listas pueden crecer sin cambiar la versión. En openapi.json llevan x-open-enum: true. Las listas de estados que tu código maneja con switch, como el estado de un pago, siguen cerradas.

Cómo tolerar un valor desconocido

Usa siempre una rama por defecto. Nunca fuerces que el switch sea exhaustivo sobre estas listas.

function onEvent(event: { id: string; type: string }) {
  switch (event.type) {
    case 'spend.settled':
      return markPaid(event);
    default:
      // Tipo que no conoces: ignóralo y responde 2xx.
      return;
  }
}

El recibo firmado lleva su propia versión. La 1 siempre dice x402 en payment.rail; la 2 deja el riel abierto. Un recibo de la versión 1 se sigue verificando igual: el verificador recalcula la cadena con la receta publicada, no decide por la versión.

• 2026-10-12. Compatible. Se abrieron las listas de códigos y tipos de error, tipos de evento, acciones siguientes y acciones de auditoría (x-open-enum). Se definieron los códigos capability_unavailable, verification_required, account_on_hold y partner_unavailable, que todavía no se devuelven. Se agregó la versión 2 del recibo. Se unificó el texto de missing_api_key (<api_key>).
• 2026-10-01. Versión inicial de la API v1.