> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salvy.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Deprecação
> Identifique pelos cabeçalhos da resposta quando um endpoint está em fim de vida e quanto tempo você tem para migrar
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:
| Cabeçalho | O que informa | Exemplo |
| ------------- | ----------------------------------------------------------------- | ------------------------------- |
| `Deprecation` | Quando o endpoint passou (ou passará) a ser considerado deprecado | `@1782863999` |
| `Sunset` | A partir de quando ele deixa de ser atendido | `Thu, 31 Dec 2026 23:59:59 GMT` |
| `Link` | Documentação da mudança e, quando existe, o endpoint substituto | veja abaixo |
Uma resposta completa se parece com isto:
```http theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: @1782863999
Sunset: Thu, 31 Dec 2026 23:59:59 GMT
Link: ; rel="deprecation"; type="text/html",
; rel="successor-version"
```
* `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](https://www.rfc-editor.org/rfc/rfc9745.html).
* `Sunset` usa uma **data HTTP** (`IMF-fixdate`) — conforme a [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594.html).
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`:
```js theme={null}
const response = await fetch(
'https://api.salvy.com.br/api/v2/virtual-phone-accounts',
{
headers: { Authorization: `Bearer ${process.env.SALVY_API_KEY}` },
},
);
const sunset = response.headers.get('Sunset');
if (sunset) {
// Encaminhe para onde o seu time realmente olha: log estruturado,
// Sentry, Slack, o que for.
console.warn(
`[salvy] endpoint deprecado, deixa de ser atendido em ${sunset}.`,
`Detalhes: ${response.headers.get('Link')}`,
);
}
```
Para inspecionar manualmente, basta pedir os cabeçalhos no `curl`:
```bash theme={null}
curl -i -X GET "https://api.salvy.com.br/api/v2/virtual-phone-accounts" \
-H "Authorization: Bearer salvy_prod_sua_chave_aqui"
```
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
Garanta que a presença de `Sunset` gere um log ou alerta em algum lugar que
o seu time acompanhe.
Abra a URL indicada em `rel="deprecation"`. Ela descreve o que muda e o que
é necessário para migrar.
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.
Teste a integração migrada com uma chave `salvy_test_` antes de trocar em
produção. Veja [Ambientes](/api-reference/environments).
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.