Activer les retours en libre-service

Pour commencer

Avant d’intégrer l’API des retours autorisés, assurez-vous d’effectuer les étapes préalables et de configuration suivantes. Pour obtenir un aperçu plus détaillé, consultez le guide de démarrage rapide.

Préalables

Remarque : Pour utiliser l’API, vous devez d’abord avoir un compte commercial de Postes Canada valide qui fournit un numéro de compte. Les membres de la clientèle commerciale ont habituellement une convention commerciale officielle. Elle fournit un numéro de convention et la facturation est portée au compte. Les membres du programme Solutions pour petites entreprises peuvent accéder à l’API à l’aide de leur numéro de compte SPPE. Les services de retour sont généralement facturés à la carte de crédit qui figure dans votre profil ou votre compte d’entreprise.

Une fois que vous avez un compte, voici les prochaines étapes à suivre pour utiliser l’API :

1. Créez un identifiant pour le site postescanada.ca.
2. Inscrivez-vous au Portail des développeurs de Postes Canada.
3. Obtenez vos identifiants pour les environnements d’essai et de production de l’API (clé API et Code API Secret). 

Points de terminaison des API

Environnement de production

https://api.canadapost-postescanada.ca/prod/devportal-portaildesdeveloppeurs/returns/v1/{mailedBy}/{mobo}/authorized-returns

Remarque : Bien qu’il n’y ait aucuns frais pour la création de l’étiquette de retour, nous recommandons de procéder à un test dans l’environnement de test. Ainsi, vous éviterez de créer accidentellement des expéditions réelles ou de déclencher des processus liés aux stocks et à l’exécution des commandes en aval. Si vous devez voir le code à barres et le code QR définitifs et de haute fidélité, vous devrez créer une étiquette dans l’environnement de production.

En-têtes requis

Retours autorisés v2

• Type de contenu : application/vnd.cpc.apic.authreturn+json
• Acceptation : application/vnd.cpc.apic.authreturn+json
• Autorisation : Bearer
• Méthode HTTP : POST

Options d’étiquettes de retour

Utilisez les options d’étiquettes de retour suivantes ensemble ou séparément. Les options de retour sont déterminées en fonction de l’étiquette en transmettant les champs JSON appropriés dans la demande d’API.

Choix pour le retour

Comptoir ou impression à domicile

Laissez les gens choisir s’ils veulent commencer le processus de retour à la maison (impression à domicile) ou au comptoir postal à l’aide d’un code QR sans étiquette.

Remarque : Vous ne pouvez pas activer les options de code QR traditionnel et de code QR sécurisé en même temps.

Code QR traditionnel

L’option de code QR traditionnel est flexible et pratique pour les personnes qui veulent faire l’impression à domicile ou dans un point de vente au détail de Postes Canada.

Pour activer l’option de code QR traditionnel, utilisez :

{
  "createPublicKey": true 
  "createQrCode": true 
}

Code QR sécurisé

L’option de code QR sécurisé offre une protection supplémentaire contre la fraude en rendant obligatoire l’impression des étiquettes aux comptoirs postaux. Par conséquent, seul le personnel de la vente au détail dans les emplacements de Postes Canada peut imprimer les étiquettes de retour.

Pour activer l’option de code QR sécurisé, utilisez :

{
  "retailOnly": true
}

Qu’est-ce que la clé publique? Cette clé sert à créer l’étiquette qui sera imprimée à la maison. 

{
  "createQrCode": true
}

Retours sans emballage

Réduisez les mécontentements de la clientèle et les exigences d’emballage, et offrez une commodité accrue lors du dépôt grâce aux retours sans emballage.

Marche à suivre

Les gens apportent leur article non emballé à un point de vente au détail. Ensuite, le personnel de la vente au détail emballe l’article et imprime l’étiquette de retour.

Remarque : Vous pouvez combiner les retours sans emballage avec un code QR traditionnel ou un code QR sécurisé (voir ci-dessus). Les gens peuvent apporter un article non emballé si vous permettez les retours sans emballage. Le code QR détermine seulement qui imprime l’étiquette (clientèle ou personnel de la vente au détail).

Pour activer les retours sans emballage, utilisez :

{
  "boxFree": true
}

Si vous ne voulez pas offrir les retours sans emballage, utilisez :

{
  "boxFree": false
}

Exigences pour les retours sans emballage

Veuillez prendre note des exigences suivantes pour utiliser les retours sans emballage :

• L’emballage est fourni au bureau de poste seulement lorsque le retour est autorisé.  
• Tous les articles composant un seul envoi doivent entrer dans une enveloppe dont les dimensions maximales sont de 47 cm sur 61 cm (18,5 po sur 24 po), plus un 5 cm (2 po) supplémentaire pour le bord.  
• Le poids des articles retournés doit être inférieur à 22 kg (48,5 lb).

Pour obtenir de plus amples renseignements, consultez la section 2.4.2 du Guide du client pour les services de colis. 

Codes à barres de retour supplémentaires

Accélérez le traitement et améliorez le suivi en ajoutant un code à barres 2D ou LINÉAIRE balayable supplémentaire.

Remarque : Vous pouvez activer ce type de retour avec toute autre option de retour indiquée ci-dessus.

Pour activer ces codes à barres de retour supplémentaires, utilisez :

{
  "customerBarcode": 1234567890
}

 (remplacer « 1234567890 » par une combinaison alphanumérique de 16 caractères de votre choix)

{
   "customerBarcodeType": "2D"
}

OU

{
  "customerBarcodeType": "LINEAR"
}

Remarque : Le champ customerBarcode est un élément graphique balayable, contrairement au champ customerRef1, qui est une métadonnée en texte seulement. 

Explication des champs de l’API

Remarque : Il ne s’agit pas d’une liste exhaustive des champs de l’API de retour. 

Exemple de demandes

Code QR traditionnel

Exemple de demande avec l’option sans emballage et un code à barres supplémentaire

{
  "createPublicKey": true,
  "createQrCode": true,
  "boxFree": true,
  "customerBarcode": "ORD12345",
  "customerBarcodeType": "LINEAR",
  "serviceCode": "DOM.EP",
  "returner": {
    "name": "John Smith",
    "company": "Optional",
    "domesticAddress": {
      "addressLine1": "502 MAIN ST N",
      "city": "Ottawa",
      "province": "ON",
      "postalCode": "K2K0B1"
    }
  },
  "receiver": {
    "name": "Ryuko Saito",
    "company": "Optional",
    "email": "test@test.com",
    "receiverVoiceNumber": "111-111-1111",
    "domesticAddress": {
      "addressLine1": "23 jardin private",
      "city": "Ottawa",
      "province": "ON",
      "postalCode": "K1K4T3"
    }
  },
  "printPreferences": {
    "outputFormat": "8.5x11",
    "encoding": "PDF",
    "showPackingInstructions": true
  },
  "settlementInfo": {
    "paidByCustomer": "1234567",
    "contractId": "12345678"
  },
  "references": {
    "customerRef1": "ref1",
    "customerRef2": "ref2"
  },
  "notifications": {
    "notificationsList": [
      {
        "email": "test@test.com",
        "onShipment": true,
        "onException": true,
        "onDelivery": true
      }
    ]
  }
}

Code QR sécurisé sans étiquette

Exemple de demande avec l’option sans emballage et un code à barres supplémentaire

{
  "createQrCode": true,
  "boxFree": true,
  "retailOnly": true,
  "customerBarcode": "ORD12345",
  "customerBarcodeType": "LINEAR",
  "serviceCode": "DOM.EP",
  "returner": {
    "name": "John Smith",
    "company": "Optional",
    "domesticAddress": {
      "addressLine1": "502 MAIN ST N",
      "city": "Ottawa",
      "province": "ON",
      "postalCode": "K2K0B1"
    }
  },
  "receiver": {
    "name": "Ryuko Saito",
    "company": "Optional",
    "email": "test@test.com",
    "receiverVoiceNumber": "111-111-1111",
    "domesticAddress": {
      "addressLine1": "23 jardin private",
      "city": "Ottawa",
      "province": "ON",
      "postalCode": "K1K4T3"
    }
  },
  "printPreferences": {
    "outputFormat": "8.5x11",
    "encoding": "PDF",
    "showPackingInstructions": true
  },
  "settlementInfo": {
    "paidByCustomer": "1234567",
    "contractId": "12345678"
  },
  "references": {
    "customerRef1": "ref1",
    "customerRef2": "ref2"
  },
  "notifications": {
    "notificationsList": [
      {
        "email": "test@test.com",
        "onShipment": true,
        "onException": true,
        "onDelivery": true
      }
    ]
  }
}

Meilleures pratiques

Si vous offrez plusieurs options de retour, nous vous recommandons fortement d’indiquer clairement ces choix dans l’interface utilisateur de votre application. Vous offrirez ainsi une expérience fluide et transparente à la clientèle.

Vous trouverez ci-dessous quelques exemples utilisant nos propres éléments de l’interface utilisateur.

Exemple 1

Retours d’articles sans étiquette ni emballage

Une personne apporte un article non emballé (voir Retours sans emballage)

Dans ce scénario, la personne apporte son article non emballé à un point de vente au détail. Le personnel de la vente au détail emballe l’article et imprime l’étiquette de retour.

Rappel : Vous pouvez combiner les retours sans emballage avec un code QR traditionnel ou un code QR sécurisé (voir ci-dessus).  

L’article doit respecter les dimensions standard des colis de Postes Canada après avoir été emballé.

Exemple de critères d’admissibilité pour l’option sans emballage :

Exemple de directives pour retourner l’emballage d’origine du produit (le cas échéant/si disponible) :

Exemple 2

Code QR traditionnel ou code QR sécurisé

Dans ce scénario :

• La personne peut choisir d’imprimer l’étiquette à la maison à partir du fichier PDF fourni au moyen de la clé publique, ou elle peut montrer le code QR à un point de vente au détail pour que le personnel de la vente au détail puisse imprimer l’étiquette (code QR traditionnel).

OU

• La personne doit montrer le code QR à un point de vente au détail et seul le personnel de la vente au détail peut imprimer l’étiquette (code QR sécurisé).

Exemple 3 

Impression à la maison

Dans ce scénario, la personne reçoit une étiquette PDF téléchargeable.

Essais et dépannage

Erreurs fréquentes et comment les corriger

Avant d’essayer autre chose, nous vous recommandons de consulter notre liste d’erreurs courantes et leurs codes. 

Voici d’autres erreurs qui peuvent se produire et les raisons connexes.

ID de contrat non valide

Cette erreur se produit parce que la combinaison du numéro de compte et du numéro de convention n’est pas valide dans le système.

Combinaisons des champs incorrectes

Un exemple de combinaison erronée des champs est l’utilisation des champs retailOnly et createPublicKey dans une seule demande.

• Le champ retailOnly est utilisé pour générer un code QR sécurisé qui peut seulement être balayé et traité par le personnel des points de vente au détail autorisés de Postes Canada. L’information sur l’étiquette d’expédition intégrée dans le code QR n’est pas accessible à l’extérieur de ces installations désignées.
• Le champ createPublicKey est utilisé pour générer une URL publique pour l’étiquette d’expédition. La clientèle peut donc imprimer sa propre étiquette (option d’impression à la maison).

La fonction principale du champ retailOnly consiste à restreindre l’accès aux étiquettes aux emplacements de vente au détail de Postes Canada et la fonction du champ createPublicKey consiste à fournir un accès aux étiquettes à la clientèle. Par conséquent, ces deux champs représentent des options mutuellement exclusives et ne peuvent pas être utilisés ensemble dans le cadre d’un même appel API. 

Vérification du rendu du code QR et de l’étiquette

Pour traiter la sortie PDF de façon programmatique et vous assurer qu’elle s’affiche correctement, nous vous conseillons de faire ce qui suit :

• Utilisez un lecteur PDF ou un moteur de rendu pour afficher le fichier PDF codé en Base64 généré.
• Vérifiez le code QR en le balayant avec un lecteur de code QR standard pour vous assurer que le lien vers l’URL publique fournie fonctionne correctement.
• Testez l’étiquette produite pour vous assurer que tous les éléments (adresses, codes à barres) sont visibles et lisibles. 

Si vous avez effectué les étapes de dépannage ci-dessus et que vous éprouvez toujours des problèmes, vous pouvez communiquer avec notre équipe de soutien aux développeurs.  

Liens connexes

• Aperçu de l’API de retours
• Solutions de retour
• Retours d’articles sans étiquette ni emballage
• Intégration des solutions de retour
• Caractéristiques à valeur ajoutée des retours
• Portail des développeurs de Postes Canada – API de suivi