Exemples de codes pour les plates-formes de cybercommerce :  REST  |  SOAP

Plates-formes de cybercommerce

Expédition de colis directement à un bureau de poste de choix

Légende

i Seules les plates-formes de cybercommerce approuvées par Postes Canada pourront faire appel à ces services Web. Pour devenir un fournisseur de plate-forme pour Postes Canada, veuillez ouvrir une session à partir de la page d'accueil du Programme pour développeurs et sélectionner Inscrire une plate-forme.

number

Lisez les premières étapes pour apprendre comment vous inscrire, comment obtenir vos clés API, et bien plus encore.

number

Pour obtenir de l'information essentielle commune à tous nos services en ligne, lisez les principes de base des services de Postes Canada pour les deux différents modules :   REST  |  SOAP

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

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 : www.canadapost.ca/cpotools/apps/drc/merchant

    Environnement pour test : www.canadapost.ca/cpotools/apps/drc/testMerchant

    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

Voici à quoi ressemblerait une demande présentée en votre propre nom :

POST https://soa-gw.canadapost.ca/rs/1234567/1234567/shipment
Variable des en-têtes HTTP Valeur

Accept

application/vnd.cpc.shipment-v2+xml

Content-Type

application/vnd.cpc.shipment-v2+xml

Authorization

Basic {Encodage en base64 du code d'usager:mot de passe}

Accept-language

en-CA ou fr-CA

Voici à quoi ressemblerait une demande présentée au nom du commerçant :

POST https:// soa-gw.canadapost.ca/rs/1111111-1234567/1111111/shipment
Variable des en-têtes HTTP Valeur

Accept

application/vnd.cpc.shipment-v2+xml

Content-Type

application/vnd.cpc.shipment-v2+xml

Authorization

Basic {Encodage en base64 du code d'usager:mot de passe}

Accept-language

en-CA ou fr-CA

Platform-id

1234567

  • 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.

Annulation interdite des étiquettes pour l'expédition sans convention

Si vous avez recours à des services d'expédition sans convention, vous ne pouvez pas annuler une étiquette qui a été créé.

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.