Envois retournés

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

Créer un modèle générique pour les envois retournés – Module REST

Résumé

Nom : Créer un modèle générique pour les envois retournés
Raison pour utiliser le service :

Pour créer un certain nombre d'étiquettes d'expédition génériques du Service de retour (jusqu'à 100000) lorsque l'adresse de l'expéditeur et le poids de l'article sont inconnus

Données d'entrée :

Données d'entrée sur l'expédition

Données de sortie :

Liens vers les modèles créés et lien vers le service pour récupérer les étiquettes du Service de retour

Exemple d'erreur :

Erreurs liées à l'adresse ou aux caractéristiques du colis

Prochaine demande de service habituelle : Récupérer le prochain artefact générique pour les envois retournés.
Historique des versions : Notes de mise à jour
Créer un modèle générique pour les envois retournés

Créer un modèle générique pour les envois retournés

Détails sur la demande

Demande – Structure pour le service « Créer un modèle générique pour les envois retournés »

Point final

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

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.openreturn-v2+xml (Remarque : */* à la place de la valeur de l’en-tête affichera un message d’erreur)

Content-Type

application/vnd.cpc.openreturn-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"?>
<open-return xmlns=”http://www.canadapost.ca/ws/openreturn-v2”>
xxx
</open-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 modèle générique pour les envois retournés – Élément de la demande
Nom de l'élément Type Requis/Optionnel Description

open-return

Complexe

Requis

Structure XML générale pour les données d'entrée de la demande.

max-number-of-artifacts

Simple

Requis

Indique le nombre maximal d'artefacts (étiquettes du Service de retour) que vous pouvez générer et récupérer à l'aide de ce modèle. Il doit s'agir d'une valeur numérique se situant entre « 1 » et « 100 000 ».

service-code

Simple

Requis

(32 caractères alphanumériques)

Le Service de retour convient seulement pour les envois retournés du régime intérieur.

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

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 pendant le formatage des adresses.

name

Simple

Requis

(44 caractères)

company

Simple

Optionnel

(44 caractères)

domestic-address

Complexe

Requis

Cette structure contient les données d'adressage du destinataire.
Les champs vides seront retirés pendant le formatage des adresses.

address-line-1

Simple

Requis

(44 caractères)
Ligne d'adresse 1 du destinataire.

address-line-2

Simple

Optionnel

(44 caractères)
Ligne d'adresse 2 du destinataire.

city

Simple

Requis

(40 caractères)
Ville du destinataire.

province

Simple

Requis

(2 caractères)
Province du destinataire.

postal-code

Simple

Requis

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

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.

Remarque : Le format 3 po sur 5 po a été éliminé en juin 2016, mais pendant une période provisoire, il sera accepté et converti en format 4 po sur 6 po.

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}
Cet élément indique si les directives d'emballage doivent être inscrites sur l'étiquette.
Si cet élément n'est pas précisé, la valeur « Faux » s'affiche par défaut.

customer-input-type

Simple

Optionnel

(20 caractères alphanumériques)

Utiliser ces éléments pour créer des étiquettes de retour qui contiennent un espace dans lequel vos clients peuvent entrer des données, comme un numéro de pièce, un numéro d’UGS, etc.

Ce champ ne s’applique qu’aux étiquettes de 4 x 6 et de 8,5 x 11.

Les valeurs valides sont les suivantes :

Code Description de l’étiquette
INVOICE Invoice No / No de facture
ITEM Item No / No d’article
ORDER Order No / No de commande
PART Part No / No de pièce
PO PO No / No de bon de comm.
RETURN Return No / No de retour
RSA RSA No / No d’ARM
SERIAL Serial No / No de série
SKU SKU No / No UGS

settlement-info

Complexe

Requis

Cette structure contient le numéro de convention de colis de départ standard aux fins de vérification.

contract-id

Simple

Requis

(10 caractères numériques)
Requis pour utiliser le service de retour générique. Seuls les clients commerciaux de Postes Canada titulaires d'une convention établie en fonction du volume peuvent utiliser le service.

Demande – Diagramme XML

Voici la structure hiérarchique des éléments XML pour la demande de création d'un modèle générique pour les envois retournés.

Créer un modèle générique pour les envois retournés – Structure de la demande XML

Créer un modèle générique pour les envois retournés – Structure de la demande XML

Détails de la réponse

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

Créer un modèle générique pour les envois retournés – Élément de la réponse
Nom de l'élément Type Description

open-return

Complexe

Il s'agit de l'élément XML de niveau supérieur pour la réponse.
Cette structure contient des renseignements sur la création d'un modèle générique pour les envois retournés.

artifacts-remaining

Simple

Il s'agit d'une valeur numérique désignant le nombre d'artefacts restants qui peuvent être utilisés. Elle est habituellement définie en fonction du nombre d'étiquettes dans la demande.

links

Complexe

générique pour les envois retournés qui vient d'être créé.

link

Complexe

La structure des liens comprend trois éléments de liens, c'est-à-dire un pour « rel=”self” », un pour « rel=”details” » et un pour « rel=”nextArtifact” ».

Exemples

<link
href="https://XX/rs/12435/454545/openreturn/676767
rel="self"
media-type="application/vnd.cpc.openreturn-v2+xml" />

<link
href="https://XX/rs/12435/454545/openreturn/6767/details
rel="details"
media-type="application/vnd.cpc.openreturn-v2+xml" />

<link
href="https://XX/rs/12435/454545/openreturn/6767676
rel="nextArtifact"
media-type="application/vnd.cpc.openreturn-v2+xml" />

Chaque lien compte les trois attributs suivants :

  1. href. String. Il s'agit du point final pouvant être utilisé pour présenter une demande de service à l'aide du code HTTP GET, POST ou DELETE aux fins d'exécution des services suivants : – Obtenir le modèle générique pour les envois retournés
    – Obtenir les détails sur le modèle générique pour les envois retournés
    – Récupérer le prochain artefact générique pour les envois retournés
    – Supprimer le modèle générique pour les envois retournés.

  1. rel. String. Cela désigne l'objectif du lien. Dans ce cas, il y a trois valeurs possibles pour « rel= », notamment :

    rel="self"
    Cela signifie que le lien « href » est un pointeur lié au modèle générique pour les envois retournés qui vient d'être créé (p. ex. il peut être utilisé pour présenter une demande de service [en utilisant le code HTTP GET]) :
    – Service « Obtenir le modèle générique pour les envois retournés »
    – Service « Supprimer le modèle générique pour les envois retournés » pour le modèle créé

    rel="details"
    Cela signifie que le lien « href » est un pointeur pouvant être utilisé pour présenter une demande de service « Obtenir les détails sur le modèle générique pour les envois retournés » (en utilisant le code HTTP GET) pour le modèle créé.

    rel="nextArtifact"
    Cela signifie que le lien « href » est un pointeur permettant au client d'obtenir le prochain artefact (p. ex. étiquette) disponible aux fins de récupération. Par exemple, le lien « href » peut être utilisé (à l'aide du code HTTP POST) pour présenter une demande de service « Obtenir le prochain artefact générique pour les envois retournés » pour le modèle qui vient tout juste d'être créé.

  1. media-type. L'attribut lié au type de média désigne le format et la structure de toutes les données d'entrée supplémentaires qui sont nécessaires pour présenter une demande de service en ligne désigné « href ». Il s'agit habituellement d'une chaîne désignant la version pertinente des services en ligne de Postes Canada pour les envois retournés.

Réponse – Diagramme XML

Le diagramme suivant présente la structure XML de la réponse pour le service « Créer un modèle générique pour les envois retournés ».

Créer un modèle générique pour les envois retournés – Structure de la réponse XML

Créer un modèle générique pour les envois retournés – 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.

Les messages d'erreur possibles pour ce service sont les suivants :

Code de statut HTTP Erreur d'application Message
500 S.O. Les détails liés à l’erreur de validation du schéma sont fournis.
412 9999

Exemples

Exemple de demande XML selon le module REST – Créer un modèle générique pour les envois retournés

<open-return>
<max-number-of-artifacts>10</max-number-of-artifacts>
<service-code>DOM.EP</service-code>
<receiver>
<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>
<print-preferences>
<output-format>8.5x11</output-format>
</print-preferences>
<settlement-info>
<contract-id>12345678</contract-id>
</settlement-info>
</open-return>

Exemple de réponse XML selon le module REST – Créer un modèle générique pour les envois retournés

<open-return-info>
<artifacts-remaining>10</artifacts-remaining>
<links>
<linkrel="self"href="https://ct.soa-gw.canadapost.ca/rs/0007023211/0007023211/openreturn/349641323786705649"media-type="application/vnd.cpc.openreturn-v2+xml"></link>
<linkrel="details"href="https://ct.soa-gw.canadapost.ca/rs/0007023211/0007023211/openreturn/349641323786705649/details"media-type="application/vnd.cpc.openreturn-v2+xml"></link>
<linkrel="nextArtifact"href="https://ct.soa-gw.canadapost.ca/rs/0007023211/0007023211/openreturn/349641323786705649/artifact"media-type="application/pdf"></link>
</links>
</open-return-info>