Versões e descontinuações

Esta política aplica-se a toda a API de integração: REST API v1, widget, webhooks de saída e de entrada, SCIM 2.0. As chamadas internas usadas pelos portais Core, Workspace e Desk não estão cobertas e podem mudar a qualquer momento: não as uses nas integrações.

Versões principais

• A versão principal está no caminho: /api/v1/…. Todas as respostas de /api/v1 contêm X-Exo-API-Version: 1.
• A v1 é estável. Dentro da v1 só fazemos alterações compatíveis:
  • novos endpoints, novos campos opcionais nos pedidos, novos parâmetros de consulta;
  • novos campos nas respostas: o teu cliente deve ignorar os que não conhece;
  • novos tipos de evento de webhook: o teu sistema deve ignorar os que não conhece;
  • novos códigos de erro: trata os desconhecidos com base no estado HTTP;
  • novos cabeçalhos opcionais.
• Uma alteração incompatível exige uma nova versão principal (/api/v2). É incompatível remover ou renomear um campo, um endpoint ou um evento, mudar um tipo, tornar obrigatório um campo opcional ou mudar a autenticação.
• Quando sai uma nova versão principal, a anterior continua disponível durante pelo menos 12 meses.

Descontinuações

• Uma funcionalidade descontinuada continua a funcionar durante pelo menos 6 meses a partir do anúncio.
• As respostas que usam uma funcionalidade descontinuada contêm:
  • Deprecation: @<unix-seconds>: quando foi anunciada a descontinuação (RFC 9745);
  • Sunset: <HTTP-date>: quando a funcionalidade deixará de funcionar (RFC 8594);
  • Link: <url>; rel="deprecation": o guia de migração.
• Cada descontinuação está no changelog e está marcada como deprecated na especificação OpenAPI.

Descontinuações em curso

Funcionalidade	Anunciada	Deixa de funcionar	O que usar
Chaves de API nh_…	1 de novembro de 2026	30 de junho de 2027	Chaves nhk.<keyid>.<secret>
Assinatura X-NH-Signature nos webhooks de saída	1 de novembro de 2026	30 de junho de 2027	X-Exo-Signature com X-Exo-Timestamp
Assinatura X-NH-Connector-Signature nos webhooks de entrada	1 de novembro de 2026	30 de junho de 2027	X-Exo-Signature com X-Exo-Timestamp
Campos event, timestamp, source no corpo dos webhooks	1 de novembro de 2026	30 de junho de 2027	type, created_at, data

Especificação e changelog

• A especificação OpenAPI é o contrato. A sua versão segue o semantic versioning 1.MINOR.PATCH: o MINOR aumenta com as adições compatíveis e o PATCH apenas com as correções de documentação.
• Cada alteração à API atualiza a versão da especificação e acrescenta uma entrada ao changelog.