> ## 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.
# Migrando da v1 para a v3
> O que muda ao trocar a v1 pela v3: o equivalente de cada endpoint, as mudanças de contrato e o que não tem substituto
A v1 da API está deprecada desde 11/08/2026 e **deixa de ser atendida em 01/02/2027**. Esta página mostra, endpoint por endpoint, onde cada chamada da v1 fica na v3 e o que muda no contrato.
Migre e valide tudo no sandbox antes de trocar em produção: basta usar uma
chave `salvy_test_`. Veja [Ambientes](/api-reference/v3/environments).
## Migrando com a ajuda de uma IA
Se você usa um assistente de código (Claude, ChatGPT, Cursor, Copilot…), copie o prompt abaixo e cole no assistente, dentro do repositório da sua integração. Ele lê este guia e a especificação da v3 e faz a migração por você, deixando o que não tiver equivalente para você decidir.
```text theme={null}
Migre a integração deste repositório da API da Salvy da v1 para a v3.
Fontes de verdade (leia antes de começar):
- Guia de migração: https://docs.salvy.com.br/api-reference/v3/migration-guide.md
- Especificação da v3: https://docs.salvy.com.br/api-reference/v3/openapi.json
- Índice da documentação: https://docs.salvy.com.br/llms.txt
O que fazer:
1. Encontre todas as chamadas para /api/v1/ no código.
2. Troque cada uma pelo equivalente na v3 indicado no guia, incluindo os métodos HTTP que mudaram.
3. Adapte as listagens para ler `data` e paginar com `page` e `pageSize` até `totalPages`.
4. Adapte o tratamento de erros: os campos que vinham em `publicDetails` passam a vir na raiz da resposta.
5. Na criação de números virtuais, renomeie os campos conforme o guia. No cancelamento, envie `reason`, que é obrigatório.
6. Mantenha POST /api/v1/employees/sync apontando para POST /api/v2/employees/sync, sem outras mudanças.
Regras:
- Não invente endpoints, campos ou códigos de erro: use só o que está no guia e na especificação.
- Não remova funcionalidade silenciosamente. O redirecionamento de chamadas não existe na v3: remova o uso dele e liste cada ocorrência no resumo final, para que eu decida o que fazer.
- Atualize ou crie testes para cada chamada alterada.
- Não use chaves de produção. Para testar, use uma chave de sandbox (`salvy_test_`).
No final, me mostre um resumo com: cada chamada alterada (antes → depois), o que você não conseguiu migrar e por quê, e o que eu preciso validar manualmente.
```
Revise as mudanças antes de publicar. O assistente segue o guia, mas quem
conhece as regras da sua integração é você.
## O que não muda
* **Endereço base e autenticação**: continuam `https://api.salvy.com.br` e o cabeçalho `Authorization: Bearer `. A mesma chave de API funciona nas duas versões.
* **Webhooks**: não dependem da versão da API. Os webhooks que você já recebe continuam iguais, e a v3 traz eventos novos. Veja [Webhooks](/api-reference/v3/webhooks/introduction).
## Onde cada endpoint da v1 fica na v3
| v1 | v3 | O que muda |
| - | - | - |
| `GET /api/v1/assets` | `GET /api/v3/assets` | Resposta paginada |
| `POST /api/v1/assets` | `POST /api/v3/assets` | — |
| `GET /api/v1/assets/{id}` | `GET /api/v3/assets/{id}` | — |
| `POST /api/v1/assets/{id}` | `PATCH /api/v3/assets/{id}` | O método passa a ser `PATCH`; os campos são os mesmos |
| `POST /api/v1/assets/{id}/archive` | `POST /api/v3/assets/{id}/archive` | — |
| `POST /api/v1/assets/{id}/timeline-notes` | `POST /api/v3/assets/{id}/timeline-notes` | — |
| `GET /api/v1/employees` | `GET /api/v3/employees` | Resposta paginada |
| `POST /api/v1/employees/sync` | continua na v2 | Veja [Sincronização de colaboradores](#sincronização-de-colaboradores) |
| `GET /api/v1/virtual-phone-accounts` | `GET /api/v3/phone-accounts` | Lista todos os tipos de linha; filtre por `productType` |
| `POST /api/v1/virtual-phone-accounts` | `POST /api/v3/phone-accounts/mobile-did` | Campos renomeados; sem redirecionamento |
| `DELETE /api/v1/virtual-phone-accounts/{id}` | `POST /api/v3/phone-accounts/{id}/cancel` | O método muda e `reason` passa a ser obrigatório |
| `PATCH /api/v1/virtual-phone-accounts/{id}/redirect` | sem equivalente | Veja [Redirecionamento de chamadas](#redirecionamento-de-chamadas) |
| `GET /api/v1/virtual-phone-accounts/area-codes` | `GET /api/v3/area-codes?productType=mobile-did` | `productType` é obrigatório |
## Mudanças de contrato
### Listagens paginadas
Na v1, as listagens devolvem todos os registros de uma vez, numa chave com o nome do recurso (`assets`, `employees`). Na v3, toda listagem devolve `data` e `pagination`:
```json theme={null}
{
"data": [{ "id": "0198c2f1-3815-45b7-9e60-8e137cad845c" }],
"pagination": { "page": 1, "pageSize": 50, "totalCount": 132, "totalPages": 3 }
}
```
* `page` começa em 1; `pageSize` tem padrão 50 e máximo 200.
* Para ler tudo, avance `page` até chegar em `totalPages`.
* As listagens da v3 também aceitam filtros e ordenação (`sortBy`, `sortOrder`). Consulte a página de cada endpoint.
### Formato dos erros
Na v1, os detalhes do erro vêm dentro de `publicDetails`. Na v3, eles vêm na raiz da resposta:
```json theme={null}
// v1
{ "code": "resource-not-found", "message": "…", "publicDetails": { } }
// v3
{ "code": "resource-not-found", "message": "…" }
```
Nos erros de validação (`422`), a v3 lista os campos inválidos em `details`:
```json theme={null}
{
"code": "input-validation-error",
"message": "…",
"details": [{ "key": "areaCode", "message": "…" }]
}
```
Se a sua integração decide o que fazer a partir de `code`, nada muda. Se ela lê `publicDetails`, passe a ler os campos na raiz.
## Números virtuais
Na v3, números virtuais são linhas como as outras: ficam em `/phone-accounts`, ao lado das linhas móveis, e são identificados por `productType`.
### Criação
`POST /api/v3/phone-accounts/mobile-did` substitui `POST /api/v1/virtual-phone-accounts`:
| v1 | v3 |
| - | - |
| `identifier` | `name` |
| `costCenter` | `costCenterId` |
| `areaCode` | `areaCode` |
| `employeeId` | `employeeId` |
| `redirectPhoneNumber`, `redirectExpiresAt` | não existem |
| — | `groupId`, `customFields` (novos) |
Na v1, `costCenter` era um texto livre. Na v3, o centro de custo é um recurso próprio: crie-o com `POST /api/v3/cost-centers` (ou encontre um existente em `GET /api/v3/cost-centers`) e envie o `id` dele em `costCenterId`.
A criação aceita o cabeçalho `idempotency-key`: se a requisição for repetida com a mesma chave, a v3 devolve o número criado na primeira vez, sem criar outro.
### DDDs disponíveis
Para mostrar ao usuário só os DDDs em que dá para criar um número, use `GET /api/v3/area-codes?productType=mobile-did`. Cada DDD vem com `available`, que indica se há número disponível nele no momento; para listar só os disponíveis, envie `available=true`.
A disponibilidade muda ao longo do tempo, então consulte a lista perto do momento da compra. Na criação do número:
* se o DDD não existir, a resposta é `422` com o código `phone-account-area-code-invalid`;
* se não houver número disponível no momento, a resposta é `409` com o código `did-area-code-out-of-stock`. A indisponibilidade é temporária; tente novamente mais tarde.
### Redirecionamento de chamadas
O redirecionamento de chamadas não está disponível na v3. Números criados na v3 não têm redirecionamento, e `PATCH /api/v1/virtual-phone-accounts/{id}/redirect` não tem equivalente.
### SMS recebidos
Para receber os SMS de um número em tempo real, use o webhook [SMS recebido](/api-reference/v3/webhooks/sms-received). Para consultar os já recebidos, use `GET /api/v3/phone-accounts/{id}/sms-messages`.
### Cancelamento
`POST /api/v3/phone-accounts/{id}/cancel` substitui `DELETE /api/v1/virtual-phone-accounts/{id}`. Na v3, `reason` é obrigatório. O cancelamento também pode ser agendado para o fim do ciclo de faturamento com `type: "scheduled"`; veja [Cancelar linha](/api-reference/v3/phone-accounts/cancel).
## Sincronização de colaboradores
A v3 não tem `POST /employees/sync`. A sincronização em massa vai ganhar um endpoint próprio de operações em lote. Até lá:
* **Para criar ou alterar colaboradores pontualmente**, use `POST /api/v3/employees` e `PATCH /api/v3/employees/{id}`.
* **Para manter a sincronização da base inteira**, continue usando `POST /api/v2/employees/sync`. A v2 segue atendida e o endpoint funciona como na v1; basta trocar `/api/v1/` por `/api/v2/` no caminho.
## Checklist de migração
Atualize cada chamada conforme a tabela acima, incluindo os métodos que mudaram.
Passe a ler `data` e a paginar com `page` e `pageSize`.
Se você lê `publicDetails`, leia os campos na raiz da resposta.
Renomeie os campos da criação, remova o redirecionamento e envie `reason` no cancelamento.
Rode a integração com uma chave `salvy_test_` antes de publicar em produção.