Principes de base liés au module REST pour les services en ligne
de Postes Canada
Les solutions de Postes Canada permettent aux fournisseurs de solutions pour le cybercommerce et aux commerçants en ligne d'intégrer les services de Postes Canada, notamment l'expédition, la tarification et le repérage, à une plate-forme ou à un site Web. Une fois qu'ils sont intégrés, votre application accédera aux serveurs de Postes Canada en se servant d'un style d'architecture REST (XML).
Consultez les cas d'utilisation typiques.
Avant de commencer les travaux d'intégration
- Lisez la section Premières étapes pour apprendre comment vous inscrire et comment obtenir vos clés API.
- Passez en revue les renseignements fournis dans le présent document intitulé Principes de base des services de Postes Canada. Il présente en détail l'information essentielle commune à tous nos services.
- Lancez notre application type pour mettre à l'essai votre accès à nos services et déterminer les données acheminées (et retournées) par nos services Internet.
- Lisez les descriptions fonctionnelles et techniques détaillées pour chacun de nos services Internet énumérés dans le répertoire de services.
Utilisation du module REST pour établir un lien avec les services Internet
Le format général pour toute demande REST est illustré ci-dessous. Consultez le répertoire de services pour obtenir des détails sur les demandes de service.
Points finaux
Vous utiliserez les deux types de points finaux suivants pour accéder aux services de Postes Canada :
- Points finaux créés par votre code d'application
- Points finaux fournis dans les réponses XML aux demandes précédentes
Un nom pratique a été donné à chaque point final à titre de référence. Ce nom n'apparaît pas directement dans le point final.
Familiarisez-vous avec les noms de référence. Lorsqu'il faut préciser un point final en saisissant seulement son code d'application, consultez les documents du répertoire de services pour obtenir des détails sur chaque point final ou exemple de code.
Points finaux créés
Les points finaux créés contiennent une adresse URL fixe et peuvent également contenir des éléments variables. Le point final du service Obtenir les manifestes est présenté ci-dessous.
Exemple de point final (selon la documentation) du service Obtenir les manifestes :
XX/rs/{Client « Expédié par »}/{Client « Expédié au nom de »}/Manifeste
?Début=AAAAMMJJ&Fin=AAAAMMJJ
Remplacez {Client « Expédié par »} par votre numéro de client.
Remplacez {Client « Expédié au nom de »} par le numéro de client « Expédié au nom de » ou indiquez de nouveau votre numéro de client.
Remplacez « AAAAMMJJ » par les dates de début et de fin.
Exemple de point final (avec les valeurs variables définies) :
GET https://ct.soa-gw.canadapost.ca/rs/123456789/123456789/manifest?start=20100324&endDate=20100405
Variables du point final créé
Il existe deux types d'éléments variables :
- « Domaine » de la demande – Par exemple :
- Numéro du client « Expédié par »
- Numéro du client « Expédié au nom de » associé à la demande
- Chaîne de requête de la demande
- Un ou plusieurs paramètres de requête pouvant s'avérer nécessaires sont inclus selon le service faisant l'objet de la demande.
Variables du domaine : Client « Expédié par » et client « Expédié au nom de »
Le domaine pourrait être fixe pour toutes vos demandes de service si votre application agit au nom d'un seul client. Dans les documents détaillés propres au service, les variables du domaine sont représentées à l'intérieur des accolades. Par exemple :
- {Client « Expédié par »} signifie que votre application doit fournir votre numéro de client.
- {Client « Expédié au nom de »} signifie que votre application doit fournir le numéro de client de l'entité pour laquelle vous effectuez l'expédition, c'est-à-dire le client « Expédié au nom de ». Si vous n'effectuez pas l'expédition au nom de personne, indiquez de nouveau votre numéro de client.
Les variables du domaine sont protégées de la même manière que le corps de la demande XML selon la connexion HTTPS.
Chaîne de requête
Le cas échéant, la chaîne de requête variera selon vos besoins actuels concernant votre application. Par exemple, la chaîne de requête pourrait transférer les données d'entrée de l'utilisateur propre au code postal à la demande de service Obtenir le bureau de poste le plus près. À interpréter correctement, une chaîne de requête ne peut pas contenir d'espaces vides. Les espaces vides peuvent toutefois être remplacées par %20 (p. ex. l'espace entre les deux parties du code postal).
La chaîne de requête est protégée de la même manière que le corps de la demande XML selon la connexion HTTPS.
Points finaux fournis
L'interface applicative (API) de Postes Canada fournit des points finaux générés de façon dynamique en tant que réponse à une demande de service en ligne précédente. Dans ces cas, vous devriez utiliser le point final tel qu'il a été reçu et vous ne devriez pas tenter de l'analyser ni de le définir.
Tous les services Internet de Postes Canada utilisés par les points finaux fournis doivent être assortis de la méthode HTTP GET et n'ont pas besoin du corps XML.
Les points finaux fournis sont décrits dans l'élément de réponse XML intitulé « Lien ». Vous trouverez ci-dessous le format de l'élément du lien.
<link rel="{rel-indicator}" href="{endpoint URL and query string}" media-type="{media-type index="{xx}" >
Attributs du lien des points finaux fournis
| Attribut du lien | Signification |
|---|---|
rel |
Indique la ressource associée à la réponse actuelle. |
href |
Désigne le point final à utiliser pour présenter une demande de service en ligne. Il contient l'adresse URL et peut également contenir une chaîne de requête. |
media-type |
Il s'agit d'une chaîne de caractères indiquant le format et la version des données prévus lorsqu'un service Internet est utilisé. La valeur de cet attribut doit être copiée dans la variable de l'en-tête HTTP « Accept » lorsque le lien href est utilisé. |
index |
Fait partie des liens vers les données de sortie formatées, comme les étiquettes. La valeur de la première page est de « 0 », et cette valeur augmente de un pour chaque page subséquente (le cas échéant). |
Types de demandes de service
La première interaction avec l'API de Postes Canada sera effectuée par l'entremise d'un point final créé. De façon générale, les autres interactions feront appel aux points finaux créés jusqu'à ce que tous les renseignements liés à la demande de service initiale soient récupérés. Il est possible d'utiliser deux types courants. Consultez la section Types de demandes de service uniques et regroupées.
Si, en tout temps pendant le traitement, votre application tombe en panne et que vos liens stockés sont perdus, il est possible de les récupérer grâce aux demandes de synchronisation.
Variables des en-têtes HTTP
Les variables des en-têtes HTTP obligatoires doivent être fournies pour chaque demande. La priorité absolue est la valeur de l'autorisation utilisée pour authentifier chaque demande.
| Variables des en-têtes HTTP | Méthodes applicables | Requis/Optionnel | Valeur | Description |
|---|---|---|---|---|
Authorization |
GET, POST, DELETE |
Requis |
Code d'usager de base : Mot de passe |
|
Content-Type |
POST |
Requis |
Unique par groupe de service. Consultez les documents liés au service pour obtenir plus de détails. |
Il s'agit de la version XML du corps de la demande que vous envoyez dans POST. (Remarque : */* à la place de la valeur de l’en-tête affichera un message d’erreur) |
Accept |
GET |
Requis |
Unique par groupe de service. Consultez les documents liés au service pour obtenir plus de détails ou utilisez le « type de média » du lien fourni. |
Il s'agit de la version XML de la réponse que vous prévoyez recevoir. (Remarque : */* à la place de la valeur de l’en-tête affichera un message d’erreur) |
Accept-Language |
GET, POST |
Optionnel |
« fr-CA » ou « en-CA » |
Indique la langue de préférence du message d'erreur lisible par un humain (si une erreur est générée). |
If-None-Match |
GET |
Optionnel |
Selon la valeur de la balise-entité ETag de la réponse initiale. |
Pourrait être inclus dans la demande si un |
Structure de la réponse HTTP
Le format général d'une réponse HTTP aux demandes de services Internet de Postes Canada contient les en-têtes standard suivants :
Code de statut : 200 OK
Date : Le mercredi 6 juillet 2011 (17 h 21 min 53 s [UTC])
Content-Type: application/vnd.cpc.shipment+xml
Etag: "6"
{Corps du message}
Codes de statut HTTP
Le code de statut HTTP qui s'affiche indique la réussite ou l'erreur de la demande, tel qu'il est décrit ci-dessous.
| Codes de statut HTTP | Réussite/Erreur | Contenu du corps | Marche à suivre |
|---|---|---|---|
200 |
Réussite |
Selon le service précis (voir les documents de service individuels) |
Traitez les détails dans le corps du message. |
202 |
Essayez plus tard |
Structure du message d'erreur |
La ressource demandée n'est pas encore disponible. Veuillez réessayer plus tard. Exemple : Une fois la demande « Créer l'envoi sans convention » soumise, il y aura un délai d'environ une seconde avant que vous puissiez récupérer l'étiquette d'expédition par l'entremise du service « Obtenir l'artefact ». |
204 |
Réussite |
Aucun |
Aucune mesure n'est requise |
304 |
Réussite |
Aucun |
Utilisez la version stockée des données. (La ressource n'a pas été modifiée. Il faut l'utiliser en combinaison avec la balise-entité ETag et l'en-tête « If-None-Match »). |
400 |
Erreur |
Structure du message d'erreur |
Code = Serveur Une demande n’a pas réussi la validation du schéma. La description contient un message détaillé pour vous aider à régler le problème. De telles erreurs ne devraient se produire que pendant la phase de développement et être résolues avant que toute application ne devienne opérationnelle. |
Erreur |
Structure du message d'erreur |
Code = Numérique Si le code est numérique, l’erreur pourrait être corrigée par un utilisateur final, grâce à un IU souple, ou par le développeur sous la forme de sélections logiques, de filtres ou de validations par l’application avant l’envoi de la demande. Voir la liste des erreurs que vous pouvez minimiser d’avance. |
|
401 |
Erreur |
Structure du message d'erreur |
Corrigez la clé API dans l'en-tête « Autorisation ». |
403 |
Erreur |
Structure du message d'erreur |
AA001 – La clé API dans l’en-tête « Autorisation » a été désactivée. Si vous vous étiez retiré du programme pour développeurs, joignez-le de nouveau. |
Erreur |
Structure du message d'erreur |
AA002 – Corrigez la clé API dans l'en-tête « Autorisation ». Cela signifie que vous avez utilisé une clé API de développement par rapport à la production ou vice versa. |
|
Erreur |
Structure du message d'erreur |
AA003 – La clé API dans l’en-tête « Autorisation » ne correspond pas au numéro Expédié par le client indiqué dans la demande. Le chemin des ressources est incorrect ou la ressource n’est plus disponible. Si reçu pour une ressource récemment créée, réessayez plus tard. |
|
Erreur |
Structure du message d'erreur |
AA004 - Vous ne pouvez pas expédier au nom du client demandé. |
|
404 |
Erreur |
Structure du message d’erreur |
(p. ex., l'artefact n'a pas encore été créé). |
406 |
Erreur |
Structure du message d'erreur |
La version de l’interface devant être retournée par la demande (GET) n’est pas valide ou documentée. Changer la variable de l’en-tête "accept". |
412 |
Erreur |
Structure du message d'erreur |
Il s'agit d'une erreur inattendue indiquant qu'une condition préalable à un envoi en une seule étape a échoué. Cela peut se produire à la suite d'un processus non synchronisé côté serveur. L'action de l'utilisateur consiste à vérifier les données d'entrée et à répéter la transaction après un court laps de temps. S'il échoue à nouveau, signalez-le. |
415 |
Erreur |
Structure du message d'erreur |
La version de l’interface indiquée dans la demande (POST) n’est pas valide ou documentée. Changer la variable de l’en-tête "content-type". |
500 |
Erreur |
Structure du message d'erreur |
Corrigez l'erreur liée au schéma XML selon le message détaillé. |
Structure du message d'erreur
La structure du message d'erreur (s'il s'affiche) remplace la structure de réussite normale. La structure du message d'erreur est présentée ci-dessous.
Exemple de réponse XML à une condition d'erreur
HTTP/1.1 403
Content-type:application/vnd.cpc.shipment+xml
<messages>
<message>
<code>7007</code>
<description> The weight value is invalid. The weight of each piece must be less than or equal to 30 kg.</description>
</message>
<message>
<code>1722</code>
<description> The options are invalid for the selected Service. Please change the options or select another service.</description>
</message>
</messages>
Environnements des services Internet
Deux environnements de services Internet sont à votre disposition :
- Bac à sable (développement) : Il est utilisé pour la mise à l'essai des codes.
- Production : Il est utilisé dans l'environnement de production.
Sélectionnez l'environnement du service Internet en utilisant :
- votre clé API de développement ou de production dans l'en-tête « Autorisation »;
- un point final de développement ou de production.
Nota : Le code de statut HTTP 403 s'affichera si vous utilisez la mauvaise clé API pour le point final sélectionné.
Environnement « Bac à sable » (développement)
Utilisez votre clé de développement dans l'environnement « Bac à sable ». L'environnement « Bac à sable » est une réplique de l'environnement de production et comprend des données d'essai/réponses valides, à l'exception des éléments suivants :
| Élément | Apparaît dans les réponses provenant de : | Valeurs des réponses dans l'environnement « Bac à sable » |
|---|---|---|
| Élément tracking-pin | Créer l'envoi Obtenir les détails de l'envoi |
123456789012 |
| Élément return-tracking-pin | Créer l'envoi | 123456789012 |
| Élément po-number | Créer l'envoi Obtenir les détails de l'envoi Obtenir les détails du manifeste Obtenir le manifeste |
P123456789 |
| Lien rel="receipt” | Créer l'envoi | Ce lien n'est pas affiché dans l'environnement « Bac à sable » |
| Artefacts, tels qu'étiquettes d'expédition, étiquettes de retour et manifestes | Obtenir l'artefact | Il est clairement indiqué que les étiquettes et les manifestes sont utilisés uniquement aux fins de mise à l'essai. Ils ne doivent donc pas être utilisés pour un envoi réel. |
| Services Web : Repérage | Obtenir un résumé du repérage Obtenir les détails de repérage Obtenir l'image de la signature Obtenir le certificat de confirmation de livraison |
Peu importe le numéro de repérage que vous soumettez dans la demande aux services Web « Repérage », la réponse « Aucun historique pour le NIP » s'affiche. Pour mettre à l'essai un ensemble complet de scénarios de suivi, utilisez les NIP de suivi de production dans l'environnement de production. (Pour mettre à l'essai un élément introuvable, utilisez un NIP invalide.) |
| Élément public-key-info url | Créer un retour autorisé |
Un ensemble de clés API valides est nécessaire pour afficher l’étiquette dans le navigateur. Google Chrome pourrait ne pas afficher l’étiquette en mode plein écran, en raison d’un bogue connu dans le navigateur. |
Points finaux de l'environnement « Bac à sable »
Les points finaux de l'environnement « Bac à sable » se trouvent dans des exemples de codes et dans les documents détaillés propres au service. Pour les points finaux de l'environnement « Bac à sable », XX = https://ct.soa-gw.postescanada.ca.
Mise à l'essai des valeurs pour l'expédition avec convention, la tarification et les renvois
Si vous n'êtes pas un client commercial de Postes Canada titulaire d'une convention, mais que vous mettez en place une solution d'expédition par tierce partie à l'intention des clients commerciaux, utilisez les numéros ci-dessous pour mettre à l'essai l'expédition avec convention et les services Web de renvoi. Veuillez prendre note des éléments suivants :
- Ces numéros ne sont valides que dans l'environnement « Bac à sable ».
- Vous devez être un client du programme Solutions pour petites entreprisesMC pour utiliser ces numéros d'essai. Inscrivez-vous dès aujourd'hui.
- Plusieurs clients de Postes Canada utiliseront les mêmes numéros. Pour éviter toute confusion, assurez-vous de créer vos propres numéros d'identification de groupe lorsque vous créerez vos envois. Apprenez-en davantage sur les numéros d'identification de groupe.
- Nous avons créé une carte de crédit pour l'exécution d'une mise à l'essai par défaut afin de vous permettre de mettre à l'essai les transactions par carte de crédit.
- Pour obtenir les tarifs commerciaux liés à la mise à l'essai, dans votre demande pour obtenir des tarifs, vous devez inclure le numéro du client et le numéro d'identification de la convention.
- Les tarifs que vous obtiendrez ne sont donnés qu'à des fins d'essai.
| Nom de l'élément/clé | Textes pour l'environnement « Bac à sable » |
|---|---|
| Customer-number | 2004381 |
| Contract-id | 42708517 |
| Clé API | 6e93d53968881714:0bfa9fcb9853d1f51ee57a |
Mise à l'essai de valeur pour le code promotionnel
Le code promotionnel DEVPROTEST peut être utilisé pour la mise à l’essai des fonctions dans l’environnement « bac à sable ». Ce code promotionnel est uniquement valide dans l’environnement « bac à sable » et pour les produits suivants :
- Xpresspost (DOM.XP)
- Xpresspost International (INT.XP)
Environnement de production
Une fois que votre application a été mise à l'essai avec succès dans l'environnement « Bac à sable », vous pouvez changer votre clé API pour la clé de production et faire passer les points finaux à des points finaux de production.
Mettez à l'essai les points finaux qui ne sont pas assujettis à des frais en premier, tels que ceux qui font partie des services Tarification, Repérage et Trouver un bureau de poste. Si vous créez des envois à titre d'essai, présentez une demande de service « Annuler l'envoi » pour ces envois avant de présenter une demande de service « Transmettre les envois » afin d'éviter qu'ils soient assujettis à des frais.
Points finaux de l'environnement de production
Les points finaux de l'environnement de production commencent par « https://soa-gw.postescanada.ca ». Vous trouverez plus de détails dans les documents propres à chacun des services.
Étiquettes thermosensibles de format ZPL II – Exigence liée à la troncature
Si vous imprimez des étiquettes thermosensibles de format ZPL II, votre imprimante doit avoir la capacité de tronquer du texte. Sans cette capacité, vous risquez d'imprimer par-dessus des renseignements importants figurant sur les étiquettes d'expédition de Postes Canada. Vérifiez votre imprimante pour vous assurer qu'elle peut tronquer du texte. Les imprimantes Citizen, par exemple, de même que les imprimantes Zebra avec un micrologiciel plus ancien, ne permettent pas la troncature. Vous pouvez tester votre imprimante à l'aide de notre exemple de code ci-dessous.
Exemples de codes à envoyer à votre imprimante thermique
Copiez et collez le code ci-dessous dans le programme de service fourni par le fabricant de l'imprimante, et imprimez une étiquette thermosensible.
^XA
^CI13
^MMT
^PW812
^LL1218
^LS0
^FO63,63^A0N,25,20^FDThe text below should not spill out of the box^FS
^FO127,127^A0N,25,20^TBN,190,25^FDthistextshouldnotspilloutofthebox^FS
^FO121,121^GB197,32,1^FS
^PQ1,0,1,Y
^XZ
Résultats de l'imprimante
Si votre imprimante permet la troncature, une boîte dans laquelle apparaîtra le texte tronqué sera imprimée, tel qu'il est montré ci-dessous :
Si votre imprimante ne permet pas la troncature, le texte s'étend en dehors de la boîte, tel qu'il est montré ci-dessous :
Si votre imprimante ne permet pas la troncature, nous vous recommandons d'utiliser plutôt le format PDF pour les étiquettes. Pour obtenir plus de détails, reportez-vous à l'élément de codage : REST | SOAP.
Contrôle des versions
Veuillez consulter notre page sur la stratégie de contrôle des versions.
Utilisation des fichiers XSDs
Toutes les demandes de service en ligne et les réponses connexes sont validées en fonction d'un schéma correspondant. Les fichiers XML Schema Definiton (XSD) sont utiles pour générer des codes ou valider les demandes XML du client avant de présenter une demande de service. Les fichiers XSD sont utilisés pour générer des catégories de données dans des exemples de codes. Télécharger les fichiers XSD.
