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 phone-account-area-code-out-of-stock, o mesmo das linhas com chip (no v2, era 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

Na v3, a sincronização é feita em lote, com Sincronizar colaboradores em lote. Ela casa cada colaborador pelo integrationId, como o sync da v1: atualiza quem já foi sincronizado com aquele identificador e cria quem ainda não existe. O que muda em relação à v1:
  • O corpo é uma lista. Envie { "employees": [ ... ] }, com até 1.000 colaboradores por requisição, cada um com os mesmos campos de antes. O corpo da requisição é limitado a 1 MB; se a sua base passar disso, divida-a em mais de uma requisição.
  • A resposta é uma tarefa, não o colaborador. A requisição responde 202 com um taskId. Acompanhe o andamento em Detalhar tarefa ou pelos webhooks de tarefa, e veja o resultado de cada colaborador em Listar resultados da tarefa. Saiba mais em Introdução a tarefas.
  • A validação é da lista inteira. Se algum colaborador for inválido, a resposta é 422, aponta a posição dele e nenhum é alterado. Um integrationId repetido na mesma lista também é recusado.
  • A chave precisa do escopo task:read, além de employee:sync, para ler o resultado da tarefa.
Para criar ou alterar um colaborador pontualmente, com a resposta na hora, use POST /api/v3/employees e PATCH /api/v3/employees/{id}.

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.