Versionamento e descontinuação da API

Pedimos que você aponte os seus próprios scripts, integrações e bibliotecas cliente do Zendesk para o HelpFalcon. Esta página é a promessa que vem com isso: o que podemos mudar, o que não podemos e com quanta antecedência você é avisado. Ela cobre a API REST em /api, a API compatível com Zendesk em /zd/api/v2 e o contrato dos webhooks. Toda mudança entra no registro de mudanças da API.

A versão curta

Aviso antes de qualquer remoção	12 meses
Versionamento da API REST	Nenhum na URL: /api só cresce
Número de versão	info.version em openapi.json, semântico
API compatível com Zendesk	Congelada nos formatos documentados do Zendesk
Webhooks	Inteiro version no payload, fixado por webhook
Como uma descontinuação é anunciada	Registro de mudanças, cabeçalhos Deprecation e Sunset, deprecated no documento OpenAPI, e-mail

Uma API REST viva, só aditiva

/api não tem versão na URL e não terá. Em vez disso, nós a ampliamos:

• novos endpoints,
• novos parâmetros opcionais de consulta e de corpo,
• novos campos nas respostas.

Escreva o seu cliente para ignorar campos que ele não conhece, e campos novos nunca serão um problema. Em troca, nunca removemos um campo, nunca mudamos o tipo de um campo no lugar e nunca tornamos obrigatório um parâmetro existente.

A versão que você pode citar num relatório de bug é info.version no documento OpenAPI. Ela é semântica: o número de patch sobe com correções, o menor com adições e o maior só junto com a regra abaixo.

Se algo precisar quebrar

Uma mudança incompatível sai ao lado do formato antigo, nunca no lugar dele. O formato novo aparece como um campo novo ou num caminho novo só para os recursos afetados (/api/v2/<resource>), e o antigo continua funcionando durante todo o período de aviso abaixo. Não usamos um cabeçalho de versão por data: ele multiplica comportamentos por endpoint, e as nossas bibliotecas cliente geradas fixam caminhos, não cabeçalhos.

A API compatível com Zendesk está congelada

/zd/api/v2 existe para que clientes escritos para o Zendesk continuem funcionando. O v2 ali é a versão do Zendesk, não a nossa. Nessa superfície só adicionamos endpoints e campos, e nunca mudamos uma resposta que o cliente de outro fornecedor interpreta. O nosso compromisso é com os formatos documentados na página da API compatível com Zendesk, e testes de contrato os protegem em todo build. Se o Zendesk mudar a própria API, a nossa continua como documentada e a diferença é registrada no registro de mudanças.

Versões do payload dos webhooks

Toda entrega e todo ping de webhook trazem um inteiro version no envelope. Hoje é 1, e ele faz parte do contrato público.

• Um envelope incompatível recebe um inteiro novo, nunca uma mudança num existente.
• A versão é escolhida por assinatura de webhook, então um webhook existente mantém o envelope para o qual foi feito.
• Enquanto uma versão é retirada, as duas são entregues durante todo o período de aviso.
• Os tipos de evento são aditivos. Uma assinatura de um tipo de evento que você não conhece nunca falha.
• Se o esquema de assinatura mudar algum dia, a nova assinatura chega num cabeçalho novo e as duas são enviadas durante o período de aviso.

12 meses de aviso

A remoção de um endpoint, um campo, um tipo de evento ou uma versão de envelope de webhook de qualquer uma das três superfícies é anunciada com pelo menos 12 meses de antecedência.

“Anunciada” significa tudo isto, não só o primeiro item:

1. uma entrada em Descontinuado no registro de mudanças da API, com a data prevista da remoção;
2. cabeçalhos de resposta Deprecation e Sunset (RFC 8594) nas operações afetadas, para que um cliente veja sem ler nada;
3. deprecated: true na operação ou no campo do documento OpenAPI;
4. um e-mail aos donos dos espaços de trabalho e aos donos de tokens de API que chamaram o endpoint nos últimos 90 dias.

Os cabeçalhos são assim:

HTTP/1.1 200 OK
Deprecation: Thu, 12 Mar 2026 00:00:00 GMT
Sunset: Fri, 12 Mar 2027 00:00:00 GMT
Link: <https://helpfalcon.com/developers/api-changelog>; rel="deprecation"; type="text/html"

Deprecation é quando anunciamos; Sunset é o primeiro momento em que a operação pode parar de responder.

A única exceção é uma mudança imposta por um problema de segurança ou jurídico. Ela recebe o máximo de aviso que for seguro dar, nunca menos de 7 dias, e sempre um e-mail direto além da entrada no registro de mudanças.

O que não está coberto

• Os endpoints próprios do aplicativo de agentes (/mobile-api) são internos aos nossos apps e mudam com eles. Não construa sobre eles; a API REST tem os mesmos dados.
• Endpoints beta, quando os oferecemos, são marcados como beta no registro de mudanças e não estão sob a regra de 12 meses até que o registro diga que estão. Nada é beta por padrão: tudo na referência da API sem nota de beta está sob a política completa.
• Comportamento que sempre foi um bug. Corrigir uma resposta que contradizia esta documentação é uma correção, e sai numa versão de patch com entrada no registro de mudanças.

Acompanhar

• Acompanhe o registro de mudanças da API, onde toda mudança é escrita primeiro.
• Gere de novo ou atualize a sua biblioteca cliente quando o número menor da versão OpenAPI mudar; os clientes são gerados a partir desse documento.
• Registre os cabeçalhos Deprecation e Sunset na sua integração. Eles são o primeiro aviso legível por máquina que você vai receber.

Registro de decisão: ADR 0014, versionamento da API e dos webhooks e a política de descontinuação.