Endpoints · Tarifs

Calculer un tarif

Obtenez le prix réel de votre compte avant de créer un bordereau.

POST/rates

Calcule un prix avec la logique tarifaire réelle de votre compte. Requiert le scope write (méthode POST).

bash

# Compte de reference de TOUS les exemples de cette page :
#   pricePerKg = 9 EUR (forfait jusqu'a 4 kg), minimumPrice = 7 EUR.
# Un compte sans pricePerKg (null) paierait 7 EUR le meme colis. Le tarif
# depend de VOTRE grille : appelez /rates, ne recopiez pas le chiffre.
curl -X POST "https://api.arelpro.com/pro/api/v1/rates" \
  -H "Authorization: Bearer sk_live_VOTRE_CLE" \
  -H "X-Client-Id: VOTRE_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{ "weight": 2.5 }'

Réponse :

json

{
  "success": true,
  "rate": {
    "price": 9,
    "currency": "EUR",
    "weightInKg": 2.5,
    "minimumPrice": 7,
    "pricePerKg": 9,
    "pricingModel": "professional_tiered",
    "scheduledDelivery": null
  }
}

Tout est sous la clé rate : il n'y a pas de champ price à la racine. Le poids vous revient sous le nom weightInKg, et non weight comme dans votre requête.

Compte de référence de ces exemples : pricePerKg: 9, minimumPrice: 7. Les prix affichés ici n'ont de sens que pour cette grille — un compte sans pricePerKg paierait 7 € le même colis de 2,5 kg. Si un autre document Arel montre un prix différent pour ce colis, c'est qu'il illustre un autre compte. Seul l'appel à /rates indique votre prix.

weight (ou parcelDetails.weight) est le seul champ requis : pas besoin d'adresse pour obtenir un tarif. pricingModel vaut scheduled_slot, professional_tiered ou professional_minimum, selon la grille de votre compte.

pricePerKg est un forfait, pas un prix au kilo

Malgré son nom, c'est un forfait qui couvre le colis jusqu'à 4 kg ; au-delà s'ajoutent 1,17 € par kilo supplémentaire. Ne le multipliez pas par le poids : à 2,5 kg avec pricePerKg: 9, le prix est 9 €, pas 22,50 €.

Si votre compte n'a pas de pricePerKg (valeur null), le modèle est professional_minimum et le prix vaut minimumPrice, quel que soit le poids.

Ne réimplémentez pas ce calcul. Il évolue avec votre grille commerciale ; POST /rates est la seule source de vérité, et c'est le même code qui facture à la création.

Un créneau programmé change de grille tarifaire

Dès que vous passez scheduledDate + timeSlot, votre forfait pricePerKg n'est plus utilisé. Le prix repart d'une grille au poids :

base = poids × 7 €, avec un plancher de 7 € ;
+ 3 € si le créneau commence avant 9h ou à 18h et après ;
+ 5 € si la date tombe un samedi ou un dimanche.

À 2,5 kg : 9 € en express (forfait), mais 17,50 € programmé en semaine à 14h — et 25,50 € un samedi à 19h. Le créneau n'est pas une option gratuite : sur un colis lourd, l'écart se creuse encore.

pricePerKg reste renvoyé dans la réponse en scheduled_slot : c'est le réglage de votre compte, pas le prix appliqué. Seul price fait foi. Ces surcoûts ne touchent que les envois programmés : un express créé un samedi ne paie pas les 5 €.

scheduledDelivery vaut null pour un envoi express. Si vous passez un créneau, il porte trois champs : date, timeSlot (le libellé normalisé) et slotId — l'id du créneau configuré sur votre compte, ou null si vous avez fourni un libellé libre du type 14h-16h.

Les deux champs ne peuvent pas être renseignés arbitrairement en même temps. Un créneau de votre compte n'est reconnu que par son id ou son libellé exact. Deux branches, deux résultats :

vous envoyez "14h-16h" (libellé libre) → timeSlot: "14h-16h", slotId: null ;
vous envoyez "s1" (un id de votre compte) → slotId: "s1", et timeSlot vous revient réécrit avec le libellé du créneau (par ex. "Matin") — pas la valeur que vous aviez envoyée.

Ne comparez donc jamais le timeSlot renvoyé à celui que vous avez envoyé pour vérifier le succès : sur un id, l'égalité est fausse alors que tout est correct.

Calculer un tarif

L'application Arel envoie vos biens.