Versionamento

A Public API segue versionamento por URL — toda chamada inclui /api/v1/ no path. A versão é parte do contrato: enquanto você usa v1, garantimos compatibilidade.

Política de breaking changes

Mudanças que quebram consumidores (remover campos, renomear endpoints, mudar tipos) só acontecem em major versions novas (v2, v3).

v1 será mantida em paralelo por mínimo 12 meses após o lançamento de uma versão nova, com:

• Aviso prévio de 6 meses no changelog e e-mail pra admins
• Header Deprecation + Sunset nas respostas durante o período de transição
• Guia de migração documentado (campos novos, campos removidos, exemplos de antes/depois)

O que NÃO é breaking change

Essas mudanças são não-breaking e podem acontecer dentro de v1 sem aviso:

• Adicionar novos campos em responses (seu cliente deve ignorar campos desconhecidos)
• Adicionar novos endpoints
• Adicionar novos query params opcionais
• Adicionar novos valores em enums (ex: novo tipo de atividade)
• Adicionar novos scopes
• Tornar campos opcionais que antes eram obrigatórios (request relaxado)
• Mudar mensagens humanas (message em erros)
• Melhorar performance, mudar internals

O que É breaking change

Essas exigem v2:

• Remover ou renomear campos em responses
• Remover endpoints
• Mudar tipo de um campo (string → number, etc.)
• Tornar campos obrigatórios que eram opcionais
• Remover valores de enum
• Mudar códigos de erro (error field)
• Mudar shape de respostas (ex: trocar array por { data, pagination } sem fallback)

Como saber se vai mudar

1. Changelog público: github.com/indutiva/indutivacrm/blob/main/CHANGELOG.md
2. Header de resposta: quando um endpoint estiver deprecated, todas as respostas incluem:

   Deprecation: true
   Sunset: Wed, 22 May 2027 00:00:00 GMT
   Link: <https://developers.indutivacrm.com.br/migration/v2-contacts>; rel="successor-version"

3. E-mail pros admins do tenant 6 meses antes do sunset

Convenção semver dos campos

Embora a API use versionamento por URL (não semver no path), internamente a gente trata:

• Patch (bugfix): correção de bug sem mudar contrato — sai sem aviso
• Minor (feature aditiva): novos endpoints/campos/params — anunciado no changelog
• Major (breaking): nova v* com sunset da anterior — anunciado com 6+ meses de antecedência

Tolerância no cliente

Boas práticas pra tornar sua integração robusta:

1. Ignore campos desconhecidos — não falhe se a resposta tem campos novos que você não esperava
2. Lide com enums novos — em vez de switch exaustivo, tenha um default que faz algo razoável
3. Não dependa da ordem dos campos em JSON
4. Não dependa de mensagens humanas — sempre switch no error field, nunca no message
5. Persista IDs como string — IDs são strings opacas (cuids), nunca trate como número