Principes de base liés au module REST pour les services en ligne
de Postes Canada

i

  • Effectuez votre essai dans l'environnement « Bac à sable » (développement). Tous les envois et les commandes que vous soumettez dans l'environnement de production vous seront facturés. Apprenez-en davantage.

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

  1. Lisez la section Premières étapes pour apprendre comment vous inscrire et comment obtenir vos clés API.
  2. 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.
  3. 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.
  4. 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.

REST request diagram

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
(relation avec le lien)

Indique la ressource associée à la réponse actuelle.

href
(référence au lien hypertexte)

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
(optionnel)

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

  • Le mot « Basic » est une valeur littérale qui doit être présente.
  • Le mot « Basic » est suivi d'une seule espace.
  • L'espace est suivie de la clé API comme chaîne d'octets codée en base64
    (52 caractères).
  • La chaîne codée est générée à partir de la clé API (soit une concaténation du code d'usager, de deux points et du mot de passe).
  • Pour obtenir un exemple de programme utilitaire pouvant générer une chaîne codée en base64 à partir de votre code d'usager et de votre mot de passe, consultez le document Outils de mise à l'essai.

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
« GET » précédent a été antémémorisé. La valeur « 304 – not changed » ou la nouvelle version de la ressource s'affichera.

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
(p. ex., la suppression a été effectuée avec succès).

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.

Message diagram

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.