Versionamento

O que pode mudar na v1

Só mudanças aditivas: novas rotas, novos campos opcionais de requisição, novos campos de resposta, novos valores de enum nas respostas, novos motivos de erro, novos eventos de webhook e campos de payload. Escreva clientes que ignoram campos desconhecidos e toleram valores de enum desconhecidos.

Uma mudança incompatível é uma nova versão maior (/v2) servida ao lado da v1.

Descontinuação

Uma rota ou campo pode ser descontinuado, nunca alterado no lugar. Desde o dia da descontinuação, toda resposta que o toca traz Deprecation: @<unix seconds> (RFC 9745), Sunset: <HTTP date> (RFC 8594) e um Link para a entrada dele no changelog com rel="deprecation". Ele continua funcionando por pelo menos 365 dias depois disso.

Registre ou alerte sobre o cabeçalho Deprecation e você saberá de cada descontinuação muito antes de ela importar. Todas estão listadas no changelog.

Payloads de webhook

Os payloads de webhook são versionados por data (hoje 2026-09-01). Cada endpoint mantém a versão de payload com que foi criado, então uma futura mudança incompatível em um payload só alcança os endpoints que optarem por ela.