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 du message doit comporter l'élément XML de niveau supérieur « ValidateRsa », tel qu'il est décrit ci-dessous.
Éléments de la demande
| Element Name | Usage | Description |
|
ValidateRsa |
Requis |
Élément XML de niveau supérieur de la structure de la réponse. |
|
RsaNumber |
Requis |
|
|
RsaNumberIssueDate |
Optionnel |
|
|
AdditionalInfo |
Optionnel |
|
É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 |
|
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"
}
]
}