Exigences du service Web pour les numéros d'autorisation de retour - Module REST

Introduction

Au moment de la création d'une politique de retour de colis, vous avez la possibilité de demander à vos clients de saisir un numéro d'autorisation de retour pour récupérer une étiquette. Vous pouvez utiliser un numéro fixe ou bien nous fournir une adresse URL vers un service Web que vous hébergez, où se trouve votre liste de numéros d'autorisation uniques.

Lorsque vous créez votre politique de retour de colis dans « Mes retours » sur le site Web de Postes Canada, si vous sélectionnez l'option de service Web, le système vous demandera de saisir l'adresse URL, le nom d'utilisateur et le mot de passe pour votre service Web. Le présent document décrit les exigences propres au service Web.

Mise en œuvre

Votre service Web devrait être mis en œuvre à l'aide du style d'architecture REST standard.

Nous aurons recours à votre service Web pour valider le numéro d'autorisation de retour saisi par vos clients avant de leur permettre de récupérer une étiquette du Service de retour. Le service Web doit accepter ou refuser la demande d'autorisation. En cas de refus, nous ne permettrons pas à votre client de récupérer une étiquette du Service de retour.

Le nom d'utilisateur et le mot de passe requis pour accéder à votre point final seront inclus dans l'en-tête d'autorisation HTTP. Votre service Web se servira de ces renseignements pour authentifier notre demande de service.

Veuillez noter que votre service Web doit comprendre le numéro d'autorisation « 99999999999999 » (p. ex. 14 fois le chiffre « 9 »), ce qui devrait toujours indiquer qu'il s'agit d'un numéro valide. Postes Canada pourra ainsi sonder votre service Web au moyen de la commande PING pour déterminer s'il est opérationnel.

Exécution réussie

Si votre service Web termine toutes ses actions avec succès pour les données d'entrée fournies, vous générerez un code de statut HTTP de niveau 200 et vous afficherez les données de sortie figurant dans un élément XML de niveau supérieur.

Résumé du service Web

Nom :	Valider l'autorisation du service de retour
Raison pour utiliser le service :	Pour valider le numéro d'autorisation de retour fourni par un consommateur. Le service doit également comprendre une fonction du sondeur PING pour indiquer qu'il est opérationnel.
Données d'entrée :	Le numéro d'autorisation doit être validé. La date d'émission du numéro d'autorisation de retour et les renseignements supplémentaires précisés dans la politique figurent parmi les paramètres facultatifs.
Données de sortie :	Un indicateur de validité indique si le numéro d'autorisation est valide.

Détails sur la demande

Point final

GET https://[votre point final]/ValidateRsa/[RsaNumber]

En-têtes HTTP

Variable des en-têtes HTTP	Valeur
Accept	application/vnd.canadapost.rest+xml
Content-Type	application/vnd.canadapost.rest+xml
Authorization	Basic {Base64 encoding of userid:password}
Accept-language	en-CA

Corps du message

Le corps de la demande doit être laissé vide.

Éléments de réponse

Nom de l'élément	Usage	Description
ValidateRsa	Requis	Il s'agit de l'élément XML de niveau supérieur pour les données de la réponse.
ValidationStatus	Requis	Fait partie de l'élément « ValidateRsaResponse » Attribut booléen Faux – L'élément « RsaNumber » n'est pas valide. Vrai – L'élément « RsaNumber » est valide.

Condition d'erreur

Une condition d'erreur survient lorsqu'un utilisateur n'est pas autorisé à utiliser votre service Web ou que votre service ne peut pas être exécuté avec succès.

En cas de condition d'erreur, votre service Web doit générer un code de statut HTTP de niveau 400 ou 500. Selon le code de statut HTTP, vous pouvez également fournir un élément XML de niveau supérieur et une structure connexe pour les messages et les codes d'erreur dans le corps de la réponse.

Veuillez noter que vous générerez les données de sortie normales (sous un élément XML de niveau supérieur, au besoin), la structure XML d'erreur ou ni l'un ni l'autre (selon la nature de l'erreur).

Examples

Exemple de demande selon le module REST

GET https://[votre point final]/ValidateRsa//99999999999999? AdditionalInfo=PO123-45678-XY&RsaNumberIssueDate=2012-09-22 HTTP/1.1

Exemple de réponse selon le module REST – XML

HTTP/1.1 200 Good 
Content-Type: application/canadapost.rsa+xml 
<?xml version=”1.0” encoding=”UTF-8”?> 
<ns1:ValidateRsaResponse xmlns:ns1=”http://www.canadapost.ca/webservices/validatersa”> 
<ValidationStatus>true</ValidationStatus> 
</ns1:ValidateRsaResponse>

Exemple de réponse selon le module REST – XML pour une condition d'erreur

HTTP/1.1 500 Error 
Content-Type: application/canadapost.rsa+xml 
<?xml version=”1.0” encoding=”UTF-8”?> 
<ns2:Messages xmlns:ns2=”http://www.canadapost.ca/webservices/messages”>
<Message>
<Code>8304</Code>
<Description>Sample error</Description>
</Message>
</ns2:Messages>

Exemple de réponse selon le module REST – JSON

HTTP/1.1 200 Good
Content-Type: application/candapost.rsa+json
{
"ValidateRsaResponse":{ "ValidationStatus":true 
} 
}

Exemple de réponse selon le module REST – JSON pour une condition d'erreur

HTTP/1.1 500 Error
Content-Type: application/candapost.rsa+json

{
"Messages":[ 
{ "Code":"8304", "Description":"Sampleerror" 
} 
] 
}

Soutien