Comment migrer de Pricing API v1 à Pricing API v2 ?

Vue d'ensemble

Ce guide explique comment migrer de l'API de tarification v1 à l'API de tarification v2. La nouvelle version de l'API de tarification comprend des changements au niveau de l'authentification, des itinéraires et des structures de réponse. Ce guide documentera les changements que vous devez apporter à votre application afin que vous puissiez mettre à jour votre intégration.

Il est important de migrer vers l'API de tarification v2 pour profiter de l'amélioration de la cohérence, de la sécurité et de la flexibilité offerte par la nouvelle API.

Avant de commencer

Avant de commencer votre migration, assurez-vous que

Vous avez votre clé d'API et votre secret d'API Vonage existants.
Vous avez consulté cette documentation pour comprendre les nouvelles fonctionnalités et capacités.
Vous disposez d'un environnement de test ou de développement pour tester les changements avant de les déployer en production.

Notez le changement d'URL

L'API de tarification v2 utilise une nouvelle URL de base pour l'API par rapport à la v1.

Dans votre application, modifiez l'URL de base et la route de https://rest.nexmo.com/account/get-pricing/outbound/ à https://api.nexmo.com/v2/account/pricing/

// 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}`;

// 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}`

Choisir le produit approprié

L'API de tarification v2 ne prend en charge que sms-outbound et voice-outboundpar rapport à la version 1 de l'API de tarification qui prenait en charge sms, sms-transitet voice. Vous devrez vous assurer d'appeler le nom du produit approprié, car il peut changer. Dans la plupart des cas sms-transit et sms peut être remplacé par sms-outboundet voice peut être remplacé par voice-outbound.

Migrer vers l'authentification par en-tête de base

L'API de tarification v1 utilisait l'authentification des paramètres de requête pour valider votre demande, et l'API de tarification v2 utilise maintenant l'authentification de base à l'aide de l'option Authorization l'en-tête.

Trouvez la demande d'API dans votre application actuelle. Si vous utilisez Node.js, vos demandes peuvent ressembler à ce qui suit :

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);
    });

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);
    });

Retirer le api_key et api_secret et les remplacer par un Authentication qui utilise l'authentification de base.

// 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);
    });

// 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);
    });

Changement pour traiter la nouvelle structure d'intervention

L'API de tarification v2 utilise désormais une fonction JSON-HAL pour la rendre plus cohérente avec les autres API de Vonage. Il s'agit d'une structure de réponse API différente de la structure de réponse plus plate de l'API de tarification v1, mais elle offre des avantages supplémentaires comme une meilleure pagination des résultats.

Notez le changement d'emplacement des données dans la réponse. Les informations relatives à la tarification et au réseau se trouvent désormais dans la section _embedded.countries au lieu du tableau networks de la gamme.

// 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"
        }
    ]
}

// 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"
        }
    }
}

Notez les changements apportés aux noms des clés. Les noms de clés utilisent désormais snake_case au lieu de camelCase. Ceci est conforme aux normes de l'API de Vonage et reste cohérent avec les autres réponses de l'API. Certains emplacements des clés ont également changé.

countryCode est maintenant situé dans l'URL en tant que country paramètre de la requête.
countryName se trouve désormais à l'adresse suivante _embedded.countries[X].country_name.
countryDisplayName se trouve désormais à l'adresse suivante _embedded.countries[X].country_name.
currency se trouve désormais à l'adresse suivante _embedded.countries[X].currency.
defaultPrice se trouve désormais à l'adresse suivante _embedded.countries[X].price.
dialingPrefix se trouve désormais à l'adresse suivante _embedded.countries[X].dialing_prefix.
network[X].type n'est plus renvoyée.
network[X].price se trouve désormais à l'adresse suivante _embedded.countries[X].price.
network[X].currency se trouve désormais à l'adresse suivante _embedded.countries[X].currency.
network[X].mcc n'est plus renvoyée.
network[X].mnc n'est plus renvoyée.
network[X].networkCode n'est plus renvoyée.
network[X].networkName n'est plus renvoyée.

La réponse reflète désormais plus fidèlement la radiomessagerie. Vous pouvez comparer la page avec la touche total_pages pour voir si vous êtes à la fin des résultats, ou vérifiez l'existence de la touche _links.next de l'écran. Si vous devez passer à la page suivante, vous pouvez utiliser la touche _links.next.href pour déterminer automatiquement la page suivante et y naviguer.

Voir aussi

Spécification OpenAPI de l'API de tarification v2