Tarification
Obtenir les tarifs – Module REST
Résumé
| Nom : | Obtenir les tarifs |
|---|---|
| Raison pour utiliser le service : | Pour obtenir une liste de services, de tarifs et de délais de transit pour un envoi |
| Données d'entrée : | Renseignements de base sur les adresses et les colis |
| Données de sortie : | Services, tarifs, délais de transit et date de livraison prévue |
| Exemple d'erreur : | Aucun service n'est approprié pour l'expédition du colis désigné. Il faut donc comparer les critères du colis aux spécifications du produit. |
| Demande de service précédente habituelle : | Aucune demande de service précédente directement liée |
| Prochaine demande de service habituelle : | |
| Historique des versions : | Notes de mise à jour |
Obtenir les tarifs – Résumé du service
Détails sur la demande
Structure de la demande pour obtenir des tarifs
Point final
POST https://XX/rs/ship/price |
|
|---|---|
| Remplacez... | Par... |
XX (développement) |
ct.soa-gw.canadapost.ca* |
XX (production) |
soa-gw.canadapost.ca |
*Si vous n'êtes pas un client commercial de Postes Canada titulaire d'une convention, mais que vous mettez en place une solution d'expédition par tierce partie destinée aux clients commerciaux, veuillez lire les renseignements importants sur la façon de mettre à l'essai les services d'expédition avec convention dans notre environnement « Bac à sable ».
En-têtes HTTP
| Variable des en-têtes HTTP | Valeur |
|---|---|
Accept |
application/vnd.cpc.ship.rate-v4+xml (Remarque : */* à la place de la valeur de l’en-tête affichera un message d’erreur) |
Content-Type |
application/vnd.cpc.ship.rate-v4+xml (Remarque : */* à la place de la valeur de l’en-tête affichera un message d’erreur) |
Authorization |
Basic {Encodage base64 du code d'usager:mot de passe} |
Accept-language |
en-CA ou fr-CA |
Corps du message
<?xml version="1.0" encoding="utf-8"?>
<mailing-scenario xmlns=”http://www.canadapost.ca/ws/ship/rate-v4”>
xxx
</mailing-scenario>
Éléments de la demande
La présente section décrit les éléments XML pour ce service. La structure hiérarchique exacte des données d'entrée XML est présentée dans un diagramme figurant sous ce tableau.
| Nom de l'élément | Type | Requis/Optionnel | Description | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
mailing-scenario |
Complexe |
Requis |
Structure XML générale pour les données d'entrée de la demande |
||||||||||||||||||||||||||||||||||||
customer-number |
Simple |
Requis sous condition |
Numéro de client du propriétaire du courrier (Expédié au nom de) (Format numérique – Jusqu'à 10 chiffres) Cet élément est exigé pour obtenir des tarifs réduits pour les clients commerciaux et les clients du programme Solutions pour petites entreprises. Il faut l'omettre pour obtenir les tarifs au comptoir (c.-à-d. tarifs des particuliers). |
||||||||||||||||||||||||||||||||||||
contract-id |
Simple |
Requis sous condition |
Cet élément est exigé pour obtenir des tarifs réduits pour les clients commerciaux lorsque le numéro de client n'est pas fourni. Il faut omettre le numéro d'identification de la convention pour les clients du programme Solutions pour petites entreprises ou les utilisateurs commerciaux généraux. (Format numérique – Jusqu'à 10 chiffres) |
||||||||||||||||||||||||||||||||||||
promo-code |
Simple |
Optionnel |
Si vous avez un code de réduction promotionnelle, saisissez-le ici. Le montant de la réduction sera affiché dans la réponse sous la structure <adjustment>. |
||||||||||||||||||||||||||||||||||||
quote-type |
Simple |
Optionnel |
Option « Commercial » ou « Counter »
L'option « Commercial » s'affiche par défaut si aucune option n'est sélectionnée. |
||||||||||||||||||||||||||||||||||||
expected-mailing-date |
Simple |
Optionnel |
Date d'expédition prévue pour le colis Cette date est utilisée pour calculer la date de livraison prévue. Cependant, toutes les propositions tarifaires sont fonction de la date actuelle du système. (Format de la date : AAAA-MM-JJ) |
||||||||||||||||||||||||||||||||||||
options |
Complexe |
Optionnel |
Structure contenant la liste d'options voulues pour l'envoi |
||||||||||||||||||||||||||||||||||||
option |
Complexe |
Requis |
Occurrence (1 à 20 fois) Comprend le code d'option et le qualificatif pour une option sélectionnée. |
||||||||||||||||||||||||||||||||||||
option-code |
Simple |
Requis |
(10 caractères alphanumériques) Comprend le code d'option propre à Postes Canada. Valeurs valides : SO – Signature |
||||||||||||||||||||||||||||||||||||
option-amount |
Simple |
Requis (selon le code d'option) |
Requis pour COV – Montant de l'assurance à acheter Cinq chiffres, suivis de deux décimales (p. ex. 99999.99) |
||||||||||||||||||||||||||||||||||||
parcel-characteristics |
Complexe |
Requis |
Détails liés au colis (p. ex. poids, dimensions et apparence) |
||||||||||||||||||||||||||||||||||||
weight |
Simple |
Requis |
Poids du colis en kilogrammes (99.999) Fait partie des parcel-characteristics. |
||||||||||||||||||||||||||||||||||||
dimensions |
Complexe |
Optionnel |
Détails liés aux dimensions du colis en centimètres. |
||||||||||||||||||||||||||||||||||||
length |
Simple |
Requis |
Dimension la plus longue (Trois chiffres, suivis d'une décimale [p. ex. format 999.9]) |
||||||||||||||||||||||||||||||||||||
width |
Simple |
Requis |
Deuxième plus longue dimension (Trois chiffres, suivis d'une décimale [p. ex. format 999.9]) |
||||||||||||||||||||||||||||||||||||
height |
Simple |
Requis |
Dimension la plus courte (Trois chiffres, suivis d'une décimale [p. ex. format 999.9]) |
||||||||||||||||||||||||||||||||||||
unpackaged |
Simple |
Optionnel |
vrai | faux
|
||||||||||||||||||||||||||||||||||||
mailing-tube |
Simple |
Optionnel |
vrai | faux
|
||||||||||||||||||||||||||||||||||||
oversized |
Simple |
Optionnel |
vrai | faux
|
||||||||||||||||||||||||||||||||||||
services |
Complexe |
Optionnel |
Précise les services pour lesquels il faut déterminer le tarif pour ce scénario d'expédition. |
||||||||||||||||||||||||||||||||||||
service-code |
simple |
required |
Occurrence (1 à 20 fois) Le tarif doit être déterminé pour un service précis. Si aucun service-code n'est inclus dans la demande, le tarif sera déterminé pour tous les services liés à l'envoi et à la destination, puis l'envoi sera retourné.
|
||||||||||||||||||||||||||||||||||||
origin-postal-code |
Simple |
Requis |
Code postal à partir duquel le colis sera envoyé Format ANANAN (seulement accepté avec majuscules) |
||||||||||||||||||||||||||||||||||||
destination |
Complexe |
Requis |
Définit la destination du colis. |
||||||||||||||||||||||||||||||||||||
domestic |
Complexe |
Choix |
Définit la destination au Canada. |
||||||||||||||||||||||||||||||||||||
postal-code |
Simple |
Requis |
Code postal de destination Format ANANAN (seulement accepté avec majuscules) |
||||||||||||||||||||||||||||||||||||
united-states |
Complexe |
Choix |
Définit la destination aux États-Unis. |
||||||||||||||||||||||||||||||||||||
zip-code |
Simple |
Requis |
Il est utilisé lorsque le code de pays est « US ». Le format est de cinq chiffres ou de cinq chiffres suivis de quatre autres chiffres (pour les codes ZIP prolongés). Exemple : 12345 ou 12345-6789 |
||||||||||||||||||||||||||||||||||||
international |
Complexe |
Choix |
Il s'agit de la destination internationale (destination autre que les États-Unis ou le Canada). Seule une destination (internationale, États-Unis ou régime intérieur) peut être précisée. |
||||||||||||||||||||||||||||||||||||
country-code |
Simple |
Requis |
Code de pays de destination – Code de pays standard à deux caractères (code de pays valide autre que CA ou US) |
||||||||||||||||||||||||||||||||||||
postal-code |
Simple |
Choix |
Le champ relatif au code postal peut être fourni si le client aimerait recevoir une garantie de date de livraison pour un pays membre du Kahala Post Group (KPG). |
Demande – Diagramme XML
Voici la structure hiérarchique des éléments XML devant être utilisée pour fournir les données d'entrées propres à l'expédition.
Détails de la réponse
Éléments de réponse
Le tableau suivant décrit les champs XML dans la réponse. Pour obtenir un aperçu détaillé de la hiérarchie de la réponse, voir le diagramme ci-dessous.
| Obtenir les tarifs - Éléments de réponse | ||
|---|---|---|
| Nom de l'élément | Type | Description |
price-quotes |
Complexe |
Une ou plusieurs propositions tarifaires sont fondées sur le nombre de services postaux disponibles ou sélectionnés pour l'envoi. |
price-quote |
Complexe |
Coûts et normes de livraison pour un service postal distinct |
service-code |
Simple |
Code du service postal faisant l'objet d'une proposition tarifaire |
service-link |
Simple |
Voir la section Points finaux fournis. |
service-name |
Simple |
Nom du service dans la langue de préférence |
price-details |
Complexe |
Analyse détaillée des coûts pour l'envoi s'il est expédié à l'aide de ce service |
base |
Simple |
(Format numérique : 99999.99) Coût de base de l'envoi avant les taxes |
taxes |
Complexe |
Contient des détails liés aux taxes facturées pour cet envoi s'il est envoyé à l'aide de ce service. (Ne contiendra pas les trois types de taxes à la fois.) |
gst |
Simple |
(Format numérique : 99999.99) Taxe sur les produits et services |
pst |
Simple |
Taxe de vente provinciale |
hst |
Simple |
(Format numérique : 99999.99) Taxe de vente harmonisée |
percent |
Attribut de la TVH, de la TVP ou de la TPS |
Format numérique : 999.99 (valeur de 1 à 100) Indique le pourcentage des taxes appliquées au montant de base. |
adjustments |
Complexe |
Structure contenant les détails liés aux rajustements tarifaires |
adjustment |
Complexe |
Structure contenant les détails liés à un rajustement tarifaire |
adjustment-code |
Simple |
Code désignant le rajustement AUTDISC – Réduction à l'automatisation |
adjustment-name |
Simple |
Nom du rajustement dans la langue de préférence |
adjustment-cost |
Simple |
(Format numérique : 9999.99) Montant du rajustement en dollars et en cents |
qualifier |
Complexe |
Contient le qualificatif du rajustement (le cas échéant). |
percent |
Simple |
Format numérique : 999.99 (valeur de 1 à 100) Si le rajustement est fonction de la valeur du pourcentage, le pourcentage en question s'affichera (p. ex. supplément pour carburant). |
due |
Simple |
(Format numérique : 99999.99) Coût total de l'envoi s'il est expédié à l'aide de ce service (y compris les taxes, les réductions, les suppléments et les options sélectionnés ou nécessaires) |
options |
Complexe |
Cette structure contient les options sélectionnées ainsi que les options gratuites et les caractéristiques de colis pour les tubes d'expédition, les articles surdimensionnés ou non emballés si elles ont été sélectionnées ou justifiées selon les dimensions. |
option |
Complexe |
Cette structure contient les détails liés à une seule option. |
option-code |
Simple |
(10 caractères alphanumériques) Code unique pour l'option Structure présentant les détails supplémentaires liés à l'option (le cas échéant) |
option-name |
Simple |
Nom de l'option dans la langue de préférence |
option-price |
Simple |
(Cinq chiffres, suivis de deux décimales [p. ex. format 99999.99]) Coût de cette option pour le colis en question |
qualifier |
Complexe |
(12 caractères alphanumériques) Contient des détails supplémentaires liés à l'option (le cas échéant). |
step-size |
Simple |
Indique la taille de la tranche aux fins de tarification par tranche supplémentaire (p. ex. montant de la couverture achetée dans une tranche, soit 100 $). |
step-cost |
Simple |
(Cinq chiffres, suivis de deux décimales [p. ex. format 99999.99]) Indique le coût lié à la taille d'une tranche (p. ex. 75 cents pour chaque tranche (100 $) de la couverture. |
included-amount |
Simple |
(Cinq chiffres, suivis de deux décimales [p. ex. format 99999.99]) Désigne la couverture offerte par le service de base (p. ex. la première tranche de 100 $ de la couverture est incluse). |
max-value |
Simple |
(Cinq chiffres, suivis de deux décimales [p. ex. format 99999.99]) Indique le montant maximal de l'option (p. ex. couverture maximale de 5 000 $). |
included |
Simple |
Indique que l'option est offerte gratuitement. |
percent |
Simple |
Format numérique : 999.99 (valeur de 1 à 100) Si l'option est fonction de la valeur du pourcentage, le pourcentage en question s'affichera. |
weight-details |
Complexe |
Il sera vide si les dimensions ne sont pas fournies ou si le poids réel du colis dépasse le poids volumétrique standard propre aux dimensions. |
cubed-weight |
Simple |
(Format numérique : 99.999) L'équivalent volumétrique du poids réel (EV) du paquet. L'EV n'est pas une unité de mesure ni une masse ou un volume. Il assure une tarification plus exacte d'un article, compte tenu de son poids et de l'espace qu'il occupe. |
service-standard |
Complexe |
Contient les détails liés à la livraison du colis si le service ayant fait l'objet d'une proposition tarifaire est sélectionné. |
am-delivery |
Simple |
vrai|faux Indique si la livraison le matin est définie dans le cadre de la norme de service pour le service en question. |
guaranteed-delivery |
Simple |
vrai|faux Indique si la date de livraison est garantie. |
expected-transit-time |
Simple |
(99 caractères numériques) Indique le nombre de jours entre le dépôt ou le ramassage et la première tentative de livraison. |
expected-delivery-date |
Simple |
(Format de la date : AAAA-MM-JJ) Date approximative de livraison en fonction de la date d'expédition prévue |
Réponse – Diagramme XML
Les diagrammes suivants montrent la structure de la réponse. Les propositions tarifaires ou les messages (réponse d'erreur) s'afficheront.
Réponses d'erreur possibles
Une demande bien structurée peut entraîner une erreur de validation d'une règle administrative concernant la validité des spécifications des colis, de l'origine, de la destination, du client ou de la convention sélectionnées. Dans ce cas, le code d'erreur HTTP sera « 400 » et le texte du message de diagnostic s'affichera dans la langue de préférence (anglais ou français).
| Code | Message |
|---|---|
1622 |
La date d'expédition prévue ne doit pas se trouver dans le passé. |
7050 |
L'option {0} nécessite l'option {1}; veuillez ajouter la condition préalable ou supprimer l'option. |
9111 |
Aucun service n'est approprié pour l'expédition du colis désigné. Il faut donc comparer les critères du colis aux spécifications du produit. |
9112 |
Le service {0} n'est pas disponible pour le pays précisé ou le client ou la convention. |
Pour obtenir de plus amples renseignements, veuillez consulter la section Structure de la réponse HTTP.
Exemples
Exemple de demande REST
<mailing-scenario xmlns="http://www.canadapost.ca/ws/ship/rate-v4">
<customer-number>1234567</customer-number>
<parcel-characteristics>
<weight>1</weight>
</parcel-characteristics>
<origin-postal-code>K2B8J6</origin-postal-code>
<destination>
<domestic>
<postal-code>J0E1X0</postal-code>
</domestic>
</destination>
</mailing-scenario>
Exemple de réponse XML
<price-quotes>
<price-quote>
<service-code>DOM.EP</service-code>
<service-link rel="service" href="https://ct.soa-gw.canadapost.ca/rs/ship/service/DOM.EP?country=CA" media-type="application/vnd.cpc.ship.rate-v4+xml"></service-link>
<service-name>Expedited Parcel</service-name>
<price-details>
<base>9.59</base>
<taxes>
<gst>0.00</gst>
<pst>0</pst>
<hst>0</hst>
</taxes>
<due>10.21</due>
<options>
<option>
<option-code>DC</option-code>
<option-name>Delivery confirmation</option-name>
<option-price>0</option-price>
</option>
</options>
<adjustments>
<adjustment>
<adjustment-code>AUTDISC</adjustment-code>
<adjustment-name>Automation discount</adjustment-name>
<adjustment-cost>-0.29</adjustment-cost>
<qualifier>
<percent>3.000</percent>
</qualifier>
</adjustment>
<adjustment>
<adjustment-code>FUELSC</adjustment-code>
<adjustment-name>Fuel surcharge</adjustment-name>
<adjustment-cost>0.91</adjustment-cost>
<qualifier>
<percent>9.75</percent>
</qualifier>
</adjustment>
</adjustments>
</price-details>
<weight-details></weight-details>
<service-standard>
<am-delivery>false</am-delivery>
<guaranteed-delivery>true</guaranteed-delivery>
<expected-transit-time>2</expected-transit-time>
<expected-delivery-date>2011-10-24</expected-delivery-date>
</service-standard>
</price-quote>
<price-quote>
<service-code>DOM.PC</service-code>
<service-link rel="service" href="https://ct.soa-gw.canadapost.ca/rs/ship/service/DOM.PC?country=CA" media-type="application/vnd.cpc.ship.rate-v4+xml"></service-link>
<service-name>Priority Courier</service-name>
<price-details>
<base>22.64</base>
<taxes>
<gst>0.00</gst>
<pst>0</pst>
<hst>0</hst>
</taxes>
<due>25.20</due>
<options>
<option>
<option-code>DC</option-code>
<option-name>Delivery confirmation</option-name>
<option-price>0</option-price>
</option>
</options>
<adjustments>
<adjustment>
<adjustment-code>AUTDISC</adjustment-code>
<adjustment-name>Automation discount</adjustment-name>
<adjustment-cost>-0.68</adjustment-cost>
<qualifier>
<percent>3.000</percent>
</qualifier>
</adjustment>
<adjustment>
<adjustment-code>FUELSC</adjustment-code>
<adjustment-name>Fuel surcharge</adjustment-name>
<adjustment-cost>3.24</adjustment-cost>
<qualifier>
<percent>14.75</percent>
</qualifier>
</adjustment>
</adjustments>
</price-details>
<weight-details></weight-details>
<service-standard>
<am-delivery>false</am-delivery>
<guaranteed-delivery>true</guaranteed-delivery>
<expected-transit-time>1</expected-transit-time>
<expected-delivery-date>2011-10-21</expected-delivery-date>
</service-standard>
</price-quote>
<price-quote>
<service-code>DOM.RP</service-code>
<service-link rel="service" href="https://ct.soa-gw.canadapost.ca/rs/ship/service/DOM.RP?country=CA" media-type="application/vnd.cpc.ship.rate-v4+xml"></service-link>
<service-name>Regular Parcel</service-name>
<price-details>
<base>9.59</base>
<taxes>
<gst>0.00</gst>
<pst>0</pst>
<hst>0</hst>
</taxes>
<due>10.21</due>
<options>
<option>
<option-code>DC</option-code>
<option-name>Delivery confirmation</option-name>
<option-price>0</option-price>
<qualifier>
<included>true</included>
</qualifier>
</option>
</options>
<adjustments>
<adjustment>
<adjustment-code>AUTDISC</adjustment-code>
<adjustment-name>Automation discount</adjustment-name>
<adjustment-cost>-0.29</adjustment-cost>
<qualifier>
<percent>3.000</percent>
</qualifier>
</adjustment>
<adjustment>
<adjustment-code>FUELSC</adjustment-code>
<adjustment-name>Fuel surcharge</adjustment-name>
<adjustment-cost>0.91</adjustment-cost>
<qualifier>
<percent>9.75</percent>
</qualifier>
</adjustment>
</adjustments>
</price-details>
<weight-details></weight-details>
<service-standard>
<am-delivery>false</am-delivery>
<guaranteed-delivery>false</guaranteed-delivery>
<expected-transit-time>4</expected-transit-time>
<expected-delivery-date>2011-10-26</expected-delivery-date>
</service-standard>
</price-quote>
<price-quote>
<service-code>DOM.XP</service-code>
<service-link rel="service" href="https://ct.soa-gw.canadapost.ca/rs/ship/service/DOM.XP?country=CA" media-type="application/vnd.cpc.ship.rate-v4+xml"></service-link>
<service-name>Xpresspost</service-name>
<price-details>
<base>12.26</base>
<taxes>
<gst>0.00</gst>
<pst>0</pst>
<hst>0</hst>
</taxes>
<due>13.64</due>
<options>
<option>
<option-code>DC</option-code>
<option-name>Delivery confirmation</option-name>
<option-price>0</option-price>
</option>
</options>
<adjustments>
<adjustment>
<adjustment-code>AUTDISC</adjustment-code>
<adjustment-name>Automation discount</adjustment-name>
<adjustment-cost>-0.37</adjustment-cost>
<qualifier>
<percent>3.000</percent>
</qualifier>
</adjustment>
<adjustment>
<adjustment-code>FUELSC</adjustment-code>
<adjustment-name>Fuel surcharge</adjustment-name>
<adjustment-cost>1.75</adjustment-cost>
<qualifier>
<percent>14.75</percent>
</qualifier>
</adjustment>
</adjustments>
</price-details>
<weight-details></weight-details>
<service-standard>
<am-delivery>false</am-delivery>
<guaranteed-delivery>true</guaranteed-delivery>
<expected-transit-time>2</expected-transit-time>
<expected-delivery-date>2011-10-24</expected-delivery-date>
</service-standard>
</price-quote>
</price-quotes>
