Versionamento
Como o /v1 evolui, o que conta como breaking change, e como se retira um path.
Tudo pendura em /v1. Esse prefixo é o contrato: um cliente escrito contra os endpoints de hoje continua funcionando sem reescrita.
O que pode mudar em /v1
Mudanças aditivas entram aqui. Um endpoint novo, um campo opcional novo, um code de erro novo. Os campos que já existem conservam o significado, os obrigatórios seguem obrigatórios, e um cliente que ignora o que não conhece continua funcionando.
O que não acontece em /v1
Um breaking change ganha um prefixo novo (/v2), não uma reescrita silenciosa de /v1. Breaking é: remover ou renomear um campo, mudar um tipo, tornar obrigatório um campo que era opcional, ou mudar o significado de um code.
Hoje não há /v2. Quando houver, /v1 permanece o tempo suficiente para migrar, e os dois prefixos são documentados juntos.
Depreciação
Hoje não há nada depreciado.
Quando um path ou um campo for sair:
- Fica marcado no spec OpenAPI (
deprecated: true). - Diz-se nesta página, com o substituto.
- As respostas que ainda servem o path antigo enviam um header
Sunset(uma data HTTP), para que um cliente veja o prazo sem ler a documentação.
Até isso acontecer, não trate /v1 como instável. Crescer por adição é o ponto do prefixo.
As chaves não são versionadas
Uma chave de API da organização funciona no prefixo vigente. Não se emite uma chave nova para continuar usando /v1, e uma chave não está presa a uma versão.
Limites de volume
Quanto você pode pedir, como é um 429, e como esperar.
Push a lead POST
Creates the person (or reuses them, matched by phone or email) and their enquiry, in one call. Idempotent per `externalId` within your organization. A lead with a phone number and no conversation yet is what the automatic first contact reacts to: if the organization has it enabled, the approved template goes out on its own.