Skip to main content
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.

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.
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 <chave>. 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.

Onde cada endpoint da v1 fica na v3

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:
  • 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:
Nos erros de validação (422), a v3 lista os campos inválidos em details:
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: 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. 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.

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

1

Troque os caminhos

Atualize cada chamada conforme a tabela acima, incluindo os métodos que mudaram.
2

Adapte as listagens

Passe a ler data e a paginar com page e pageSize.
3

Adapte o tratamento de erros

Se você lê publicDetails, leia os campos na raiz da resposta.
4

Revise os números virtuais

Renomeie os campos da criação, remova o redirecionamento e envie reason no cancelamento.
5

Valide no sandbox

Rode a integração com uma chave salvy_test_ antes de publicar em produção.