Repérer des colis
Fournir des mises à jour et une visibilité en temps réel pour chaque envoi
Produits d’API requis
Pour commencer
Avant d’intégrer l’API des retours autorisés, assurez-vous d’effectuer les étapes préalables et de configuration suivantes. Pour obtenir un aperçu plus détaillé, consultez le guide de démarrage rapide.
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 :
- Créez un identifiant pour le site postescanada.ca.
- Inscrivez-vous au Portail des développeurs de Postes Canada.
- Obtenez vos identifiants pour les environnements d’essai et de production de l’API (clé API et Code API Secret).
Points de terminaison des API
Environnement de production
https://api.canadapost-postescanada.ca/prod/devportal-portaildesdeveloppeurs /tracking/v1/pins/{pinNumber}/summariesEn-têtes requis
| Nom d’en-tête | État requis | Description et objet |
|---|---|---|
| Type de contenu | Obligatoire Exemple de valeur ou de format Unique par groupe de services. Consultez les documents sur l’interface API pour obtenir plus de précisions. | Il s’agit de la version JSON du corps que vous envoyez dans la demande POST. Remarque : */* à la place de la valeur d’en-tête affichera un message d’erreur. |
| Acceptation | Obligatoire Exemple de valeur ou de format Unique par groupe de services. Consultez les documents sur l’interface API pour obtenir des précisions ou utilisez le type de média à partir du lien fourni dans la réponse. | Il s’agit de la version JSON de la réponse que vous vous attendez à recevoir. Remarque : */* à la place de la valeur d’en-tête affichera un message d’erreur. |
| Autorisation | Obligatoire Exemple de valeur ou de format Bearer | Porte le jeton d’accès pour authentifier la demande. Précisions :
|
| Accept-Language | Facultatif Exemple de valeur ou de format « en-CA » ou « fr-CA » | Indique la langue de préférence pour tout message d’erreur lisible par un humain qui peut être généré. |
Services de repérage offerts
Nous offrons des services de repérage du régime intérieur et du régime international. Vous trouverez ci-dessous une liste catégorisée des services couramment pris en charge, y compris les codes de service requis pour toutes les demandes d’API.
Services du régime intérieur
(au Canada)
| Nom du service | Code de service API | Avantages |
|---|---|---|
| Colis standardMC | DOM.RP | Expédition de surface économique. |
| Colis accélérésMC | DOM.EP | Livraison plus rapide grâce au repérage. |
| XpresspostMC | DOM.XP | Livraison garantie le jour suivant ou en deux jours dans les grands centres urbains. |
| Priorité MC | DOM.PC | Option de livraison la plus rapide avec repérage et signature. |
| Documents de bibliothèque | DOM.LIB | Service spécial et économique pour l’expédition de documents de bibliothèque (livres, etc.). |
Services à destination des États-Unis
(expédition aux États-Unis)
| Nom du service | Code de service API | Avantages |
|---|---|---|
| Colis accélérésMC – É.-U. | USA.EP | Livraison en aussi peu que 4 jours ouvrables pour les gros colis. Repérage inclus. |
| XpresspostMC – É.-U. | USA.XP | Livraison en 2 ou 3 jours ouvrables. Service garanti avec suivi. |
| Paquet repérableMC – É.-U. | USA.TP | Option rentable pour les articles petits et légers. Comprend le service de suivi. |
Service international
| Nom du service | Code de service API | Avantages |
|---|---|---|
| XpresspostMC – International | INT.XP | Livraison garantie et rapide en seulement quatre jours ouvrables vers les principaux marchés. Comprend le service de suivi. |
| Paquet repérableMC – International | INT.TP | Option rentable pour les articles petits et légers à destination de certains pays. Comprend le service de suivi. |
| Colis-avion – International | INT.IP.AIR | Service aérien standard pour les gros colis. Comprend le repérage pour de nombreuses destinations. L’information sur le repérage est offerte uniquement pour les activités au Canada. |
| Colis de surface – International | INT.IP.SURF | Service standard par voie terrestre ou maritime pour les gros colis. Longs délais de transit (1 à 3 mois). L’information sur le repérage est offerte uniquement pour les activités au Canada. |
Exemple de demandes
Recherche par numéro de repérage
GET https://api-stg.canadapost-postescanada.ca/prod/devportal-portaildesdeveloppeurs/tracking/v1/pins/{PIN}/detailsRecherche par détails de la carte Avis de livraison
GET https://api-stg.canadapost-postescanada.ca/prod/devportal-portaildesdeveloppeurs/tracking/v1/dncs/{DNC}/detailsRecherche par numéro de référence
GET https://api.canadapost-postescanada.ca/prod/devportal-portaildesdeveloppeurs/tracking/v1/refs/summaries?customer-number={customerNumber}&reference-number=ABC123456789&destination-postal-code=M9W1J1&mailing-date-from=2026-02-25&mailing-date-to=2026-02-26Cas d’utilisation
Voici des scénarios typiques que la clientèle pourrait rencontrer lors de l’intégration avec nos API de repérage. Chaque cas d’utilisation est illustré à l’aide d’un diagramme d’appel, qui fournit des précisions sur le flux de données ou de demandes et les paramètres nécessaires pour lancer ces appels.
Suivi et ramassage chez la clientèle
- Utilisez les appels Obtenir un résumé du repérage et Obtenir les détails de repérage pour permettre à la clientèle de faire le suivi des commandes dans votre boutique.
- Utilisez l’appel Obtenir la confirmation de livraison pour permettre au personnel du Service à la clientèle d’afficher l’image de la signature ou le certificat de confirmation de livraison.
Exemple 1
Suivre les commandes à partir de votre site Web
Les appels Obtenir un résumé du repérage et Obtenir les détails de repérage permettent aux clients et clientes de faire le suivi de leurs commandes directement à partir de votre site Web.
L’organigramme illustre le flux typique d’interactions entre une application d’une cliente ou d’un client et l’API de Postes Canada pour le suivi des colis. L’application de la cliente ou du client envoie un numéro de repérage à l’API qui renvoie ces données à l’application, affiche l’événement de repérage le plus récent et tous les détails de livraison subséquents.
Exemple 2
Afficher le certificat de confirmation de livraison
Votre personnel du Service à la clientèle peut obtenir les mêmes renseignements de suivi que ceux décrits dans le procédé Suivre les commandes à partir de votre site Web. Il peut également afficher le certificat de confirmation de livraison.
Cet organigramme illustre la méthode pour confirmer la livraison d’un colis à l’aide d’un certificat de confirmation de livraison. L’application obtient un NIP pour le colis, demande le certificat de confirmation de livraison à partir de l’API de Postes Canada, puis récupère et affiche le certificat en format PDF comme preuve de livraison.
Essais et dépannage
Les développeurs doivent décider quand montrer un message d’erreur directement à 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.