Résumé du service

Utilisez les services Web propres aux plates-formes si vous disposez d'une plate-forme de cybercommerce et que vous voulez inscrire vos clients commerçants aux services de Postes Canada afin qu'ils puissent expédier leurs envois à partir de votre plate-forme.

Inscription d'un commerçant aux services de Postes Canada

Le diagramme ci-dessous offre un aperçu de la marche à suivre pour l'inscription des commerçants aux services Web.

Inscription d'un commerçant aux services de Postes Canada

Services de plate-forme

Les services de plate-forme sont fournis par l'entremise des demandes de service suivantes.

1. Obtenir le jeton d'inscription
   du commerçant
   REST   |    SOAP Utilisez ce service pour obtenir un jeton d'inscription unique (token-id) requis pour entamer le procédé d'inscription d'un commerçant aux services de Postes Canada.
2. Obtenir l'information sur l'inscription
   du commerçant
   REST   |    SOAP Ce service affiche les renseignements du commerçant, notamment son numéro de client ainsi que son code d'usager et son mot de passe requis pour l'utilisation des services Web. Vous avez besoin de ces renseignements pour effectuer les transactions d'expédition du service Web au nom du commerçant.

Détails liés à la programmation

1. Si l'un de vos utilisateurs commerçants souhaite expédier ses envois à l'aide des services de Postes Canada et s'il est prêt à entamer le procédé d'inscription de Postes Canada à l'aide de votre session de navigation authentifiée :
   
   • Présentez une demande de service Web « Obtenir le jeton d'inscription du commerçant » de Postes Canada en vous servant du point final pertinent.
     • Module REST : POST https://soa-gw.postescanada.ca/ot/token
     • Module SOAP : https://soa-gw.postescanada.ca/ot/soap/merchant/registration
   • Associez la réponse à cette demande avec votre propre numéro d'identification unique du commerçant sur votre système.

   Nota : Le token-id n'est valide que pendant 30 minutes, et ce, à compter du moment où il est émis, y compris le temps pris par un commerçant pour s'inscrire aux services de Postes Canada.

2. Affichez les champs suivants à l'adresse URL suivante pour entamer la séance d'inscription aux services de Postes Canada :
   

   Environnement production : https://www.canadapost-postescanada.ca/information/app/drc/commercant

   Environnement pour test : https://www.canadapost-postescanada.ca/information/app/drc/testcommercant

   Obligatoire	Optionnel
   return-url * (fonction de rappel à votre système) token-id (pour renvoyer à l'utilisateur intéressé) platform-id (votre numéro de client)	first-name last-name address-line-1 prov-state postal-zip-code country-code email city

   *Votre adresse URL doit être complète. Postes Canada n'y ajoutera rien.

3. Nous vous redirigerons vers la page précisée dans votre return-url. Nous passerons les deux prochains paramètres de requête assortis de l'option GET à la page en question.
   
   • token-id
   • registration-status (sera l'une des options suivantes : SUCCESS, CANCELLED, BAD_REQUEST, UNEXPECTED_ERROR, UNAUTHORIZED and SERVICE_UNAVAILABLE)
4. Montrez le message concernant l'état d'avancement à votre commerçant.
5. Si le statut d'inscription est OK, passez à la prochaine étape. Si le statut est Cancelled, veuillez aviser le commerçant que vous ne pourrez pas soumettre ses demandes tant qu'il n'aura pas accepté les modalités, mais que sa relation avec Postes Canada reste en vigueur. S'il s'agit d'une autre option, cela signifie qu'une erreur s'est produite. Veuillez réessayer plus tard.
6. Échangez le jeton pour le code d'usager et le mot de passe du commerçant en faisant appel au service Web « Obtenir l'information sur l'inscription du commerçant » de Postes Canada en vous servant du point final pertinent.
   • Module REST : GET https://soa-gw.postescanada.ca/ot/token/{token-id}
   • Module SOAP : https://soa-gw.postescanada.ca/ot/soap/merchant/registration
7. Associez la réponse à cette demande avec votre propre numéro d'identification unique du commerçant sur votre système. Sauvegardez la clé API du commerçant (nom d'utilisateur et mot de passe) sur votre serveur. Le token-id n'est plus utile, mais le code d'usager et le mot de passe du commerçant vous permettront de soumettre les services Web au nom du commerçant inscrit.
8. Mettez à l'essai le code d'usager et le mot de passe du commerçant en faisant appel à un service Web qui n'occasionne aucun coût (p. ex. « Obtenir les tarifs » ou « Obtenir l'information sur les clients ») pour déterminer s'ils fonctionnent de bout en bout.
9. Transmettez les demandes HTTPS en cours du commerçant par l'entremise de votre serveur et ajoutez la clé API liée à votre plate-forme ainsi que la clé du commerçant appropriée.

Éléments essentiels pour la demande

• Les demandes de service présentées au nom d'un commerçant ne sont acceptées que par les points finaux de l'environnement de production. L'erreur d'autorisation AA002 (mauvais environnement) s'affichera pour les demandes de service présentées avec le code d'usager et le mot de passe du commerçant dans l'environnement d'essai.
• Protégez la sécurité de la clé API de votre plate-forme (code d'usager et mot de passe) en la conservant sur le serveur de votre côté.
• Avant de procéder à l'inscription d'un commerçant, vérifiez que son compte est en règle.
• Prendre note des éléments suivants concernant les numéros de client :
  • Même si vous présentez une demande de service au nom d'un commerçant, son numéro de client est placé dans l'élément
    mailed-by. Le numéro de client « Expédié au nom de » est une répétition du numéro de client du commerçant (sauf si le commerçant a déjà conclu une entente avec un autre client).
  • Entrez le numéro de client de votre plate-forme dans l'élément de la demande nommé platform-id.
  • La valeur de l'élément platform-id doit être identique au numéro de client utilisé pour inscrire le commerçant, c'est-à-dire le numéro de client associé au code d'usager du service Web ayant authentifié la demande d'inscription.

Demande de service Web selon le module SOAP au nom des commerçants

Pour les demandes de service selon le module SOAP, placez l'élément <platform-id> au niveau supérieur de chaque demande (p. ex. au même niveau que les éléments « locale » et « mailed-by »).

Demande de service Web selon le module REST au nom des commerçants

Chaque fois que vous présentez une demande de service selon le module REST au nom du commerçant, vous devez inclure l'élément Platform-Id dans l'en-tête HTTP.

De plus, si l'adresse URL de la demande REST comprend le numéro de client « Expédié par », vous devez également ajouter un trait d'union et votre platform-id à ce numéro. Le non-respect de cette consigne entraînera une erreur d'authentification. Cette approche sépare les données d'un même commerçant sur plusieurs plates-formes. Consultez la liste de demandes de service selon le module REST touchées ci-dessous.

Exemples de demandes de service selon le module REST pour les plates-formes

• Code « 1111111 » = Numéro de client du commerçant
• Code « 1234567 » = Votre numéro de client/platform-id
• Code d'usager = merchant-username
• Mot de passe = merchant-password

Les valeurs susmentionnées s'affichent par l'entremise du service Web « Obtenir l'information sur l'inscription du commerçant », puis elles sont enregistrées sur votre système.

Nota : Vous pouvez toujours utiliser le champ <group-id> pour regrouper les envois de l'utilisateur dans votre plate-forme. Le chevauchement des valeurs group-id des autres plates-formes n'est pas une préoccupation puisque l'identificateur mailed-by est un séparateur de niveau supérieur.

Adresses URL des demandes REST incluant le numéro de client « Expédié par »

Vous devez ajouter un trait d'union et votre platform-id au numéro de client « Expédié par » pour les demandes de service ci-dessous.

Expédition

Créer l'envoi

Obtenir les groupes

Obtenir l'envoi

Obtenir les détails de l'envoi

Obtenir le tarif de l'envoi

Obtenir les envois

Annuler l'envoi

Manifeste

Transmettre les envois

Obtenir le manifeste

Obtenir les manifestes

Obtenir les détails du manifeste

Expédition sans convention

Créer l'envoi sans convention

Obtenir le reçu de l'envoi sans convention

Obtenir les détails de l'envoi sans convention

Obtenir les envois sans convention

Obtenir l'envoi sans convention

Envois retournés

Créer un retour autorisé

Créer un modèle générique pour les envois retournés

Obtenir le modèle générique pour les envois retournés

Supprimer le modèle générique pour les envois retournés

Obtenir les modèles génériques pour les envois retournés

Renseignements sur le client

Obtenir l'information sur les clients

Obtenir l'information sur les clients « Expédié au nom de »

Dimensions

Les dimensions (p. ex. hauteur, largeur et longueur du colis) permettront aux commerçants d'obtenir des coûts d'expédition plus précis. Si les dimensions ne sont pas transférées à l'API de Postes Canada, le commerçant pourrait être assujetti à des frais supplémentaires en plus du tarif établi en fonction du poids. Cela se produit surtout pour les grandes boîtes dont le contenu est léger.

Message d'avertissement pour les commerçants

Nous vous recommandons de montrer le message d'avertissement suivant aux commerçants avant qu'ils impriment une étiquette ou qu'ils transmettent un manifeste :

Veuillez noter que l'information fournie à Postes Canada est soumise à une vérification. Par conséquent, si les articles présentés à Postes Canada ne correspondent pas à l'information fournie (catégorie, volumes, préparation et poids incorrects, frais supplémentaires manquants, etc.), les tarifs pourraient être ajustés ou des frais supplémentaires pourraient être appliqués conformément à la convention conclue entre le client et Postes Canada. Le client consent à ce que les changements de tarif soient automatiquement appliqués au moyen de la même méthode de paiement qu'il a choisie pour sa commande (carte de crédit ou compte Postes Canada), sans que Postes Canada ait à lui envoyer de nouvel avis.

Messages d'erreur

Code	Description	Signification et atténuation
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).	Les demandes des commerçants ne peuvent pas être acheminées à l'environnement de production.
AA005	Le numéro d'identification de la plate-forme n'est pas précisé.	La variable de l'en-tête platform-id est vide ou elle n'est pas présente dans l'adresse URL. Cela devrait seulement se produire pendant le codage au moment du développement de la plate-forme.
AA006	La plate-forme n'est pas autorisée.	Le platform-id précisé est inexact ou le commerçant s'est ensuite rendu à Postes Canada afin de révoquer intentionnellement la permission permettant à votre plate-forme de soumettre des transactions en son nom. On pourrait demander de revalider avec Postes Canada s'il veut rétablir sa relation avec la plate-forme. Cette erreur pourrait également survenir si le titulaire en ligne de la clé API liée à la plate-forme s'est désinscrit volontairement du Programme pour développeurs. Dans de rares cas, Postes Canada pourrait désactiver le statut de plate-forme au complet en raison des préoccupations de fraude ou de mauvaise utilisation.
AA007	Les demandes d'inscription ne peuvent pas être présentées tant que le statut de plate-forme n'est pas approuvé.	La demande de statut de plate-forme a été présentée, mais Postes Canada ne l'a pas encore approuvée. Dans de rares cas, Postes Canada pourrait désactiver le statut de plate-forme au complet en raison des préoccupations de fraude ou de mauvaise utilisation.
AA008	Seules les plates-formes autorisées peuvent avoir recours aux services d'inscription.	Une tentative d'accès aux services d'inscription a été effectuée sans présenter une demande à Postes Canada pour inscrire votre plate-forme.
AA009	Le type de clé n'est pas valide pour platform-id.	Si une clé autre que celle d'un commerçant est utilisée pour authentifier une transaction, le champ platform-id ne doit pas être rempli. Retirez donc le champ platform-id de la demande, et ce, même si vous disposez d'une plate-forme inscrite. Seules les demandes présentées au nom d'un commerçant peuvent préciser le platform-id.
AA010	La demande de plate-forme est mal configurée.	Le platform-id dans l'en-tête et le platform-id dans l'adresse URL ne concordent pas. Ces valeurs doivent être les mêmes.