Intégrer les ramassages de colis sur demande

Pour commencer

Avant d’intégrer l’API ramassage, 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 :

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

Points de terminaison des API

Environnement de production

https://api.canadapost-postescanada.ca/prod/devportal-portaildesdeveloppeurs/pickup/v1/{customer}/pickup-request

Demandes de simulations (stubs) de requête et données statiques

L’environnement d’essai utilise des réponses simulées (stubs) pour valider que votre format de requête, votre authentification et vos en-têtes sont corrects.

Les données retournées dans la charge de réponse sont statiques et seront identiques pour chaque demande réussie, peu importe les données uniques que vous envoyez (p. ex., heure, emplacement, articles).

Cet environnement sert uniquement à l’intégration initiale et à la validation du format de la demande. Il ne simule pas la logistique du monde réel ou les vérifications dynamiques des stocks.

Valeurs de test standard

Pour assurer la réussite du traitement dans l’environnement d’essai, utilisez les valeurs connues suivantes pour les champs requis :

ID de la demande d’essai

• Utilisez 0074698052 lorsqu’un identificateur de demande unique est requis.

Numéro du contrat d’essai

• Si vous vous êtes inscrit au portail des développeurs, vous pouvez utiliser votre propre numéro de convention pour effectuer la mise à l’essai (si vous en avez un).

Essai de simulation des erreurs

Utilisez les données d’entrée suivantes pour tester la logique de traitement des erreurs de votre système. Remarque : Il ne s’agit pas d’une liste exhaustive de scénarios d’essai.

Logique de paiement et de facturation

Cette interface API utilise les identifiants fournis dans votre demande pour déterminer la méthode de facturation appropriée en fonction de votre relation établie avec Postes Canada.

Scénarios liés au paiement

Facturation des ramassages par une tierce partie

Lorsqu’un compte commercial (qui a une convention de colis) demande un ramassage à un emplacement qui n’est pas son adresse commerciale enregistrée (un emplacement tiers), les frais y sont appliqués.

Exigences de l’interface API pour le paiement

L’interface API de ramassage n’exige pas de renseignements explicites sur la carte de crédit ou de jetons de paiement dans la charge. Le mode de paiement est déterminé automatiquement par le numéro d’identification de compte ou de convention utilisé dans l’en-tête de la demande.

En-têtes requis

Exemple de demande de ramassage

En-tête:  
Type de contenu: application/vnd.cpc.purs-v1+json
Autorisation: Bearer 

{
  "pickupType" : "OnDemand",
  "pickupLocation" : {
    "businessAddressFlag" : false,
    "alternateAddress" : {
      "company" : "ABC PLASTICS INC.",
      "addressLine1" : "123 Sesame St",
      "city" : "Dartmouth",
      "province" : "NS",
      "postalCode" : "K1T0A1"
    }
  },
  "contactInfo" : {
    "contactName" : "Developer Portal",
    "email" : "test@test.ca",
    "contactPhone" : "613-123-4567",
    "telephoneExt" : "315273",
    "receiveEmailUpdatesFlag" : true,
    "lang": "e"
  },
  "locationDetails" : {
    "fiveTonFlag" : false,
    "loadingDockFlag" : true,
    "pickupInstructions" : "Front door"
  },
  "itemCharacteristics" : {
 
    "priorityFlag" : false,
    "returnsFlag" : false,
    "heavyItemFlag" : true
  },
  "pickupVolume" : 10,
  "pickupTimes" : {
    "onDemandPickupTime" : {
      "date" : "2026-02-11",
      "preferredTime" : "15:00",
      "closingTime" : "17:00"
    }
  },
  "paymentInfo" : {
    "methodOfPayment" : "OnAccount"
  }
}

Explication des champs de l’API

Remarque : Il ne s’agit pas d’une liste exhaustive des champs de l’API de ramassage. Pour voir la liste complète, visitez la page d’aperçu de l’interface API de ramassage.

Remarques :

• Si vous réglez businessAddr à false pour un ramassage sur demande, le service doit être payé par carte de crédit.  
• Lorsque l’indicateur est true, le système extrait automatiquement l’adresse actuellement enregistrée dans votre profil de Postes Canada. 

Services de ramassage offerts

Nous offrons des services de ramassage 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.

Cas d’utilisation

Cette section décrit les scénarios commerciaux types pour l’utilisation de l’interface API de ramassage et décrit les contraintes de planification associées.

Exemple 1

Expédition à partir du magasin

Ce scénario aide les détaillants qui exploitent plusieurs emplacements physiques et qui gèrent chacun leurs propres envois.

Chaque comptoir postal peut demander de façon indépendante des ramassages à l’aide de son compte client attitré de Postes Canada. Cette configuration est idéale pour une intégration fluide dans le panneau d’administration d’un magasin.

Exigence d’API

Le système doit utiliser les identifiants et le numéro de compte propres au magasin à l’origine de la demande pour assurer l’exactitude des stocks et de la gestion des manifestes. 

Exemple 2

Gestion du ramassage par un tiers

Ce scénario permet à une entité commerciale principale de gérer et de facturer les ramassages à des emplacements externes.

Un compte commercial peut demander des ramassages pour des emplacements tiers (p. ex., entrepôts de fournisseurs, adresses commerciales des partenaires). Tous les frais liés aux demandes de ramassage sont acheminés exclusivement au compte principal utilisé aux fins d’authentification, peu importe l’adresse physique du ramassage.

Exigence d’API

La demande utilise les identifiants du compte principal, mais l’objet du lieu de ramassage doit contenir les détails complets de l’adresse de la tierce partie.

Exemple 3

Ramassages à horaire fixe et le jour même

Le délai de livraison maximal pour la planification des ramassages dépend des renseignements sur le paiement que vous avez sauvegardés.

Notes sur le service le jour même

• La date de ramassage demandée doit correspondre à la date du jour.  
• Le système validera la demande par rapport à l’heure limite locale pour le lieu de ramassage.
• Si la demande est faite après l’heure limite, la commande de ramassage sera automatiquement rejetée.

Meilleures pratiques

Pour les applications d’expédition à partir du magasin ou toute mise en œuvre impliquant plusieurs emplacements de ramassage, nous recommandons d’utiliser une mise en correspondance individuelle entre chaque comptoir postal physique et un numéro de compte commercial unique (numéro d’identification de compte). Cette structure est essentielle pour assurer l’exactitude de la facturation et du suivi en fonction de l’emplacement.

Mise en correspondance et authentification des comptes

Pour gérer efficacement plusieurs magasins au moyen de l’interface API, votre application doit traiter dynamiquement l’authentification et les en-têtes des requêtes :

Simplification de la demande de ramassage

Afin de maximiser l’efficacité pour le personnel du magasin, votre application doit afficher par défaut les renseignements statiques sur le ramassage à l’aide de données stockées localement liées au numéro d’identification de compte du magasin.

Exemple 1

Exemple de code

"pickupLocation": {
  "businessAddr": true,
  "alternateAddr": {
    "addrLn1": "365 March Road",
    "city": "Ottawa",
    "province": "ON",
    "postalCode": "K2K3N5",
    "countryCd": "CA",
    "companyNm": "Testing Inc."
  }
}

Données prédéfinies recommandées

Adresse officielle complète du magasin (lignes d’adresse, ville, code postal).

Raison de l’affichage automatique

Élimine les erreurs de saisie et fait en sorte que le lieu de ramassage correspond à l’adresse du compte enregistré. 

Exemple 2

Exemple de code

"contactInfo": { 
  "email": "john.doe@email.com",
  "receiveEmailUpdate": false,
  "lang": "e",
  "contactNm": "John Doe",
  "phone": "613-123-4567",
  "phoneExt": "123"
}

Données prédéfinies recommandées

Numéro de téléphone par défaut du magasin et nom et adresse courriel de la ou du gestionnaire.

Raison de l’affichage automatique

Réduit le fardeau du personnel et s’assure que la communication est acheminée correctement. 

Exemple de schéma du panneau d’administration

Votre interface d’administration doit être conçue de façon à ce que le personnel du magasin n’ait qu’à saisir les données dynamiques requises pour le ramassage précis :

1. Le personnel saisit la date et l’heure et le nombre de colis.
2. Le système ajoute l’adresse du magasin, les coordonnées et le bon en-tête.
3. Le système effectue ensuite l’appel API de création d’une demande de ramassage.

Cette conception permet de réduire au minimum les frappes au clavier, les erreurs et l’épuration des données de facturation et de suivi.

Les illustrations ci-dessous montrent un exemple différent d’interface de panneau d’administration. Comme vous pouvez le voir, la plupart des champs sont prédéfinis pour le personnel du magasin.

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 champs 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

• Disponibilité du service de ramassage de colis
• Créer une demande de ramassage