Inscription des nouveaux commerces

Qu’est-ce qu’une plateforme?

Une plateforme est une solution de cybercommerce ou d’expédition qui intègre les API de Postes Canada pour faciliter l’expédition pour plusieurs commerces. Dans cet écosystème, la plateforme sert de pont entre la boutique du commerce et le réseau logistique de Postes Canada.

Chaque plateforme se voit attribuer un platformId (numéro de compte) unique à 10 chiffres par Postes Canada. Grâce à ce numéro, Postes Canada peut :

• Valider la plateforme lors du processus d’intégration immédiate « punch-out »
• Associer des commerces précis à votre plateforme aux fins de facturation et de production de rapports.
• Suivre l’intégration des contrats commerciaux et des tarifs négociés à l’avance

Important : Mise à jour des exigences d’authentification

Pour interagir avec nos API en toute sécurité, toutes les plateformes doivent maintenant respecter notre guide d’authentification actualisé. Il s’agit d’une exigence obligatoire pour assurer la protection des données sensibles.

Sans une authentification adéquate, votre plateforme ne pourra pas :

• Lancer le flux OAuth
• Appeler les API de tarification, d’expédition ou de suivi au nom de vos utilisateurs et utilisatrices.
• Renouveler les jetons sécurisés, ce qui entraînera des interruptions de service immédiates.

Pour éviter les retards d’intégration, veuillez consulter le guide d’authentification sans délai pour comprendre comment gérer les clés API, les jetons OAuth 2.0 et les en-têtes de requête.

Qu’attend-on d’une plateforme?

Postes Canada exige des plateformes qu’elles maintiennent des normes élevées de sécurité et de fiabilité technique pour protéger les données des commerces. Les plateformes doivent traiter le secret de production et le secret de test du commerce comme des « clés principales » hautement sensibles Ces données doivent être chiffrées au repos (p. ex., AES-256) et ne doivent jamais être exposées dans les journaux côté client.

Conformité technique

• Votre returnUrl doit être accessible via HTTPS.
• Votre application doit analyser correctement le corps de la requête Form POST envoyée par Postes Canada au moment de l’inscription du commerce.
• La plateforme est responsable de générer et de mettre à jour les jetons Bearer pour tous les appels d’API subséquents (tarification, expédition, etc.).

Traitement des erreurs

Les plateformes doivent faire la distinction entre les annulations demandées par l’utilisateur ou l’utilisatrice et les erreurs techniques. En cas d’échec d’une inscription, la plateforme doit afficher des messages conviviaux plutôt que des codes d’erreur API bruts.

Pour commencer

Pour commencer à intégrer des commerces à votre plateforme, assurez-vous de remplir une demande pour devenir une plateforme.

Préalables

Remarque : Pour utiliser l’API, vous devez d’abord avoir un compte commercial de Postes Canada valide qui fournit un numéro de compte. Les membres de la clientèle commerciale ont habituellement une convention commerciale officielle. Elle fournit un numéro de convention et la facturation est portée au compte. Les membres du programme Solutions pour petites entreprises peuvent accéder à l’API à l’aide de leur numéro de compte SPPE. Les services de retour sont généralement facturés à la carte de crédit qui figure dans votre profil ou votre compte d’entreprise.

Une fois que vous avez un compte, voici les prochaines étapes à suivre pour utiliser l’API :

1. Créez un identifiant pour le site postescanada.ca.
2. Inscrivez-vous au Portail des développeurs de Postes Canada.
3. Obtenez vos identifiants pour les environnements d’essai et de production de l’API (clé API et Code API Secret).
4. Assurez-vous que votre serveur dispose d’une returnUrl dédiée accessible via HTTPS. Ce point de terminaison doit être configuré pour traiter les données HTTP POST entrantes.
5. Élaborez un flux d’intégration immédiate « punch-out » de sorte que votre plateforme envoie une requête POST contenant votre platformId, votre returnUrl et la langue préférée.

Processus d’intégration immédiate « punch-out »

Le processus d’inscription est une intégration immédiate de type « punch-out ». Cela signifie que le parcours du commerce commence sur votre plateforme, mais se termine dans l’environnement sécurisé de Postes Canada.

1. Le commerce amorce le processus d’inscription sur le site Web de la plateforme.
2. La plateforme envoie une requête HTTP POST au point de terminaison d’intégration de Postes Canada. Cette requête doit comprendre les éléments suivants : platformId, returnUrl et language.
3. Postes Canada valide le platformId. S’il n’est pas valide, une erreur s’affiche dans le navigateur pour le commerce.
4. Le commerce ouvre une session ou crée un profil d’entreprise de Postes Canada.
5. Le commerce sélectionne son mode de paiement par défaut, comme une carte de crédit ou un compte de fournisseur.
6. Postes Canada crée les identifiants API du commerce et associe son compte à la plateforme dans le système de facturation.
7. Postes Canada redirige le commerce vers la returnUrl de la plateforme.
8. La redirection comprend une requête Form POST contenant les nouvelles clés API, les secrets et les configurations de paiement du commerce.

URL POST

POST https://www.canadapost-postescanada.ca/devonboarding-integrationdev/api/activation

Explication des éléments de la requête HTTP POST

Amorcez le processus d’inscription en envoyant une demande HTTP POST à l’URL finale indiquée ci-dessus. Le corps de votre demande doit comprendre les paramètres suivants :

Détails du message de confirmation de l’inscription

Une fois l’inscription réussie, Postes Canada envoie une requête Form POST à la returnUrl spécifiée. Votre application doit analyser les paramètres suivants à partir du corps de la requête :

Traitement des échecs d’inscription

Il est essentiel de faire la distinction entre une annulation demandée par l’utilisateur ou l’utilisatrice et une erreur de configuration technique.

Échecs liés à la logique

Si l’inscription échoue après le début de la procédure d’intégration immédiate « punch-out », Postes Canada ajoutera le paramètre de chaîne de requête registration-status=failure à votre returnUrl.

Échecs de validation initiale

Si le platformId fourni dans la requête POST initiale n’est pas valide ou est inactif, le commerce n’atteindra pas les écrans d’inscription; Postes Canada affichera immédiatement un message d’erreur dans le navigateur.

Meilleures pratiques en matière de sécurité

Comme ces identifiants donnent accès aux données de facturation et d’expédition du commerce, assurez-vous que votre returnUrl est accessible via HTTPS et que le merchant-prd-client-secret n’est jamais exposé dans les journaux côté client ou les consoles de navigation.

Exemple de requête POST pour une inscription réussie 

<!-- HTML -->
<form name="merchant-return"
	action="https://www.[returnUrl]/shipper/onboarding?session=1234567&status=success"
	method="post" type="hidden">
	<input type="hidden" name="customer-number" value="0007020811"/>
	<input type="hidden" name="merchant-prd-client-id" value="ae5213511a244779b68c8a38d90dded8"/>
	<input type="hidden" name="merchant-prd-client-secret" value="2989a6f7cc594aa687c9829932fe5624"/>
	<input type="hidden" name="merchant-test-client-id" value="ae5213511a244779b68c8a38d90dded8"/>
	<input type="hidden" name="merchant-test-client-secret" value="2989a6f7cc594aa687c9829932fe5624"/>
	<input type="hidden" name="credit-card" value="true"/>
	<input type="hidden" name="on-account" value="false"/>
</form>

Cas d’utilisation

Cette section décrit les scénarios commerciaux types pour l’utilisation de l’API d’inscription du commerce.

Exemple 1

Intégration d’un nouveau commerce

Le ou la propriétaire d’une petite entreprise s’inscrit à votre plateforme de cybercommerce et doit configurer l’expédition par Postes Canada pour la première fois.

Exigence d’API

La plateforme doit lancer une requête POST d’intégration immédiate « punch-out » contenant les éléments suivants : platformId et returnUrl.

Résultat

La personne est redirigée vers Postes Canada pour créer un profil et, une fois le profil créé, la plateforme reçoit les nouvelles clés API de production et le numéro de compte du commerce.

Exemple 2

Lier un compte commercial existant

Un grand détaillant titulaire d’un contrat commercial de Postes Canada souhaite intégrer ses tarifs négociés au préalable à votre plateforme.

Exigence d’API

Le commerce ouvre une session pendant le processus d’intégration immédiate « punch-out » à l’aide de ses identifiants existants.

Résultat

L’API associe le numéro de contrat existant du commerce à votre platformId et renvoie l’indicateur on-account: true, garantissant ainsi que la facturation se fera sur son compte de crédit plutôt que sur une carte de crédit.

Exemple 3

Mise à jour du mode de paiement

Un commerce doit faire passer son mode de paiement par défaut pour l’expédition d’une carte de crédit personnelle à un compte de fournisseur.

Exigence d’API

La plateforme relance le processus d’inscription.

Résultat

Le commerce sélectionne un nouveau mode de paiement par l’entremise de l’interface de Postes Canada, et la plateforme reçoit une charge utile actualisée avec le statut credit-card ou on-account défini sur la nouvelle valeur par défaut.

Meilleures pratiques

Exemple de flux général

1. Le commerce amorce l’inscription par l’entremise de la plateforme.
2. La plateforme envoie une requête Form POST au point de terminaison d’intégration de Postes Canada.
3. Postes Canada valide l’ID de la plateforme.
4. Le commerce termine l’inscription et sélectionne son mode de paiement.
5. Postes Canada crée les identifiants du commerce et associe ce dernier à la plateforme.
6. Le commerce est redirigé vers la returnUrl de la plateforme via une requête HTTP POST. La plateforme saisit la charge utile, valide le statut de l’inscription et stocke les identifiants API de façon sécurisée.

Liste de contrôle des meilleures pratiques en matière de sécurité

Le message de confirmation de l’inscription comprend les identifiants essentiels qui donnent accès au compte de Postes Canada d’un commerce.

Suivez ces étapes pour traiter le flux principal en toute sécurité :

1. Récupérez le merchant-prd-client-id et le merchant-prd-client-secret dans les paramètres du formulaire entrant.
2. Confirmez que la logique d’association à la plateforme correspond au platformId utilisé pour initier la requête.
3. Vérifiez les valeurs booléennes credit-card et on-account pour définir le profil de facturation du commerce dans votre interface utilisateur.
4. Si la valeur associée au registration-status est failure, consignez l’erreur et affichez un message convivial plutôt que des codes d’erreur API bruts.

Exemple d’appels REST pour les plateformes

Lorsque vous faites des appels au nom d’un commerçant, vous devez utiliser une structure d’URL précise qui identifie le commerçant et votre plateforme.

Modèle d’URL de plateforme

Pour les points de terminaison énumérés ci-dessous, vous devez ajouter votre ID de plateforme au numéro de compte du commerçant au moyen d’un trait d’union.

Modèle :

.../{mailedBy}-{platformId}/{mobo}/{resource}

Exemple de demande :

POST https://api.canadapost-postescanada.ca/prod/devportal-portaildesdeveloppeurs/shipping/v1/1111111-1234567/1111111/shipment

Remarque : Dans l’exemple ci-dessus, 1111111 est le numéro de compte du commerçant et 1234567 est votre ID de plateforme unique.

Points de terminaison touchés

Le format {customer-number}-{platformId} est obligatoire pour les catégories suivantes :

• Expédition : Création, obtention et annulation d’envois, détails de l’envoi et tarification
• Manifeste : Transmission des envois, obtention des manifestes et des détails
• Retours : Création de retours autorisés ou ouverts, gestion des modèles
• Renseignements sur la clientèle : Obtention des renseignements sur la cliente ou le client ou Expédié au nom de

Logique de mise en œuvre : Gestion des identifiants

Il est recommandé de considérer le secret de production et le secret de test comme des « clés maîtresses » hautement sensibles.

Environnement de production

Utilisez merchant-prd-client-id et merchant-prd-client-secret pour la génération des étiquettes et la facturation.

Environnement de test

Utilisez merchant-test-client-id et merchant-test-client-secret pour que le développement et le dépannage n’aient pas d’incidence sur le compte du commerce.

Essais et dépannage

Les équipes de développement doivent décider s’il convient d’afficher directement un message d’erreur destiné à l’utilisatrice ou l’utilisateur final plutôt que de mettre en œuvre une stratégie d’atténuation pour prévenir l’erreur.

Erreurs fréquentes et comment les corriger

Avant de procéder au dépannage, passez en revue notre liste d’erreurs courantes et leurs codes. Chaque entrée comprend le code d’état HTTP précis et les mesures d’atténuation recommandées.

P. ex. : Une erreur 9112 (« Service non disponible ») peut indiquer un problème de configuration. La mesure d’atténuation consiste à vérifier les services disponibles pour l’origine ou la destination sélectionnée.

Structure de réponse en cas d’erreur d’API

Les réponses d’erreur de l’interface API renvoient habituellement à 400 Bad Request (Requête non valide 400) (pour les erreurs de validation de saisie) ou à500 Internal Server Error (Erreur du serveur interne 500) (pour les problèmes imprévus). Le corps de réponse contiendra un objet d’erreur structuré comportant les éléments clés suivants :

• code : Le code d’erreur alphanumérique précis (p. ex., 9111).
• message : Une description en texte brut de l’erreur.

Soutien au développement

Si vous avez mis en œuvre les stratégies d’atténuation recommandées et que vous éprouvez toujours des problèmes, veuillez communiquer avec notre équipe de soutien aux développeurs.

Liens connexes

Pour obtenir plus de renseignements sur les intégrations existantes ou pour découvrir d’autres solutions mises de l’avant, veuillez consulter le répertoire des partenaires de Postes Canada.