Exigences du service Web pour les numéros d'autorisation de retour – Module SOAP

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 protocole SOAP standard et de nos fichiers WSDL.

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.

Votre service Web doit intégrer un accès sécuritaire. Lorsque nous avons recours à votre service, nous inclurons le nom d'utilisateur et le mot de passe dans l'en-tête du service Web pour la sécurité dans le cadre de notre demande de service selon le module SOAP.

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.

É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	Fait partie de l'élément « ValidateRsa ». Numéro d'autorisation du service de retour fournir par le client pour récupérer une étiquette du Service de retour. Contient de 1 à 15 caractères spéciaux ou alphanumériques. La valeur PING spéciale « 99999999999999 » doit toujours générer l'élément « ValidationStatus = true ».
RsaNumberIssueDate	Optionnel	Fait partie de l'élément « ValidateRsa ». (Pour utilisation ultérieure) Date à laquelle le numéro d'autorisation du service de retour a été émis au client. Format : AAAA-MM-JJ
AdditionalInfo	Optionnel	Fait partie de l'élément « ValidateRsa ». (Pour utilisation ultérieure) Jusqu'à 20 caractères. Renseignements supplémentaires précisés dans la politique que le client doit fournir (p. ex. numéro de facture, numéro d'article, numéro de référence).

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

Fichiers WSDL

Condition d'erreur

Si nous ne sommes pas autorisés à utiliser le service ou si le service ne peut pas être exécuté correctement, on considérera qu'il s'agit d'une condition d'erreur. Votre service Web devrait générer une anomalie du module SOAP. De plus, tous les renseignements descriptifs obtenus à partir du service dorsal doivent être intégrés dans le corps de l'anomalie du module SOAP.

Examples

Exemple de demande XML selon le module SOAP

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/
xmlns:val="http://www.canadapost.ca/webservices/validatersa"> 
<soapenv:Header> 
<wsse:Security soapenv:mustUnderstand="1"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> 
<wsse:UsernameToken wsu:Id="UsernameToken-1">
<wsse:Username>test</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">test</wsse:Password>
<wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary">ITB53//D6aw8hS+EWxI1NA==</wsse:Nonce>
<wsu:Created>2012-09-22T16:59:01.454Z</wsu:Created>
</wsse:UsernameToken> 
</wsse:Security> 
</soapenv:Header>
<soapenv:Body>
<val:ValidateRsa>
<val:RsaNumber>99999999999999</val:RsaNumber>
<val:RsaNumberIssueDate>2012-09-22</val:RsaNumberIssueDate>
<val:AdditionalInfo>PO123-45678-XY</val:AdditionalInfo>
</val:ValidateRsa>
</soapenv:Body>
</soapenv:Envelope>

Exemple de réponse XML selon le module SOAP

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> 
<s:Header> 
<o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"> 
<u:Timestamp u:Id="_0">
<u:Created>2012-09-22T20:03:36.751Z</u:Created>
<u:Expires>2012-09-22T20:08:36.751Z</u:Expires>
</u:Timestamp>  
</o:Security>
</s:Header>
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
<ValidateRsaResponse xmlns="http://www.canadapost.ca/webservices/validatersa">
<ValidationStatus xmlns="">true</ValidationStatus>
</ValidateRsaResponse>
</s:Body>
</s:Envelope>

Exemple de réponse selon le module SOAP pour une condition d'erreur

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> 
<s:Header> 
<o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"> 
<u:Timestamp u:Id="_0">
<u:Created>2012-09-22T20:05:35.673Z</u:Created>
<u:Expires>2012-09-22T20:10:35.673Z</u:Expires>
</u:Timestamp>  
</o:Security>
</s:Header>
<s:Body
<s:Fault>
<faultcode>8304</faultcode> <faultstring xml:lang="en-US">Sample error</faultstring>
<s:Fault>
</s:Body>
</s:Envelope>