Política de versionamento

• A versão é uma data, a atual é 2026-10-01, e viaja no cabeçalho Nouron-Version.
• Ao criar uma chave, uma versão é fixada nela. Se a requisição não mandar o cabeçalho, usa-se a da chave: um agente que não é alterado não quebra por uma atualização.
• Se você mandar uma versão que existe, vale só para essa requisição. Se mandar uma que não existe, a resposta é 400 unsupported_version.
• Toda resposta traz Nouron-Version (a que realmente foi usada) e Request-Id.

• Adicionar um campo opcional a uma resposta ou a uma requisição.
• Adicionar um endpoint ou método novo.
• Adicionar um tipo de evento (os destinos de webhook só recebem os que pediram).
• Adicionar um código de erro novo.
• Adicionar um valor a uma enumeração aberta (x-open-enum: true em openapi.json).
• Adicionar um parâmetro opcional.

• Remover ou renomear um campo, um endpoint ou um parâmetro.
• Mudar o tipo de um campo.
• Tornar obrigatório um campo ou parâmetro que antes não era.
• Adicionar um valor a uma enumeração fechada, como o estado de um pagamento.
• Remover um valor de qualquer enumeração.
• Tornar fechada uma enumeração aberta.
• Mudar o significado de um estado ou de um motivo.
• Mudar a descrição ou os argumentos de uma ferramenta MCP.

• Toda mudança compatível é registrada na seção «Histórico de mudanças» da página de versionamento.
• Uma mudança que quebra sai como uma versão nova com data (Nouron-Version: AAAA-MM-DD); a anterior continua funcionando.
• Cada chave fica fixada a uma versão: um agente que não é alterado não quebra por uma atualização.
• Antes de aposentar uma versão, os donos são avisados com antecedência; o prazo é publicado com a primeira versão nova.

Cinco listas podem crescer sem mudar a versão. No openapi.json elas levam x-open-enum: true. As listas de estados que seu código trata com switch, como o estado de um pagamento, continuam fechadas.

Como tolerar um valor desconhecido

Use sempre um ramo padrão. Nunca force o switch a ser exaustivo 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;
  }
}

O recibo assinado leva a própria versão. A 1 sempre diz x402 em payment.rail; a 2 deixa o trilho aberto. Um recibo da versão 1 continua sendo verificado igual: o verificador recalcula a cadeia com a receita publicada, não decide pela versão.

• 2026-10-12. Compatível. Foram abertas as listas de códigos e tipos de erro, tipos de evento, ações seguintes e ações de auditoria (x-open-enum). Foram definidos os códigos capability_unavailable, verification_required, account_on_hold e partner_unavailable, que ainda não são devolvidos. Foi adicionada a versão 2 do recibo. O texto de missing_api_key foi unificado (<api_key>).
• 2026-10-01. Versão inicial da API v1.