Principes de base liés au module SOAP pour les services Web
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 du protocole 1.1 du module SOAP.

Consultez les cas d'utilisation typiques.

Avant de commencer les travaux d'intégration...

1. Lisez la section Avant de commencer... 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 liés au module SOAP pour les services Web 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 Web.
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 SOAP pour établir un lien avec les services Web

Le format général pour toute interface de service Web de Postes Canada (module SOAP) est illustré ci-dessous. Pour obtenir de plus amples renseignements sur les demandes de service, veuillez consulter le répertoire de services.

Espaces de nommage

Une enveloppe SOAP précise toujours :

• l'espace de nommage de la définition du message SOAP en question;
• l'espace de nommage de l'interface précise faisant l'objet de la demande.

Il existe différents espaces de nommage liés aux interfaces pour diverses catégories de service. L'espace de nommage est propre à la version précise de l'interface faisant l'objet de la demande. Veuillez prendre note des éléments suivants concernant l'espace de nommage :

• Le format des attributs de l'espace de nommage de l'enveloppe est « xmlns:prefix="URI" ».
• L'élément « prefix » est ensuite utilisé dans le message à titre de référence pour l'espace de nommage.
• Les entrées « URI » ne constituent pas nécessairement une URL adressable. Il faut récupérer les ressources WSDL au lieu de tenter d'utiliser les entrées URI.
• Lorsqu'un espace de nommage a été désigné explicitement, tous les éléments enfants de la balise déclarant que l'espace de nommage est présumé être présent dans le même espace. Souvent, la balise de niveau supérieur précisera le préfixe de l'espace de nommage et les balises subséquentes ne feront pas référence à l'espace de nommage.

Exemple

En-tête (Sécurité)

Les demandes de service Web de Postes Canada exigent que des mesures de sécurité soient prises avec l'élément
« UsernameToken » dans lequel votre code d'usager et votre mot de passe sont précisés. De nombreux programmes utilitaires (p. ex. soapUI) formeront l'en-tête XML pour vous si vous fournissez les attributs de votre code d'usager et de votre mot de passe. L'en-tête est vide dans la réponse selon le module SOAP.

Corps

La première balise suivant l'élément du corps de l'enveloppe correspond à l'élément XML de niveau supérieur de la demande ou de la réponse. Consultez les pages de référence propres aux demandes de service pour obtenir de plus amples renseignements sur le formatage des éléments pour chaque demande et l'interprétation des éléments pour chaque réponse.

Demandes de service asynchrones à plusieurs volets

Bon nombre des services Web sont asynchrones et affichent les renseignements immédiatement lorsqu'une tâche est exécutée en arrière-plan. Par exemple :

1. Vous présentez une demande d'étiquettes d'expédition.
2. Les renseignements concernant l'étiquette en format PDF s'affichent avant que la production de l'étiquette soit terminée.
3. Le numéro d'identification de l'étiquette d'expédition fourni dans la réponse est utilisé en tant que donnée d'entrée dans une deuxième demande pour récupérer l'étiquette en format PDF.
4. La deuxième demande affiche la structure du message d'erreur jusqu'à ce que l'étiquette en format PDF soit disponible.

Types de demandes de service

Les demandes de service peuvent être exécutées en répétant deux ou trois fois les données, ou une demande de service peut être répétée avec les résultats enregistrés dans votre application, suivis de la répétition de la deuxième partie. Consultez la section Types de demandes de service uniques et regroupées. Une série de recherches ou de demandes de synchronisation/récupération est disponible si le dossier d'un client léger est en cours d'élaboration. La forme au pluriel est toujours employée pour ces demandes de service (p. ex. « Obtenir les envois »).

Traitement des erreurs

Le code HTTP « 200 » s'affichera pour les transactions réussies ou celles dont le schéma est valide, mais qui éprouvent des problèmes de validation de l'application.

Il faut vérifier la réponse XML pour déterminer quelle branche de la réponse s'affiche, soit le message pour la réussite complète (réponse) ou la réussite partielle (messages). Consultez le diagramme ci-dessous pour obtenir un aperçu général des deux branches. En général, si l'élément <messages> existe, le reste du message doit être traité selon la logique du message d'erreur de votre application. S'il n'existe pas, il faut traiter les données de la réponse selon la logique de votre réussite.

Les erreurs de statut « 200 » sont fonction de la présence de l'élément <messages> au deuxième niveau de la réponse.

Code de statut HTTP	Code	Commentaires
200
	Codes à quatre chiffres	Les erreurs d'application comportent quatre chiffres. Pour obtenir de plus amples renseignements sur les messages précis, consultez la section Messages d'erreur et stratégies d'atténuation. Les erreurs du système comptent trois chiffres, comme il est indiqué ci-dessous.
	202	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 ».
	404	L'information demandée n'est pas encore prête (réessayer plus tard) ou elle n'est plus disponible. (Les nouvelles demandes d'étiquettes sont produites de façon asynchrone et les anciennes demandes sont supprimées après 90 jours.)

Les erreurs graves, notamment les échecs d'authentification ou les erreurs de validation du schéma, entraîneront le code d'erreur HTTP
« 500 ». Une anomalie du module SOAP s'affichera. L'élément <faultcode> pour les problèmes d'authentification sera propre au type d'erreur. Les erreurs de validation du schéma seront assorties d'un élément <faultcode> générique pour le « serveur ». En tant que développeur, vous obtiendrez dans les deux cas des renseignements sur le diagnostic par l'entremise de l'élément <faultstring> afin que vous puissiez remédier à la situation avant le lancement de l'application.

Les erreurs de statut « 500 » sont fonction de l'élément <SOAP-ENV:Fault> immédiatement après l'élément
<SOAP-ENV:Body>

Code de statut HTTP	faultcode	Commentaires
500
	AA001	Le code d'usager pour la demande a été désactivé. Si vous vous êtes désinscrit du Programme pour développeurs, veuillez vous y inscrire de nouveau.
	AA002	Le code d'usager et le mot de passe de la demande ne correspondent pas au point final (p. ex. la clé de développement par rapport au point final de production ou vice versa).
	AA003	La clé API figurant dans l'en-tête « Authorisation » ne correspond pas au numéro de client « Expédié par » dans la demande.
	AA004	Vous ne pouvez pas effectuer l'expédition au nom du client demandé.
	Serveur	Les détails liés aux erreurs du schéma sont décrits dans l'élément « faultstring ».
	env:Client	Le point final n'est pas défini correctement. Veuillez le corriger et le soumettre de nouveau.

Environnements des services Web

Deux environnements de services Web 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 Web en utilisant :

• votre code d'usager et votre mot de passe pour le développement ou la production;
• le point final de développement ou de production correspondant.

Nota : Le code d'anomalie « AA002 » s'affichera si vous utilisez les mauvais éléments d'identification 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
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 » figurent dans les exemples de codes et les exemples de schémas du projet soapUI à l'adresse par défaut « 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 entreprises^MC 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 sont les mêmes que ceux de l'environnement « Bac à sable », mais sans la valeur
« ct. » dans l'adresse « https://soa-gw.postescanada.ca ».

É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 WSDL (version 1.1)

De nombreux outils se servent des fichiers WSDL (version 1.1) comme données d'entrée. Les fichiers WSDL ont été saisi dans les programmes utilitaires de génération de codes à titre de point de départ pour les exemples de codes Java et .NET. Le programme utilitaire SoapClient (PHP) se sert des fichiers WSDL au cours de l'exécution. Les exemples du module soapUI ont été générés en fonction des fichiers WSDL à titre de point de départ.

Les fonctions des services Web de Postes Canada sont consignées dans 11 fichiers WSDL. différents. Chaque fichier WSDL contient une ou plusieurs fonctions des services Web.

Comment les fichiers WSDL sont utilisés