Soutien

    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" 
    } 
    ] 
    }