Como migrar da API de preços v1 para a API de preços v2

Visão geral

Este guia explica como migrar da API de Preços v1 para a API de Preços v2. A nova versão da API de Preços inclui alterações na autenticação, nas rotas e nas estruturas de resposta. Este guia documentará as alterações que você precisa fazer em seu aplicativo para que possa atualizar sua integração.

A migração para a API de Preços v2 é importante para aproveitar as vantagens da maior consistência, segurança e flexibilidade oferecidas pela nova API.

Antes de começar

Antes de iniciar a migração, certifique-se de que:

• Você já possui sua chave API e seu segredo API da Vonage.
• Você consultou esta documentação para entender os novos recursos e funcionalidades.
• Você dispõe de um ambiente de teste ou desenvolvimento para testar as alterações antes de implantá-las na produção.

Observe a alteração na URL

A API de Preços v2 utiliza uma nova URL base para a API em comparação com a v1.

1. Na sua aplicação, altere a URL base e a rota de https://rest.nexmo.com/account/get-pricing/outbound/ para https://api.nexmo.com/v2/account/pricing/

   Copiar

   // Example using the old route
   const apiKey = 'vonage_api_key'; // Replace with your API Key
   const apiSecret = 'vonage_api_secret'; // Replace with your API Secret
   const product = 'sms'; // Example product
   const country = 'CA'; // Example country code
   
   const url = `https://rest.nexmo.com/account/get-pricing/outbound/${product}?api_key=${apiKey}&api_secret=${apiSecret}&country=${country}`;
   

   Copiar

   // Example using the new route
   const apiKey = 'vonage_api_key'; // Replace with your API Key
   const apiSecret = 'vonage_api_secret'; // Replace with your API Secret
   const product = 'sms-outbound'; // Example product
   const country = 'CA'; // Example country code
   
   const url = `https://api.nexmo.com/v2/account/pricing/${product}`
   

Selecione o produto adequado

A API de Preços v2 suporta apenas sms-outbound e voice-outbound, em comparação com a API de Preços v1, que oferecia suporte a sms, sms-transit, e voice. Você precisará se certificar de usar o nome correto do produto, pois ele pode mudar. Na maioria dos casos sms-transit e sms pode ser alterado para sms-outbound, e voice pode ser alterado para voice-outbound.

Migrar para a autenticação por cabeçalho básico

A API de Preços v1 utilizava a autenticação por parâmetro de consulta para validar sua solicitação, e a API de Preços v2 agora utiliza a autenticação básica por meio do Authorization cabeçalho.

1. Encontre a solicitação de API em seu aplicativo atual. Se você estiver usando o Node.js, suas solicitações podem ter a seguinte aparência:

   Copiar

   const fetch = require('node-fetch');
   
   const apiKey = 'vonage_api_key'; // Replace with your API Key
   const apiSecret = 'vonage_api_secret'; // Replace with your API Secret
   const product = 'sms'; // Example product
   const country = 'CA'; // Example country code
   
   const url = `https://rest.nexmo.com/account/get-pricing/outbound/${product}?api_key=${apiKey}&api_secret=${apiSecret}&country=${country}`;
   
   fetch(url)
       .then(response => {
           if (!response.ok) {
           throw new Error(`HTTP error! status: ${response.status}`);
           }
           return response.json();
       })
       .then(data => {
           console.log('Pricing Data:', data);
       })
       .catch(error => {
           console.error('Error fetching pricing data:', error);
       });
   

   Copiar

   const axios = require('axios');
   
   const apiKey = 'vonage_api_key'; // Replace with your API Key
   const apiSecret = 'vonage_api_secret'; // Replace with your API Secret
   const product = 'sms-outbound'; // Example product
   const country = 'CA'; // Example country code
   
   const url = `https://rest.nexmo.com/account/get-pricing/outbound/sms`;
   
   axios
       .get(url, {
           params: {
           api_key: apiKey,
           api_secret: apiSecret,
           country: country,
           },
       })
       .then(response => {
           console.log('Pricing Data:', response.data);
       })
       .catch(error => {
           console.error('Error fetching pricing data:', error.response ? error.response.data : error.message);
       });
   

2. Remova o api_key e api_secret parâmetros e substituí-los por um Authentication cabeçalho que utiliza autenticação Basic.

   Copiar

   // Example using Node Fetch
   const fetch = require('node-fetch');
   
   const apiKey = 'vonage_api_key'; // Replace with your API Key
   const apiSecret = 'vonage_api_secret'; // Replace with your API Secret
   const product = 'sms-outbound'; // Example product
   const country = 'CA'; // Example country code
   
   const url = `https://api.nexmo.com/v2/account/pricing/${product}?country=${country}`;
   
   fetch(url, {
       method: 'GET',
       headers: {
           Authorization: `Basic ${Buffer.from(`${apiKey}:${apiSecret}`).toString('base64')}`,
       },
   })
       .then(response => {
           if (!response.ok) {
           throw new Error(`HTTP error! status: ${response.status}`);
           }
           return response.json();
       })
       .then(data => {
           console.log('Pricing Data:', data);
       })
       .catch(error => {
           console.error('Error fetching pricing data:', error);
       });
   

   Copiar

   // Example using Axios
   const axios = require('axios');
   
   const apiKey = 'vonage_api_key'; // Replace with your API Key
   const apiSecret = 'vonage_api_secret'; // Replace with your API Secret
   const product = 'sms-outbound'; // Example product
   const country = 'CA'; // Example country code
   
   const url = `https://api.nexmo.com/v2/account/pricing/${product}`;
   
   axios
       .get(url, {
           auth: {
               username: username,
               password: password,
           },
           params: {
               country: country,
           },
       })
       .then(response => {
           console.log('Pricing Data:', response.data);
       })
       .catch(error => {
           console.error('Error fetching pricing data:', error.response ? error.response.data : error.message);
       });
   

Alteração para processar a nova estrutura de resposta

A API de Preços v2 agora utiliza um JSON-HAL estrutura de resposta para torná-la mais consistente com outras APIs da Vonage. Essa estrutura de resposta da API difere da estrutura mais simples da API de Preços v1, mas oferece alguns benefícios adicionais, como uma melhor paginação dos resultados.

1. Observe a mudança na localização dos dados na resposta. As informações sobre preços e rede agora se encontram no _embedded.countries matriz em vez do networks matriz.

   Copiar

   // Pricing API v1 Response
   {
       "countryCode": "CA",
       "countryName": "Canada",
       "countryDisplayName": "Canada",
       "currency": "EUR",
       "defaultPrice": "0.00620000",
       "dialingPrefix": "1",
       "networks": [
           {
               "type": "mobile",
               "price": "0.00590000",
               "currency": "EUR",
               "mcc": "302",
               "mnc": "530",
               "networkCode": "302530",
               "networkName": "Keewaytinook Okimakanak"
           }
       ]
   }
   

   Copiar

   // Pricing API v2 Response
   {
       "page_size": "100",
       "page": "1",
       "total_items": "243",
       "total_pages": "3",
       "_embedded": {
           "countries": [
               {
                   "country_name": "Canada",
                   "dialing_prefix": "1",
                   "dest_network_type": "ALL",
                   "group_internal_start": "1s",
                   "rate_increment": "60",
                   "currency": "USD",
                   "price": "0.1"
               }
           ]
       },
       "_links": {
           "self": {
               "href": "https://api.nexmo.com/account/pricing/sms-outbound?page=1&page_size=100"
           },
           "first": {
               "href": "https://api.nexmo.com/account/pricing/sms-outbound?page=1&page_size=100"
           },
           "last": {
               "href": "https://api.nexmo.com/account/pricing/sms-outbound?page=3&page_size=100"
           },
           "next": {
               "href": "https://api.nexmo.com/account/pricing/sms-outbound?page=2&page_size=100"
           },
           "prev": {
               "href": "https://api.nexmo.com/account/pricing/sms-outbound?page=1&page_size=100"
           }
       }
   }
   

2. Observe as alterações nos nomes das chaves. Agora, os nomes das chaves utilizam snake_case em vez de camelCase. Isso está em conformidade com os padrões da API da Vonage e mantém a consistência com nossas outras respostas de API. A localização de algumas chaves também mudou.

• countryCode agora está localizado na URL como o country parâmetro de consulta.
• countryName agora está localizado em _embedded.countries[X].country_name.
• countryDisplayName agora está localizado em _embedded.countries[X].country_name.
• currency agora está localizado em _embedded.countries[X].currency.
• defaultPrice agora está localizado em _embedded.countries[X].price.
• dialingPrefix agora está localizado em _embedded.countries[X].dialing_prefix.
• network[X].type não é mais retornado.
• network[X].price agora está localizado em _embedded.countries[X].price.
• network[X].currency agora está localizado em _embedded.countries[X].currency.
• network[X].mcc não é mais retornado.
• network[X].mnc não é mais retornado.
• network[X].networkCode não é mais retornado.
• network[X].networkName não é mais retornado.

3. A resposta agora reflete com mais precisão o paging. Você pode comparar o page chave com o total_pages tecla para verificar se você está no final dos resultados ou para verificar se existe o _links.next tecla. Se precisar passar para a próxima página, você pode usar a _links.next.href valor para determinar automaticamente e navegar para a próxima página.

Veja também

• Especificação OpenAPI da API de Preços v2