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.O que não muda
- Endereço base e autenticação: continuam
https://api.salvy.com.bre o cabeçalhoAuthorization: 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:
pagecomeça em 1;pageSizetem padrão 50 e máximo 200.- Para ler tudo, avance
pageaté chegar emtotalPages. - 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 depublicDetails. Na v3, eles vêm na raiz da resposta:
422), a v3 lista os campos inválidos em details:
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, useGET /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 é
422com o códigophone-account-area-code-invalid; - se não houver número disponível no momento, a resposta é
409com o códigodid-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, ePATCH /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, useGET /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 temPOST /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/employeesePATCH /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.