Envois retournés

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

Créer un retour autorisé – Module SOAP

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 : Liste d'artefacts (sous forme de numéros d'identification propres aux artefacts) pouvant être utilisée pour imprimer les étiquettes
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

WSDL: authreturn.wsdl
Point final (Conception) : https://ct.soa-gw.canadapost.ca/rs/soap/authreturn/v2
Point final (Production) : https://soa-gw.canadapost.ca/rs/soap/authreturn/v2
Espace de nommage : http://www.canadapost.ca/ws/soap/authreturn/v2
Opération : CreateAuthorizedReturn

Corps – SOAP

La présente section décrit les éléments XML d'entrée pour ce service. Pour obtenir la structure hiérarchique, consultez le diagramme XML.

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

create-authorized-return-request

complexe

requis

Élément XML de niveau supérieur de la structure de la réponse.

mailed-by

simple

requis

(1 à 10 caractères numériques)

Il s'agit du numéro de client à 10 chiffres du client « Expédié par ».

Si le numéro fourni compte moins de 10 chiffres, le système ajoutera des zéros au début.

mobo

simple

optionnel

(1 à 10 caractères numériques)

Il s'agit du numéro de client à 10 chiffres du client « Expédié au nom de ».

S'il manque cet élément, le numéro du client « Expédié par » s'affichera par défaut.

Si le numéro fourni compte moins de 10 chiffres, le système ajoutera des zéros au début.

locale

simple

optionnel

Indique votre langue de préférence pour recevoir les messages d'erreur.

EN = Anglais
FR = Français

Si aucune valeur n'est fournie, la langue par défaut est « Anglais ».

authorized-return

complexe

requis

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

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'agir 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.

Il 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. 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 largeur 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 données codées en base64. Décodez le fichier pour obtenir les 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 éléments XML figurant dans la réponse à la demande de création d'un retour autorisé. Pour obtenir la hiérarchie de la réponse, consultez le diagramme XML.

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

create-authorized-return-response

complexe

Il s'agit de l'élément XML de niveau supérieur de la structure de la réponse.

Il affichera les résultats d'une exécution réussie ou la structure d'un message d'erreur.

authorized-return

complexe

Structure XML contenant les renseignements sur le retour autorisé.

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

NIP de repérage pour l'envoi. Il 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).

artifacts

complexe

Structure contenant l'ensemble des étiquettes et des documents produits pour le retour autorisé.

artifact

complexe

Structure contenant une seule étiquette ou un seul document produit pour le retour autorisé.

type

attribut

Il s'agit de l'attribut de artifact.

Il désigne l'objectif du lien et le type de renseignements qui y seront récupérés dans ce cas. "returnLabel".

artifact-id

simple

Identificateur numérique pour un document précis ayant été généré pour le retour autorisé.

Remarque : Après que vous avez créé un retour autorisé, vous avez cinq jours civils à récupérer l'étiquette de retour avant que l'artefact 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

La réponse à des conditions d'erreur pour ce service en ligne respecte l'approche standard SOAP liée à la réponse d'erreur, laquelle est utilisée pour tous les services en ligne de Postes Canada. Pour obtenir de plus amples renseignements, consultez les Principes de base liés au module SOAP pour les services en ligne de Postes Canada.

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 SOAP – Créer un retour autorisé

<create-authorized-return-request>
<mailed-by>1111111</mailed-by>
<locale>EN</locale>
<authorized-return>
<create-public-key>true</create-public-key>
<service-code>DOM.EP</service-code>
<returner>
<name>Jane Doe</name>
<domestic-address>
<address-line-1>111 Return From Drive</address-line-1>
<city>Ottawa</city>
<prov-state>ON</prov-state>
<postal-zip-code>K1A0B1</postal-zip-code>
</domestic-address>
</returner>
<receiver>
<name>John Doe</name>
<company>Return Solutions Incorporated</company>
<email>RSI@RSI.com</email>
<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>
<settlement-info></settlement-info>
</authorized-return>
</create-authorized-return-request>

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

<create-authorized-return-response>
<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>
<artifacts>
<artifacttype="returnLabel">
<artifact-id>21238</artifact-id>
</artifact>
</artifacts>
</authorized-return-info>
</create-authorized-return-response>