Expédier des colis

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 :

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/shipping/v1/{mailedBy}/{mobo}/shipment 

En-têtes requis

Services d’expédition offerts

Nous offrons des services d’expédition des régimes intérieur et 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.

Service international

Options d’expédition

Les options d’expédition sont sélectionnées en fournissant le code d’option approprié (par exemple, SO ou COV) dans vos demandes d’API. Les options peuvent être utilisées ensemble ou de façon indépendante, bien que certaines puissent entrer en conflit avec d’autres ou nécessiter des données supplémentaires.

Afficher une liste complète des codes valides et de leurs descriptions

Exemple de demande d’options d’expédition

{ 
  "serviceCode": "DOM.XP", 
  "options": [ 
    { 
      "optionCode": "SO", 
      "optionAmount": "0.00" 
    }, 
    { 
      "optionCode": "COV", 
      "optionAmount": "100.00" 
    } 
  ] 
} 

Options de traitement en cas de non-livraison

Pour les envois du régime international et des États-Unis qui ne sont pas distribuables, une directive de traitement en cas de non-livraison doit être précisée dans la demande d’API. Cela détermine le sort du colis si la livraison échoue.

Remarque : Ces options sont requises pour de nombreux services, en particulier les colis commerciaux comme les services Colis-avion/de surface – International et Colis accélérés^MC – É.-U. L’omission pour les services requis entraînera une erreur de validation. 

Indicateurs d’emballage

Ces indicateurs sont transmis dans l’élément parcelCharacteristics de votre demande d’API. Elles ont une incidence sur le calcul des tarifs et la manutention.

Remarques importantes sur la mise en œuvre :

• Si votre article respecte ces conditions, vous devez manuellement régler mailingTube ou unpackaged à True.  
• L’interface d’API définit habituellement l’indicateur d’article surdimensionné automatiquement si vous fournissez des dimensions qui dépassent les seuils maximaux.  
• Nous n’appliquons qu’un seul supplément. Si le supplément pour articles non emballés s’applique, le supplément pour articles surdimensionnés sera annulé. 

Demande d’exemple d’indicateur d’emballage

{ 
  "parcelCharacteristics": { 
    "weight": 1.2, 
    "dimensions": { 
      "length": 60, 
      "width": 10, 
      "height": 10 
    }, 
    "mailingTube": true 
  } 
} 

Cas d’utilisation

Voici des scénarios typiques que notre clientèle pourrait rencontrer lors de l’intégration avec nos API. 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.

Exemple 1

Obtenir les tarifs des services d’expédition

Lorsque vous lancez l’appel Obtenir les tarifs, vous fournissez les caractéristiques d’un colis donné dans votre demande. Tous les services et les coûts d’expédition applicables seront renvoyés dans les données JSON. Vous ou votre cliente ou client (selon votre mise en œuvre) pouvez ensuite sélectionner la méthode d’expédition préférée en fonction de la rapidité et du coût.

Agrandir l’image

Exemple 2

Imprimer les étiquettes d’expédition (sur du papier ordinaire ou thermosensible)

Lorsque vous créez un envoi, vous pouvez préciser ce qui suit :  

• Étiquettes sur papier thermosensible ou ordinaire  
• Codage des étiquettes en format PDF  
• Options relatives aux avis électroniques pour le suivi (pour la clientèle titulaire d’un compte commercial, les activités de suivi des envois commencent une fois que le manifeste a été transmis)  
• Une étiquette de retour
• Renseignements sur les prix
• Un code QR

L’image suivante illustre le nombre minimal d’appels nécessaires pour obtenir une image d’étiquette.

Agrandir l’image

Exemple 3

Imprimer une étiquette d’expédition du régime intérieur avec une étiquette de retour

Vous voudrez peut-être imprimer une étiquette de retour à joindre à un envoi. L’étiquette de retour n’est pas facturée à votre compte tant qu’elle n’est pas apposée sur un envoi de retour et qu’elle ne passe pas par le flot du courrier.  

Les liens vers les étiquettes d’expédition et de retour du régime intérieur vous sont renvoyés dans la même réponse unique à la demande Créer l’envoi, contenant les détails de l’étiquette de retour. Vous pouvez implanter les liens vers les étiquettes dans n’importe quel ordre (par exemple, l’étiquette d’expédition ou l’étiquette de retour en premier).

Agrandir l’image

Exemple 4

Obtenir les tarifs de Postes Canada pour un envoi

Vous pouvez lancer un appel pour obtenir les tarifs de Postes Canada pour vos envois du régime intérieur, du régime international ou à destination des États-Unis.

Intégrez l’appel Obtenir le prix de l’envoi dans tous les scénarios commençant par Créer l’envoi.

Agrandir l’image

Exemple 5

Schémas d’appels ponctuels ou par lot

Vous pouvez traiter les impressions d’étiquettes à l’aide de l’un des deux schémas d’appel suivants :  

• Appel ponctuel : Une commande à la fois, dès qu’un emballeur est prêt  
• Par lot : Stockez plusieurs commandes, puis imprimez-les toutes en même temps  

Les renseignements sur les envois sont stockés sur les serveurs de Postes Canada à partir du moment où vous les créez et jusqu’à 90 jours après leur transmission.  

Le diagramme suivant montre comment exécuter des schémas d’appels ponctuels et par lot.

Agrandir l’image

Exemple 6

Synchroniser les appels pour les envois

Votre application peut stocker des liens pour une utilisation ultérieure (comme décrit dans le schéma d’appel par lot) ou utiliser la synchronisation des appels pour obtenir les liens de Postes Canada. Si votre application stocke habituellement les liens, mais qu’une panne survient et entraîne une perte de données, vous pouvez utiliser la synchronisation des appels pour récupérer les données.

Agrandir l’image

Exemple 7

Transmettre vos envois pour recevoir un manifeste

À moins d’utiliser un seul groupe, il est préférable de commencer par l’appel de synchronisation Obtenir les groupes pour déterminer quels groupes contiennent des envois admissibles à la transmission.

Un group-id a pour but de regrouper plusieurs envois afin de les inclure sur le même manifeste. Vous pouvez traiter les impressions d’étiquettes à l’aide de deux schémas d’appel distincts :  

Limites du rendement

Afin d’éviter un délai de temporisation de nos serveurs, suivez ces recommandations :  

• Veuillez ne pas inclure plus de 30 groupes par manifeste, c’est-à-dire pas plus de 30 group-ids dans une seule demande Transmettre les envois.
• Veuillez ne pas placer plus de 5 000 envois dans un groupe.

Limites du système

Pour éviter une erreur, ne dépassez pas les limites suivantes avant de lancer un appel Transmettre les envois :

• Maximum de 50 groupes par manifeste (erreur 9109 si la limite est dépassée)
• Maximum de 10 000 envois dans un groupe (erreur 9110 si la limite est dépassée)
• Maximum de 10 000 envois répartis dans plusieurs groupes (erreur 9108 si la limite est dépassée)

 Vous trouverez le schéma de transmission d’un groupe à la fois ci-dessous. Vous pouvez également créer une boucle de vos transmissions pour chaque groupe en stockant tous les liens de manifeste avant de créer une boucle des artéfacts de manifeste.

Agrandir l’image

Exemple 8

Récupérer les détails du manifeste

Les détails du manifeste sont disponibles en format XML. Les liens vers les données sont renvoyés en même temps que les liens vers le document du manifeste à partir d’une demande Obtenir le manifeste.

Pour récupérer les données JSON, ajoutez un appel Obtenir les détails du manifeste dans le processus Transmettre vos envois pour recevoir un manifeste avant ou après avoir implanté le lien d’artéfact. Vous pouvez utiliser les données en format XML pour mettre à jour vos systèmes comptables dorsaux.

Si les liens vers les manifestes sont perdus ou non stockés intentionnellement, vous pouvez utiliser l’appel de synchronisation Obtenir les manifestes avec une plage de dates commençant à la date du jour pour récupérer les liens de tous les manifestes créés par les demandes de transmission.  

Meilleures pratiques

Le flux de travail suivant illustre un scénario dans lequel les services Web de Postes Canada ont été intégrés dans une boutique en ligne.  

Sélectionnez n’importe quel lien dans le flux de travail pour obtenir plus de renseignements.

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.

Liens connexes

• Aperçu de l’API de tarification
• Aperçu de l’API d’expédition
• Service de manifeste