Versionamento

A versão vai no caminho:

/api/integrations/v1/{company}/...

A v1 só cresce por adição

É um compromisso, não uma intenção. Dentro da v1:

Pode acontecer

• Campos novos nas respostas
• Parâmetros novos, sempre opcionais
• Pontos novos
• Valores novos em campos que já eram listas de valores possíveis
• Códigos de erro novos, em situações que antes respondiam de forma mais genérica
• Mensagens de erro reescritas — o Code é que não muda

Não acontece

• Remover um campo de uma resposta
• Mudar o nome de um campo
• Mudar o tipo ou o significado de um campo
• Tornar obrigatório um parâmetro que era opcional
• Mudar o significado de um código de erro
• Mudar um caminho

Se alguma dessas mudanças alguma vez for inevitável, nasce uma v2 e a v1 mantém-se a funcionar durante um período acordado. Não muda por baixo dos pés de ninguém.

O que isto lhe pede

Ignore o que não conhece. Um campo novo numa resposta não pode partir o seu código. Muitos desserializadores falham perante campos desconhecidos por predefinição — desligue isso.

//C#
JsonSerializerOptions options = new() { PropertyNameCaseInsensitive = true };
//System.Text.Json ignora campos desconhecidos por predefinição

# Python: aceda por chave em vez de exigir a forma exata
occurrence.get("newField")

Não dependa da ordem dos campos de um objeto JSON, nem do número de campos.

Trate listas de valores como abertas. Estados, prioridades e tipos vêm das tabelas de referência de cada empresa e podem ganhar entradas. Um switch exaustivo sobre valores conhecidos parte-se quando o cliente cria um estado novo — tenha sempre um caminho por omissão.

As tabelas de referência são do cliente

Estados, prioridades, naturezas e tipos de serviço são configurados por cada empresa e podem ser renomeados. Compare sempre por identificador, nunca pela descrição. Ver o ponto /reference.

Versões anteriores

Os pontos anteriores à v1 continuam a funcionar e não estão a ser desligados. Não recebem funcionalidades novas.

Se está a integrar de novo, use a v1. Se já integra pelos pontos antigos, a migração é recomendada mas não urgente — e quando for planeada, será com aviso e prazo acordados, nunca por corte.

Saber que versão está a falar

O ping devolve ApiVersion. Vale a pena registá-lo no arranque: numa chamada de suporte, poupa a primeira meia hora.