Principes de base des API
Principes de base de l’intégration et l’interaction avec les interfaces API de Postes Canada
Les interfaces API de Postes Canada permettent aux détaillants en ligne et aux fournisseurs de solution de cybercommerce d’intégrer les services de Postes Canada tels que l’expédition, la tarification et les données de suivi, à une plate-forme ou à un site Web. Une fois intégrée, votre application accédera aux serveurs de Postes Canada au moyen de l’architecture de style REST.
Avant le début du travail d’intégration
- Vous devez lire Pour commencer pour savoir comment vous inscrire et obtenir vos clés API.
- Passez en revue les renseignements inclus ici dans les principes de base des API pour obtenir des renseignements essentiels communs à toutes les interfaces API.
- Utilisez la fonction d’essai de l’interface API de votre application [Test] pour vérifier l’accès et afficher des échantillons de données. Remarque : Les demandes réussies par l’entremise des applications [Test] donnent des réponses statiques et tronquées.
- Lisez les descriptions fonctionnelles et techniques détaillées de chacune de nos interfaces API dans le catalogue d’API.
Utilisation de REST pour interagir avec nos interfaces API
L’image suivante montre le format général de toute demande REST. Consultez le répertoire des services pour obtenir des précisions par appel.
Une demande REST à une API de Postes Canada consiste à préciser la méthode HTTP, l’URL finale, les paramètres de requête facultatifs et les en-têtes HTTP. La demande de charge utile est envoyée à l’API. L’API répond par un code d’état HTTP et fournit les renseignements demandés ou les détails d’erreur.
Points de terminaison
Vous utiliserez deux types de points de terminaison pour accéder aux API de Postes Canada :
- Points de terminaison construits par votre code d’application
- Points de terminaison fournis dans les réponses aux demandes précédentes
Chaque point de terminaison a reçu un nom pratique aux fins de référence. Ce nom de référence n’apparaît pas directement dans le point de terminaison.
Familiarisez-vous avec les noms des références. Lorsqu’ils doivent être appelés par le code d’application, consultez la documentation dans le catalogue d’interfaces API pour obtenir des précisions sur chaque point de terminaison ou échantillon de code.
Points de terminaison construits
Exemple de point de terminaison (selon les documents) pour Obtenir les manifestes
Les points de terminaison construits sont composés d’une adresse URL fixe et peuvent également contenir des éléments variables. Le point de terminaison pour Obtenir les manifestes est le suivant :
XX/{mailed by customer}/{mobo}/manifest?from=AAAAMMJJ&to=AAAAMMJJ
Remplacez {envoyé par la cliente ou le client} par votre numéro de compte.
Remplacez {mobo} par le numéro de compte MOBO ou répétez votre numéro de compte.
Remplacez AAAAMMJJ par les dates de début et de fin.
Exemple de point de terminaison
Vous trouverez ci-dessous un exemple de demande GET avec les valeurs variables prédéfinies.
https://api.canadapost-postescanada.ca/prod/devportal-portaildesdeveloppeurs/shipping/v1/123456789/123456789/manifests?from=20100324&to=20100405
Variables de points de terminaison construits
Il existe deux types d’éléments variables :
- Le domaine de la demande. Par exemple :
- Expédié selon le numéro de compte
- Le numéro de compte MOBO associé à la demande
- Chaîne de requête de la demande :
- Contient un ou plusieurs paramètres de requête qui peuvent être nécessaires selon l'API appelé.
Variables du domaine : expédié par la cliente ou le client et MOBO
Le domaine peut être corrigé pour tous les appels si votre application agit au nom d’un(e) seul(e) client(e). Dans la documentation détaillée sur le service, les variables de domaine sont représentées entre deux distinctions. Par exemple :
{mailed by customer} signifie que votre demande doit comporter votre numéro de compte.
{mobo} signifie que votre demande doit fournir le numéro de compte de l’entité au nom de laquelle vous expédiez (dit client[e] MOBO). Si vous n’expédiez pas de courrier au nom de qui que ce soit, répétez votre numéro de compte ici.
Les variables de domaine sont protégées de la même façon que le corps de la demande et de la réponse sous la connexion HTTPS.
Chaîne de requêtes
S’il y a lieu, la chaîne de requêtes variera en fonction des besoins courants de votre application. Par exemple, la chaîne de requêtes pourrait faire passer la saisie du postal-code de l’utilisateur à la demande Obtenir le bureau de poste le plus près.
Pour être interprétée correctement, une chaîne de requêtes ne peut pas contenir d’espaces vides. Les espaces vides peuvent toutefois être remplacés par %20 (par exemple, pour l’espace entre les deux éléments d’un code postal).
La chaîne de requêtes est protégée de la même façon que le corps de la demande et de la réponse sous la connexion HTTPS.
Points de terminaison fournis
Les interfaces API de Postes Canada fournissent des points de terminaison générés de façon dynamique en réponse à ce qu’on appelait auparavant un service Web. Dans ces cas, vous devez utiliser le point de terminaison comme il a été reçu et ne pas tenter de l’analyser ou de le construire.
Toutes les API de Postes Canada appelés par les points de terminaison fournis nécessitent une méthode HTTP GET et n’ont pas besoin d’un corps de demande.
Attributs des liens des points de terminaison fournis
| Attribut du lien | Signification |
|---|---|
| rel (relation avec lien) | Indique la ressource liée à la réponse courante. |
| href (référence hypertexte) | Indique le point de terminaison à utiliser pour joindre l’interface API. Il contient l’URL et peut également contenir une chaîne de requêtes. |
| media-type | Chaîne de caractères qui indique le format et la version des données auxquelles s’attendre lorsque l’interface API est appelée. La valeur de cet attribut doit être copiée dans la variable d’en-tête HTTP Accept (Accepter) lorsque le lien vers la référence hypertexte est appelé. |
| index (facultatif) | Présent sur les liens vers le format de sortie, par exemple les étiquettes. La valeur commence à 0 pour la première page, et les pages suivantes (le cas échéant) comptent chacune pour une unité de plus. |
Schémas d’appels
La première interaction avec une interface API de Postes Canada se fera toujours au moyen d’un point de terminaison construit. Les interactions ultérieures utiliseront d’ordinaire les points de terminaison fournis jusqu’à ce que tous les renseignements liés à l’appel de départ aient été récupérés. Deux schémas courants sont utiles. Reportez-vous aux schémas d’appels ponctuels ou par lot.
Si, à tout moment pendant le traitement, votre application plante et que les liens stockés sont perdus, vous pouvez les récupérer au moyen de la synchronisation des appels.
Variables des en-têtes HTTP
Il faut obligatoirement fournir les variables des en-têtes HTTP pour chaque requête. La valeur d’autorisation utilisée pour authentifier chaque requête est la plus importante.
| Variable des en-têtes HTTP | Valeur (Obligatoire ou Facultatif) | Description |
|---|---|---|
Authorization GET POST DEL | Bearer (Obligatoire) |
|
Content-Type POST | Unique par groupe de services. Consultez les documents sur l’interface API pour obtenir plus de précisions. (Obligatoire) | Il s’agit de la version JSON du corps que vous envoyez dans le POST. (Remarque : */* à la place de la valeur d’en-tête affichera un message d’erreur.) |
Accept GET | Unique par groupe de services. Consultez les documents sur l’interface API pour obtenir des précisions ou utilisez le type de média à partir du lien fourni. (Obligatoire) | Il s’agit de la version JSON de la réponse que vous vous attendez à recevoir. (Remarque : */* à la place de la valeur d’en-tête affichera un message d’erreur.) |
Accept-Language GET POST | « fr-CA » ou « en-CA » (Facultatif) | Indique la langue de préférence du message d’erreur que peut lire un être humain (si une erreur est générée). |
If-None-Match GET | Facultatif (Facultatif) | Peut être inclus à la requête si un précédent message GET a été mis en cache. « 304 – not changed » ou la nouvelle version de la ressource sera retournée. |
Structure de la réponse HTTP
La forme générale d’une réponse HTTP aux interfaces API de Postes Canada contient les en-têtes standard suivants :
Status Code: 200 OK
Date: Wed 06 Jul 202317:21:53 GMT
Content-Type: application/json
Etag: "6"
{body}Structure des messages d’erreur
La structure des messages d’erreur (le cas échéant) remplace la structure normale de la réussite.
Exemple de réponse JSON à une condition d’erreur
HTTP/1.1 403 Content-type:application/vnd.cpc.shipment+json
"messages": [
{
"code": "7007",
"description": "The weight value is invalid. The weight of each piece must be less than or equal to 30 kg."
},
{
"code": "1722",
"description": "The options are invalid for the selected Service. Please change the options or select another service."
}
]Versionnage
Pour ce qui touche le versionnage, veuillez consulter nos notes de version.
Utilisation des fichiers OpenAPI
Toutes les requêtes et les réponses liées aux interfaces API sont validées par rapport à un fichier OpenAPI correspondant. Les fichiers de définition OpenAPI sont utiles pour générer un code ou pour valider les requêtes JSON du côté de la clientèle avant de faire un appel. Les fichiers OpenAPI ont été utilisés pour générer les échantillons de code. Pour télécharger les fichiers OpenAPI, consultez la documentation sur l’interface API respective et sélectionnez le lien Télécharger le document OpenAPI.