Skip to main content
Conforme a API evolui, alguns endpoints e versões saem de circulação. Quando isso acontece, a Salvy avisa em toda resposta do endpoint afetado, através de cabeçalhos HTTP padronizados. Isso significa que a própria integração pode detectar a deprecação e avisar o seu time, sem depender de alguém ler um aviso na caixa de entrada.
Se você fizer só uma coisa nesta página, faça esta: registre um log ou alerta sempre que uma resposta da Salvy vier com o cabeçalho Sunset.

​
Por onde o aviso chega

  • Cabeçalhos HTTP — em toda resposta do endpoint deprecado. É o único canal que acompanha cada requisição e, por isso, o único que a sua integração não corre o risco de perder.
  • Especificação OpenAPI — a operação passa a ser publicada como deprecada, com as datas e o caminho de migração na descrição.
  • E-mail — a Salvy também comunica as deprecações da API por e-mail para os contatos da sua empresa.
Quem recebe o aviso depende de quando a chave de API foi criada: para chaves a partir de 07/2026, avisamos quem criou a chave; para chaves anteriores, o e-mail de contato da empresa. Confirme com o seu contato na Salvy quem recebe esses avisos hoje, sobretudo se quem criou a chave não for mais quem mantém a integração.

​
Como a Salvy sinaliza uma deprecação

Três cabeçalhos acompanham as respostas de um endpoint deprecado: Uma resposta completa se parece com isto:
  • rel="deprecation" aponta para a página que explica a mudança e o caminho de migração.
  • rel="successor-version" aponta para o endpoint que substitui o atual. Ele só aparece quando existe um substituto direto.

​
Os dois formatos de data são diferentes

Não é um erro de digitação:
  • Deprecation usa um timestamp Unix em segundos, prefixado por @ — conforme a RFC 9745.
  • Sunset usa uma data HTTP (IMF-fixdate) — conforme a RFC 8594.
Como são cabeçalhos padronizados, é possível que a sua biblioteca HTTP, gateway ou ferramenta de observabilidade já saiba interpretá-los.

​
Como consumir os cabeçalhos

A checagem mínima é olhar para a presença de Sunset:
Para inspecionar manualmente, basta pedir os cabeçalhos no curl:
Avise uma vez por processo, não uma vez por requisição. Um alerta a cada chamada transforma o aviso em ruído e o seu time passa a ignorá-lo.

​
Em quais respostas os cabeçalhos aparecem

Os cabeçalhos acompanham as respostas autenticadas do endpoint, incluindo as de erro. Se você recebe um 404 ou um 422 de um endpoint deprecado, o aviso vem junto. Eles não aparecem em respostas 401 e 403, porque a autenticação é avaliada antes. Uma chave inválida devolve o erro de autenticação e nada mais.

​
Onde mais a deprecação aparece

Além dos cabeçalhos, a deprecação é publicada na especificação OpenAPI da API pública:
  • a operação é marcada com deprecated: true, o que faz ferramentas como Postman, Insomnia e geradores de cliente exibirem o endpoint como obsoleto;
  • a descrição da operação começa com [DEPRECADO], seguido das datas e do link de migração;
  • os cabeçalhos acima estão documentados nas respostas da operação.
Ou seja: se a sua integração é gerada a partir da especificação, a informação chega até você sem esforço adicional.

​
O que fazer quando você vê o aviso

1

Registre

Garanta que a presença de Sunset gere um log ou alerta em algum lugar que o seu time acompanhe.
2

Leia a documentação da mudança

Abra a URL indicada em rel="deprecation". Ela descreve o que muda e o que é necessário para migrar.
3

Migre para o substituto

Quando houver rel="successor-version", aponte a sua integração para o novo endpoint. Diferenças de contrato estão descritas na documentação da mudança.
4

Valide no sandbox

Teste a integração migrada com uma chave salvy_test_ antes de trocar em produção. Veja Ambientes.
A partir da data indicada em Sunset, a Salvy não garante mais o funcionamento do endpoint. Conclua a migração antes dessa data.

​
Versões da API

Endpoints da API pública são versionados no caminho (/api/v1/..., /api/v2/...). Uma versão mais nova de um endpoint não invalida a anterior automaticamente: quando uma versão for deprecada, ela passará a responder com os cabeçalhos descritos nesta página. Em caso de dúvida sobre um aviso de deprecação que você recebeu, fale com o seu contato na Salvy.