Repérage

Exemples de codes de repérage : Java (.zip) | PHP (.zip) | C# (.zip)

Obtenir un résumé du repérage – Module REST

Résumé

Nom : Obtenir un résumé du repérage
Raison de l'appel : Pour obtenir l'activité de repérage la plus récente ou importante pour un colis
Données d'entrée : Paramètres d'identification du colis
(p. ex., le NIP et le numéro de la CAL ou les paramètres de référence)
Données de sortie : Date, emplacement et type d'activité pour l'activité la plus récente ou la plus importante
Exemples d'erreurs : NIP introuvable, NIP en double
Prochains appels possibles : Obtenir les détails de repérage, Obtenir l'image de la signature,
Obtenir le certificat de confirmation de livraison
Historique des versions : Notes de mise à jour

Détails sur la demande

Structure de la demande pour obtenir un résumé du repérage

Point final

GET https://XX/vis/track/pin/{numéro d'identification du produit}/summary
ou
GET https://XX/vis/track/dnc/{numéro de la carte Avis de livraison}/summary
ou
GET https://XX/vis/track/ref/summary?mailingDateTo=YYYY-MM-DD
&mailingDateFrom=YYYY-MM-DD&referenceNumber={numéro de référence}
&customerNumber={numéro du client}&destinationPostalCode={code postal de destination}

Remplacez... Par...

XX (développement)

ct.soa-gw.canadapost.ca

XX (production)

soa-gw.canadapost.ca

{numéro d'identification du produit}

le numéro d'identification du produit (NIP)

{numéro de la carte Avis de livraison}

le numéro de la carte Avis de livraison (CAL)

YYYY-MM-DD

les dates de début et de fin

{numéro de référence}

la valeur que vous avez spécifié dans les champs customer-ref-1 ou customer-ref-2 lorsque vous avez créé l'envoi.

{numéro du client}

le numéro du client

{code postal de destination}

le code postal de destination du colis

En-têtes HTTP

Variable des en-têtes HTTP Valeur

Value

Accept

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

Authorization

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

Accept-language

en-CA ou fr-CA

Corps du message

Aucun

Paramètres de la demande

Le tableau suivant décrit les différents paramètres utilisés pour repérer le ou les colis pour lesquels l'information est demandée. Voici quelques exemples de ces paramètres :

  • Les paramètres intégrés directement à l'adresse du point final URI (p. ex., le {numéro d'identification du produit} et le {numéro de la carte Avis de livraison}).
  • Les paramètres fournis comme des paramètres de requête URI à la fin de l'adresse du point final URI (p. ex., les paramètres de référence)
Obtenir un résumé du repérage – REST – Paramètres de la demande
Nom du paramètre Type de paramètre Description/taille/format

Accès avec le numéro d'identification du produit (NIP)

{pin number}

Intégré directement
à l'URI

Le numéro d'identification du produit (NIP) est attribué par Postes Canada au cours de la création de l'étiquette d'expédition et utilisé aux fins de repérage.(12, 13 ou 16 caractères)

Lorsque vous exécutez une demande avec le NIP, il est obligatoire et il s'agit du seul paramètre nécessaire.

Le {numéro d'identification du produit} est intégré à l'URI comme suit :

XX/vis/track/pin/{numéro d'identification du produit}/summary

Accès avec le numéro de la CAL

{dnc number}

Intégré directement
à l'URI

Numéro de la carte Avis de livraison (CAL) : Le numéro sur la carte laissé par le personnel de livraison lorsqu'il n'y a personne à la maison pour recevoir la livraison.

(15 caractères numériques)

Lorsque vous exécutez une demande avec le numéro de la CAL, il est obligatoire et il s'agit du seul paramètre nécessaire.

Le {Numéro de la carte Avis de livraison} est intégré à l'URI comme suit :

XX/vis/track/dnc/{Numéro de la carte Avis de livraison}/summary.

Accès avec les paramètres de référence

customerNumber=XXXX

QParamètre de requête (facultatif)

La valeur du paramètre de requête du customerNumber peut être :

  • le numéro du client pour l'organisation qui entreprend l'expédition;
  • le numéro du client pour le client au nom duquel le colis a été expédié.

(10 caractères numériques)

Il s'agit d'un paramètre de requête facultatif. Si le paramètre de requête pour le customerNumber n'est pas précisé, le customer-number de l'utilisateur qui a été utilisé pour authentifier cette demande sera utilisé.

Si vous expédiez des colis au nom d'autres clients et que vous précisez leur numéro de client dans la demande, seuls les résultats de repérage des colis qui ont été expédiés au nom de ce client (et qui correspondent aux autres critères des paramètres de requête) sont renvoyés.

Si vous expédiez des colis au nom d'autres clients et que vous précisez votre propre numéro de client, vous recevrez des résultats de repérage pour tous les colis que vous avez expédiés vous-même, y compris tous les colis que vous avez expédiés au nom d'autres clients (à condition qu'ils correspondent aux autres critères des paramètres de requête).

reference
Number=XXXX

Paramètre de requête (obligatoire)

La valeur attribuée à un colis par l'expéditeur lorsque l'envoi a été créé. Cette valeur peut avoir été indiquée dans les champs « customer-ref1 » ou « customer-ref2 » du colis soumis.

(jusqu'à 35 caractères)

Lorsque vous exécutez une demande avec le paramètre de référence, le paramètre de requête du referenceNumber est obligatoire et doit être inclus.

Le service Obtenir un résumé de repérage fournit seulement les résultats du repérage pour les colis qui correspondent à la valeur du paramètre de requête referenceNumber.

destinationPostalCode=XXXX

Paramètre de requête (facultatif)

Le code postal de destination, le code ZIP ou l'identificateur postal du colis dans son pays de destination. Il s'agit de la valeur qui serait fournie dans l'élément « postal-zip-code » dans une demande de création d'un envoi.

Le format est l'un des suivants :

  • six caractères alphanumériques pour le Canada
    (A9A9A9)
  • code numérique de cinq chiffres ou de cinq chiffres avec un tiret et quatre chiffres supplémentaires pour les É.-U.
    (99999 or 99999-9999)
  • chaîne de caractères – jusqu'à 14 caractères (tout format) pour les autres pays.

Le paramètre de requête destinationPostalCode est facultatif.

Lorsqu'il est offert, le service Obtenir un résumé de repérage fournit seulement les résultats du repérage pour les colis qui correspondent à la valeur du paramètre de requête destinationPostalCode.

Nota : Pour les codes ZIP dont le format est « 99999-9999 », seulement les cinq premiers caractères sont utilisés dans la mise en correspondance.


mailingDateFrom=
YYYY-MM-DD

Paramètre de requête (obligatoire)

La combinaison des paramètres de requête mailingDateFrom et mailingDateTo définit une plage de dates pendant laquelle les colis en question ont été expédiés.

Le format est : aaaa-mm-jj.

La valeur mailingDateFrom ne peut pas être antérieure à deux mois civils à partir de la date actuelle.

Lorsque vous exécutez une demande avec un paramètre de référence, les paramètres de requête mailingDateFrom et mailingDateTo sont obligatoires et doivent être inclus.

Le service Obtenir un résumé de repérage fournit seulement les résultats du repérage pour les colis qui ont été expédiés à l'intérieur de la plage de dates précisées par les paramètres de requête mailingDateFrom et mailingDateTo.

mailingDateTo=
YYYY-MM-DD

Paramètre de requête (obligatoire)

Détails de la réponse

Éléments de réponse

Obtenir un résumé de repérage – REST – Aperçu détaillé des éléments de réponse
Nom du champ Description

tracking-summary

Niveau supérieur de la structure XML

pin-summary

Contient la réponse pour le NIP précis.

Fait partie de l'élément <tracking-summary>.

pin

(15 caractères numériques)

Numéro d'identification du colis (NIP) pouvant être utilisé par le client pour faire appel aux services de repérage.

origin-postal-id

Trois premiers caractères du code postal d'origine pour les destinations canadiennes.

^[ABCEGHJKLMNPRSTVXY]{1}\d{1}[A-Z]{1}

Dans le cas d'un colis d'arrivée du régime international, ce champ est vide ou il contient l'identificateur postal du pays d'origine.

destination-postal-id

Trois premiers caractères du code postal de destination pour les colis qui doivent être livrés au Canada.

^[ABCEGHJKLMNPRSTVXY]{1}\d{1}[A-Z]{1}

Pour les colis du régime international, il s'agit de l'identificateur postal du pays de destination (p. ex., le code ZIP pour les colis à destination des É.-U.) ou un identificateur du pays de destination.

destination-province

Code de province à deux caractères pour la destination.

« indicateurs postaux » – abréviations utilisées par Postes Canada (ISO 3166-2) pour les colis du régime intérieur.

Les colis à destination des É.-U. et du régime international portent l'identificateur postal du pays de destination (p. ex., le code ZIP pour les colis à destination des É.-U.).

service-name

Nom du service de Postes Canada dans la langue précisée. Le service-name sera indiqué par défaut en anglais si la langue n'est pas précisée.

Pour les colis d'arrivée du régime international, le champ relatif au nom du service est vide ou il contient le nom du service fourni par l'expéditeur d'origine, le cas échéant.

mailed-on-date

aaaa-mm-jj

Date de la première activité pour l'article. Si l'article a été expédié à partir d'une destination internationale, cette date peut ne pas être indiquée.

expected-delivery-date

aaaa-mm-jj

Date à laquelle l'article doit arriver à l'adresse de destination pour les adresses au Canada.

Si l'article a été expédié à destination ou en provenance de l'étranger, cette date peut ne pas être indiquée.

actual-delivery-date

aaaa-mm-jj

Date à laquelle l'article a été livré.

N'apparaît pas si l'article n'a pas été livré ou si les données de livraison provenant d'un organisme international n'ont pas été fournies pour un envoi du régime international.

delivery-option-completed-ind

0 – Au moins une option n'a pas été satisfaite

1 – toutes les options ont été satisfaites

2 – aucune option n'a été trouvée

event-date-time

aaaammjj :hhmmss

Horodatage de l'activité la plus récente ou la plus importante.

event-description

Brève description de l'activité.

attempted-date

aaaa-mm-jj – Date à laquelle une tentative de livraison à été effectuée.

Pour les articles envoyés au Canada ou les articles du régime intérieur, il sera indiqué qu'une tentative infructueuse de livraison a été effectuée à la date précisée.

customer-ref-1

(chaîne de caractères jusqu'à 35 caractères)

Valeur fournie par l'expéditeur (customer-ref-1) lorsque l'envoi a d'abord été créé auprès de Postes Canada. L'ensemble de caractères en français est appuyé par cette interface.

customer-ref-2

(chaîne de caractères jusqu'à 35 caractères)

Valeur fournie par l'expéditeur (customer-ref-2) lorsque l'envoi a d'abord été créé auprès de Postes Canada. L'ensemble de caractères en français est appuyé par cette interface.

return-pin

Si une étiquette Service de retour (NIP) a été imprimée en même temps que l'envoi a été créé et que l'envoi est retourné, le NIP de retour est affiché.

event-type

Valeur dans ce champ qui montre quel type d'activité est indiqué pour cet article.

event-location

Pour une activité correspondant à un balayage ou à une livraison, cette valeur indiquera l'emplacement où l'activité a eu lieu.

signatory-name

Si l'événement indiqué comme la dernière activité la plus importante est une signature, le texte de ce champ renferme le nom du signataire.

Remarque : Pour une protection accrue de la vie privée et de la sécurité, le champ du nom du signataire sera dorénavant toujours vide. Il pourrait être retiré dans une version future.

code

ID relatif à l'échec d'une recherche.

description

Message textuel relatif au code d'usager.

Messages d'erreur possibles

Une demande bien structurée peut recevoir l'un des messages d'erreur d'application suivants :

Code Description Notes

002

NIP en double

Reçu pour les recherches de NIP ou de CAL lorsque des NIP en double ont été constatés.

004

Aucun historique pour le NIP

Aucun résultat de repérage obtenu d’après les paramètres fournis. Vérifiez les paramètres et l’ordre des dates d’expédition et de destination.

006

Champs du numéro de référence, de la date d'expédition et du code postal de destination qui sont requis pour effectuer une recherche du numéro de référence.

Reçu seulement pour les recherches de numéro de référence.

008

Date invalide

Pour les recherches du numéro de référence des résumés, les dates de plus de deux mois entraîneront une répétition de l'erreur.

Diagramme XML du message

Les recherches de NIP et de CAL fournissent un seul résultat de « pin-summary ». Une recherche du numéro de référence peut donner de multiples résultats de « pin-summary » si plus d'un article satisfait aux critères de recherche.

Message diagram

Exemples

Demande liée aux NIP

GET https://XX/vis/track/pin/7023210039414604/summary

Réponse liée aux NIP

<tracking-summary>
<pin-summary>
<pin>7023210039414604</pin>
<origin-postal-id>K1G</origin-postal-id>
<destination-postal-id>K0J</destination-postal-id>
<destination-province>ON</destination-province>
<service-name>Expedited Parcels</service-name>
<mailed-on-date>2011-04-04</mailed-on-date>
<expected-delivery-date>2011-04-05</expected-delivery-date>
<actual-delivery-date/>
<delivery-option-completed-ind>2</delivery-option-completed-ind>
<event-date-time>20110404:133457</event-date-time>
<event-description>Order information received by Canada Post</event-description>
<attempted-date/>
<customer-ref-1>APRIL1REF1A</customer-ref-1>
<customer-ref-2>APRIL1REF1C</customer-ref-2>
<return-pin/>
<event-type>INDUCTION</event-type>
<event-location/>
<signatory-name/>
</pin-summary>
</tracking-summary>

Demande liée à la CAL

GET https://XX/vis/track/dnc/315052413796541/summary

Réponse liée à la CAL

<tracking-summary>
<pin-summary>
<pin>1680678172650919</pin>
<origin-postal-id/>
<destination-postal-id>K0B</destination-postal-id>
<destination-province>ON</destination-province>
<service-name>Xpresspost</service-name>
<mailed-on-date>2011-01-10</mailed-on-date>
<expected-delivery-date>2011-01-12</expected-delivery-date>
<actual-delivery-date>2011-01-27</actual-delivery-date>
<delivery-option-completed-ind>2</delivery-option-completed-ind>
<event-date-time>20110127:140229</event-date-time>
<event-description>Item successfully delivered</event-description>
<attempted-date>2011-01-11</attempted-date>
<customer-ref-1/>
<customer-ref-2/>
<return-pin/>
<event-type>DELIVERED</event-type>
<event-location/>
<signatory-name/>
</pin-summary>
</tracking-summary>

Demande liée au numéro de référence

GET https://XX/vis/track/ref/summary?mailingDateTo=2011-04-05&destinationPostalCode=K0J1T0&customerNumber=1111111&mailingDateFrom=2011-03-01&referenceNumber=APRIL1REF1A

Réponse liée au numéro de référence

<tracking-summary>
<pin-summary>
<pin>1681334332936901</pin>
<origin-postal-id>S6V</origin-postal-id>
<destination-postal-id></destination-postal-id>
<destination-province></destination-province>
<service-name></service-name>
<mailed-on-date>2010-01-05</mailed-on-date>
<expected-delivery-date></expected-delivery-date>
<actual-delivery-date>2010-01-06</actual-delivery-date>
<delivery-option-completed-ind>2</delivery-option-completed-ind>
<event-date-time>20100106:084923</event-date-time>
<event-description>Paiement CR - SPL</event-description>
<attempted-date>2010-01-06</attempted-date>
<customer-ref-1></customer-ref-1>
<customer-ref-2></customer-ref-2>
<return-pin></return-pin>
<event-type>OUT</event-type>
<event-location></event-location>
<signatory-name></signatory-name>
</pin-summary>
</tracking-summary>