Envois retournés

Exemples de codes pour les envois retournés : Java (.zip) | PHP (.zip) | C# (.zip)

Créer un retour autorisé – Module REST

Résumé

Nom : Créer un retour autorisé
Raison pour utiliser le service : Pour créer un retour autorisé vous permettant de récupérer et imprimer une étiquette d'expédition du Service de retour pouvant être envoyée (par voie physique ou électronique) à un client
Données d'entrée : Données d'entrée sur l'envoi, notamment l'adresse de retour (expéditeur et destinataire), et caractéristiques du colis (p. ex. dimensions et poids)
Données de sortie : Pointeurs liés à l'artefact pour permettre l'impression de l'étiquette
Exemple d'erreur : Erreurs liées à l'adresse ou aux caractéristiques du colis
Prochaine demande de service habituelle : Service Obtenir l'artefact permettant de récupérer l'étiquette d'expédition du Service de retour
Historique des versions : Notes de mise à jour
Créer un retour autorisé – Résumé du service

Créer un retour autorisé – Résumé du service

Détails sur la demande

Demand – Structure pour le service « Créer un retour autorisé »

Point final

POST https://XX/rs/{Client « Expédié par »}/{Client « Expédié au nom de »}/authorizedreturn

Remplacez... Par...

XX (Conception)

ct.soa-gw.canadapost.ca

XX (Production)

soa-gw.canadapost.ca

{Client « Expédié par »}

Votre numéro de client

{Client « Expédié au nom de »}

Numéro du client « Expédié au nom de » (ou répétez votre numéro de client)

En-têtes HTTP

Variable des en-têtes HTTP

Valeur

Accept

application/vnd.cpc.authreturn-v2+xml (Remarque : */* à la place de la valeur de l’en-tête affichera un message d’erreur)

Content-Type

application/vnd.cpc.authreturn-v2+xml (Remarque : */* à la place de la valeur de l’en-tête affichera un message d’erreur)

Authorization

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

Accept-language

en-CA or fr-CA

Corps du message

<?xml version="1.0" encoding="utf-8"?>
<authorized-return xmlns=”http://www.canadapost.ca/ws/authreturn-v2”>
xxx
</authorized-return>

Demande – Éléments

Le tableau suivant décrit les éléments XML composant les données d'entrée pour ce service. La structure hiérarchique des données d'entrée XML est présentée dans la section Demande – Diagramme XML.

Créer un retour autorisé – Éléments de la demande
Nom de l'élément Type Requis/Optionnel Description

authorized-return

Complexe

Requis

Il s'agit de la structure XML générale pour les données d'entrée de la demande. Cette structure fournit une description des détails sur la demande de retour, notamment le destinataire, le code de service, la personne retournant l'envoi, les caractéristiques du colis et les références.

create-public-key

Simple

Optionnel

{true}
Si l’indicateur est présent et qu’il est réglé à « true », une d’URL publique sera générée pour qu’une version PDF de l’étiquette d’expédition soit récupérée et incluse dans la réponse au service avec la date d’expiration. Cette fonction peut être utilisée si l’expéditeur préfère envoyer au client un lien vers l’étiquette plutôt qu’une étiquette comme pièce jointe. De plus, l’expéditeur peut envoyer au client un code QR encodant l’URL publique, ce qui permettrait au client d’utiliser le code QR pour imprimer l’étiquette dans n’importe quel emplacement de vente au détail de la SCP.
La date d’expiration indique quand le lien pour récupérer l’étiquette ne sera plus accessible.

create-qr-code

Simple

(true|false)
Si un indicateur est présent et qu’il est réglé à « true », ET que l’élément create-public-key a également cette valeur, l’encodage du code QR de l’URL publique est automatiquement généré et retourné dans la réponse..

box-free

Simple

Facultatif

(True/False) Si un indicateur est présent et réglé à « true », le libellé « Box-free / Sans emballage » est ajouté sur l’image contenant le code QR, et un code QR vert est généré. Remarque : Il y a des exigences d’admissibilité pour les retours sans boîte. Si les articles ne sont pas admissibles, ils ne seront pas acceptés comme des retours sans emballage au bureau de poste. Consultez le Guide du client pour les services de colis pour obtenir plus de renseignements.

customer-barcode

Simple

Optional

(16 caractères alphanumériques)
Valeur du code à barres.
S’il est présent, le code à barres sera rendu dans la section de renseignements client de l’étiquette de retour autorisée (habituellement en bas).

customer-barcode-type

Simple

Optional

(LINÉAIRE|2D)
Type de code à barres. Obligatoire si le code à barres du client est spécifié.

service-code

Simple

Requis

(Chaîne de caractères – Jusqu'à 32 caractères alphanumériques)

Les étiquettes du Service de retour peuvent seulement être créées si l'envoi est déposé au Canada et qu'il doit être livré à l'intérieur de ce pays.

Code de service Description
DOM.RP Colis standard
DOM.EP Colis accélérés
DOM.XP Xpresspost
DOM.PC Priorité

Il s'agit du service de livraison de Postes Canada utilisé pour expédier l'article.

returner

Complexe

Requis

Cette structure contient des données sur l'expéditeur correspondant à l'adresse de l'expéditeur figurant sur l'étiquette. Les champs vides seront retirés du formatage des adresses.

name

Simple

Requis

(44 caractères alphanumériques)
Nom de la personne retournant l'envoi avec qui il faut communiquer.

company

Simple

Optionnel

(44 caractères alphanumériques)
Nom de l'entreprise de la personne retournant l'envoi.

domestic-address

Complexe

Requis

Cette structure contient les données d'adressage de la personne retournant l'envoi. Les champs vides seront retirés des champs relatifs à l'adresse aux fins de formatage des étiquettes.

address-line-1

Simple

Requis

(44 caractères alphanumériques)

address-line-2

Simple

Optionnel

(44 caractères alphanumériques)

city

Simple

Requis

(40 caractères alphanumériques)

province

Simple

Requis

(2 caractères)

postal-code

Simple

Requis

(Modèle du code postal canadien à six caractères : A9A9A9)

receiver

Complexe

Requis

Cette structure contient des données sur la destination correspondant à l'adresse du destinataire figurant sur l'étiquette. Les champs vides seront retirés du formatage des adresses.

name

Simple

Requis

(44 caractères alphanumériques)
Nom du destinataire correspondant avec qui il faut communiquer.

company

Simple

Optionnel

(44 caractères alphanumériques)
Nom de l'entreprise du destinataire correspondant.

email

Simple

Optionnel

(60 caractères – Il doit s'agit d'une adresse électronique valide.)
Pour utilisation future.

receiver-voice-number

Simple

Optionnel

(Chaîne de caractères – Jusqu'à 25 caractères)
Il s'agit du numéro de téléphone du destinataire.
Ce numéro n'apparaîtra pas sur l'étiquette d'expédition.

domestic-address

Complexe

Requis

Requis si l'élément XML parent correspondant « Destinataire » existe.
Cette structure contient les données d'adressage du destinataire de l'envoi. Les champs vides seront retirés des champs relatifs à l'adresse aux fins de formatage des étiquettes.

address-line-1

Simple

Requis

(44 caractères alphanumériques)

address-line-2

Simple

Optionnel

(44 caractères alphanumériques)

city

Simple

Requis

(40 caractères alphanumériques)

province

Simple

Requis

(2 caractères)

postal-code

Simple

Requis

(Modèle du code postal canadien à six caractères : A9A9A9)

parcel-characteristics

Complexe

Optionnel

Cette structure contient des renseignements sur les caractéristiques physiques du colis.

weight

Simple

Optionnel

(Champ numérique de trois chiffres, suivis de trois décimales [p. ex. format 999.999])

Poids total du colis en kilogrammes.

dimensions

Complexe

Optionnel

Cette structure contient des renseignements précisant les dimensions du colis.

length

Simple

Requis sous condition

(Champ numérique de trois chiffres, suivis d’une décimale [p. ex. format 999.9])
Requis si l'élément XML parent correspondant « Dimensions » existe.
Il s'agit de la longueur du colis en centimètres.
Si la longueur est précisée, un prix plus exact peut être défini.

width

Simple

Requis sous condition

(Champ numérique de trois chiffres, suivis d’une décimale [p. ex. format 999.9])
Requis si l'élément XML parent correspondant « Dimensions » existe.
Il s'agit de la longueur du colis en centimètres.
Si la largeur est précisée, un prix plus exact peut être défini.

height

Simple

Requis sous condition

(Champ numérique de trois chiffres, suivis d’une décimale [p. ex. format 999.9])
Requis si l'élément XML parent correspondant « Dimensions » existe.
Il s'agit de la hauteur du colis en centimètres.
Si la hauteur est précisée, un prix plus exact peut être défini.

print-preferences

Complexe

Optionnel

Cette structure contient les préférences d'impression pour les étiquettes.

output-format

Simple

Optionnel

(7 caractères alphanumériques)
Les valeurs valides sont les suivantes :
- 8.5x11
- 4x6
Si cet élément n'est pas précisé, la valeur « 8.5x11 » s'affiche par défaut.

encoding

Simple

Optionnel

{PDF, ZPL}
Servez-vous de ce champ pour préciser le format de sortie pour votre étiquette du Service de retour : PDF ou ZPL II. Si le champ est vide, le format PDF sera sélectionné par défaut.

Si vous choisissez le format ZPL, la réponse du service « Obtenir l'artefact » inclura un fichier contenant des commandes d'impression ZPL II. Vous devrez ensuite coder une solution ou utiliser une application afin d'envoyer les commandes directement à une imprimante thermique.

Pour les étiquettes de format ZPL II, votre imprimante doit permettre la troncature. Utilisez notre exemple de code pour tester la capacité de votre imprimante à tronquer du texte.

Le format ZPL est uniquement disponible sur du papier thermosensible. L'élément <output-format> doit alors être de 4 po sur 6 po.

show-packing-instructions

Simple

Optionnel

{Vrai ou faux} La valeur par défaut est « Vrai ».
Cet élément indique si les directives d'emballage doivent être inscrites sur l'étiquette.

settlement-info

Complexe

Requis

Cette structure est semblable à celle du service « Créer un envoi », mais son contenu est facultatif. Il est recommandé d'omettre ce contenu.

paid-by-customer

Simple

Optionnel

(10 caractères numériques)
Pour utilisation future.

contract-id

Simple

Optionnel

(10 caractères numériques)
Pour utilisation future.

references

Complexe

Optionnel

Cette structure contient des champs de référence que vous pouvez attribuer. Ces autres numéros d'identification (pouvant être uniques) sont attribués aux envois retournés. Ils peuvent être utilisés pour le repérage ou pour une raison quelconque que vous jugez utile.

customer-ref-1

Simple

Optionnel

(Chaîne de caractères – Jusqu'à 35 caractères)
Il s'agit d'une valeur définie par l'utilisateur disponible pour vos applications. La valeur que vous saisissez ici apparaîtra sur l'étiquette d'expédition, dans l'outil Repérer et, pour les clients qui sont inscrits à notre service de suivi automatisé des colis, dans votre fichier SAC.

customer-ref-2

Simple

Optionnel

(Chaîne de caractères – Jusqu'à 35 caractères)
Il s'agit d'une valeur définie par l'utilisateur disponible pour vos applications. La valeur que vous saisissez ici apparaîtra sur l'étiquette d'expédition, dans l'outil Repérer et, pour les clients qui sont inscrits à notre service de suivi automatisé des colis, dans votre fichier SAC.

notifications

Complexe

Optionnel

Cette structure contient les paramètres propres aux avis électroniques pour recevoir les renseignements sur le repérage des colis.

notification

Complexe

Requis

Si la structure liée aux avis est présente, au moins un avis est requis et jusqu'à quatre avis sont permis. Cette structure contient une adresse électronique ainsi que les types d'avis qu'il faut envoyer à l'adresse électronique en question.

email

Simple

Requis

(Série de courriels – Jusqu'à 60 caractères)

Adresse électronique pour recevoir des mises à jour de suivi automatiques.

L'adresse électronique doit être valide. Par exemple, elle doit respecter le format suivant : (['_A-Za-z0-9\-\+])(\.['_A-Za-z0-9\-\+])@([A-Za-z0-9-])(\.[A-Za-z0-9-])(\.[A-Za-z]{2,})

Si la structure liée aux avis est présente, l'adresse électronique doit être fournie.

on-shipment

Simple

Requis

{vrai, faux}

Si la structure liée aux avis est présente, cet élément doit être fourni. Si la valeur est
« Vrai », toutes les mises à jour concernant le repérage des envois seront envoyées à l'adresse électronique indiquée.

on-exception

Simple

Requis

{vrai, faux}

Si la structure liée aux avis est présente, cet élément doit être fourni. Si la valeur est
« Vrai », toutes les mises à jour concernant le repérage des exceptions seront envoyées à l'adresse électronique indiquée.

on-delivery

Simple

Requis

{vrai, faux}

Si la structure liée aux avis est présente, cet élément doit être fourni. Si la valeur est
« Vrai », toutes les mises à jour concernant le repérage des livraisons seront envoyées à l'adresse électronique indiquée.

email-subject

Simple

Optionnel

{tracking,customer-ref-1,customer-ref-2}

Voici le format général de la ligne d'objet d'un courriel selon le type d'avis :

  • Ship Notification for Item / Avis d’expédition pour l’article :
  • Exception Notification for Item / Avis d’exception pour l’article :
  • Delivery Notification for Item / Avis de livraison pour l’article :

La mention « TRACKING » et le numéro de repérage de Postes Canada s'affichent par défaut après le deux-points. Vous pouvez également régler les paramètres pour que la mention « REFERENCE » et l'un des numéros de référence du client s'affichent.

Demande – Diagramme XML

Créer un retour autorisé – Structure de la demande XML
Créer un retour autorisé – Structure de la demande XML

Détails de la réponse

Réponse – Éléments

Le tableau suivant décrit les champs XML dans la réponse. Pour obtenir un aperçu détaillé de la hiérarchie de la réponse, consultez le diagramme ci-dessous.

Créer un retour autorisé – Éléments de la réponse
Nom de l'élément Type Description

authorized-return

Complexe

Il s'agit de l'élément XML de niveau supérieur pour la réponse.
Cette structure XML contient des renseignements sur le retour autorisé créé.

public-key-info

Complexe

Cette structure représente les données relatives à l’URL publique de l’étiquette – l’URL pour récupérer une version PDF de l’étiquette d’expédition avec la date d’expiration de l’URL.

expiry-date

Simple

La date d'expiration du URL publique de l'étiquette.

url

Simple

URL pour récupérer la version PDF de l’étiquette au format
http://est.postescanada.ca/esto/app/bypass/label?key={generated_key}

qr-code

Simple

Encodage Base64 de l’image réelle du code QR qui représente l’URL publique (si create-qr-code et create-public-key sont tous deux présents dans la demande et réglés à « true »). – insérer le français

tracking-pin

Simple

Il s'agit du numéro d'identification du produit (NIP) pour l'envoi. Le NIP de repérage peut être utilisé en tant que donnée d'entrée pour toute autre demande de service pour les colis, notamment le service Obtenir les détails de repérage.

customer-barcode

Simple

Valeur du code à barres spécifiée dans la demande (si elle est fournie).

links

Complexe

Cette structure représente une liste de liens vers les renseignements concernant l'envoi créé.

return-link

Complexe

La structure des liens comprend un seul élément de lien pour le retour.
Exemple :

<link href=”https://XX/ers/artifact/12346789/9876554/01
rel=”returnLabel" index=”1”
media-type=”application/png”/>

Ce lien ne contient aucun sous-élément, mais il contient les trois attributs suivants :

  1. href. String. Il s'agit du point final pouvant être utilisé pour présenter une demande de service Obtenir l'artefact afin de récupérer l'étiquette pour le retour autorisé qui vient tout juste d'être créé.

  1. rel. String. L'utilisation générique de l'élément de lien désigne l'objectif du lien et le type de renseignements qui y seront récupérés. Dans le cas de ce service, il y aura seulement un élément de lien pour le retour. Il sera également assorti de la valeur « rel="returnLabel" », ce qui signifie que la valeur  « href » peut être utilisée pour présenter une demande de service Obtenir l'artefact afin de récupérer une étiquette du Service de retour. Il n'y a aucun autre type de lien associé à ce service.

  1. media-type. L'attribut lié au type de média désigne le format du fichier graphique (p. ex. PDF ou ZPL).

Remarque : Après que vous avez créé un retour autorisé, vous avez cinq jours civils à récupérer l'étiquette de retour avant que le lien expire.

Réponse – Diagramme XML

Créer un retour autorisé – Structure de la réponse XML

Créer un retour autorisé – Structure de la réponse XML

Réponse – Réponses d'erreur possibles

Dans le cas d'une erreur d'application, une réponse d'erreur (code de statut HTTP de niveau 400) sera générée et le corps du message XML aura une structure du message d'erreur plutôt qu'une réponse de réussite. Pour obtenir de plus amples renseignements, veuillez consulter la section Codes de statut HTTP.

Code

Description

9191

Le langage ZPL est utilisé pour les imprimantes thermiques. Vous pouvez donc l'utiliser uniquement avec du papier thermosensible de 4 po sur 6 po.

9192

Les étiquettes de retour de format de 3 po sur 5 po ne sont plus disponibles. Veuillez utiliser des étiquettes de 4 po sur 6 po et des imprimantes thermiques.

9208

Les étiquettes publiques ne sont disponibles qu’en format PDF 8,5x11.

Exemples

Exemple de demande XML selon le module REST – Créer un retour autorisé

<authorized-return>
<create-public-key>true</create-public-key>
<service-code>DOM.EP</service-code>
<returner>
<name>Jane Doe</name>
<company>Capsule Corp.</company>
<domestic-address>
<address-line-1>2701 Return Avenue</address-line-1>
<city>Ottawa</city>
<province>ON</province>
<postal-code>K1A0B1</postal-code>
</domestic-address>
</returner>
<receiver>
<name>John Doe</name>
<company>Canada Post Corporation</company>
<domestic-address>
<address-line-1>2701 Riverside Drive</address-line-1>
<city>Ottawa</city>
<province>ON</province>
<postal-code>K1A0B1</postal-code>
</domestic-address>
</receiver>
<parcel-characteristics>
<weight>15</weight>
</parcel-characteristics>
<print-preferences>
<output-format>8.5x11</output-format>
</print-preferences>
<settlement-info></settlement-info>
</authorized-return>

Exemple de réponse XML selon le module REST – Créer un retour autorisé

<authorized-return-info>
<tracking-pin>12345678901234</tracking-pin>
<public-key-info>
<expiry-date>2020-02-22T23:59:59-05:00</expiry-date>
<url>https://www.canadapost-postescanada.ca/printlabel-imprimeretiquette?key-cle=6b7e21420a314e7b84c34a7be5fa8728</url>
</public-key-info>
<links>
<linkhref="https://ct.soa-gw.canadapost.ca/ers/artifact/76108cb5192002d5/21238/0"rel="returnLabel"media-type="application/pdf"index="0"></link>
</links>
</authorized-return-info>