API v1
Documentation de l’API
Intégrez le calcul des frais d’importation à La Réunion dans votre boutique, votre marketplace ou votre outil logistique.
Introduction
L’API est une API REST qui reçoit et renvoie du JSON en UTF-8, uniquement en HTTPS. Elle accepte une liste de produits et identifie le code douanier de chaque produit dans le référentiel officiel publié, puis calcule l’octroi de mer, l’octroi de mer régional, la TVA et, pour les envois hors Union européenne, les droits de douane et frais européens sur les petits colis.
URL de basehttps://api.fraisdouane.re/1.0
La description complète au format OpenAPI 3.1 est disponible sur /openapi.json : importez-la dans Postman, Insomnia ou un générateur de client.
Les montants renvoyés sont des estimations à titre indicatif ; ils ne remplacent pas la liquidation des droits par les services douaniers.
Authentification
Chaque requête s’authentifie avec une clé API transmise dans l’en-tête Authorization. Créez vos clés dans l’onglet Clés API de votre espace.
Authorization: Bearer fd_live_3kT9xQ2mV7pL4wZ8cN1bR6yH5jF0sD2afd_live_…: clé live, calculs réels, décomptés de votre offre (abonnement actif requis).fd_test_…: clé sandbox, taux fictifs, gratuite, illimitée et hors quota.
La clé n’est affichée qu’une fois, à sa création. Conservez-la côté serveur (variable d’environnement) : l’API refuse les appels depuis un navigateur (CORS) pour qu’elle ne soit jamais exposée dans une page web. En cas de fuite, révoquez-la immédiatement.
Démarrage rapide
Avec une clé sandbox, ce premier appel ne consomme aucune requête de votre offre :
curl https://api.fraisdouane.re/1.0/calculations \
-H "Authorization: Bearer fd_test_VOTRE_CLE" \
-H "Content-Type: application/json" \
-d '{ "items": [ { "product": "Casque audio Bluetooth", "price": 129.90, "reference": "casque-1" }, { "product": "Câble USB", "price": 20, "reference": "cable-1" } ], "shipping": 12, "origin": "FR", "reference": "commande-1042" }'Créer un calcul
POSThttps://api.fraisdouane.re/1.0/calculations
Envoyez les produits d’un même colis dans items. Chaque produit est classé séparément ; les taxes et le coût total sont renvoyés par ligne et pour le colis entier. La franchise et les seuils des frais européens sont évalués sur la somme des prix HT ; les catégories douanières identiques ne sont comptées qu’une fois pour les frais européens.
Corps de la requête
| Champ | Type | Défaut | Description |
|---|---|---|---|
items | array | requis | De 1 à 50 lignes de produits d’un même colis. Chaque ligne contient product et price ; vat_rate et reference sont facultatifs. Le format historique product + price à la racine reste accepté. |
items[].product | string | requis | Nom du produit, 2 à 150 caractères. Précisez la matière, l’usage, la marque ou le modèle pour aider la classification. |
items[].price | number | requis | Montant HT total de la ligne, quantités déjà comprises, en euros. Strictement positif après arrondi au centime, 1 000 000 € maximum par ligne et pour la somme des lignes. |
items[].vat_rate | number | hérité | Taux propre au produit : 0, 0.021 ou 0.085. Par défaut : vat_rate du colis. |
items[].reference | string | — | Identifiant de la ligne (SKU, etc.), 100 caractères maximum, renvoyé avec son résultat. |
shipping | number | 0 | Transport total du colis en euros, 1 000 000 € maximum. Fourni une seule fois, réparti au prorata des prix HT avec conservation des centimes. |
origin | string | "FR" | Pays d’expédition, code ISO à 2 lettres. Un pays hors Union européenne déclenche le calcul des frais européens sur petits colis et des droits de douane. |
currency | string | "EUR" | Seul l’euro est accepté. |
vat_rate | number | 0.085 | Taux de TVA par défaut du colis : 0, 0.021 ou 0.085. Chaque ligne peut le remplacer. |
transaction_type | string | "b2c" | Hors UE : b2c, b2b, c2c ou unknown. |
vat_regime | string | "standard" | Hors UE : standard, simplified ou ioss. |
fees_included_in_price | boolean | — | Hors UE : le vendeur inclut déjà les frais européens dans son prix. |
goods_in_free_circulation | boolean | — | Hors UE : marchandise déjà dédouanée dans l’Union. |
reference_date | string | aujourd’hui | Date d’importation au format AAAA-MM-JJ (règles en vigueur à cette date). |
reference | string | — | Votre identifiant (commande, panier…), 100 caractères maximum, renvoyé tel quel. |
Tout champ non documenté est refusé (invalid_request).
Le format historique reste accepté pour un seul produit : { "product": "Casque audio", "price": 129.9, "shipping": 12 }. Choisissez un seul format par requête : items ne se combine pas avec product ou price à la racine. Dans une liste, price est le total HT de la ligne : pour trois câbles à 10 €, envoyez price: 30.
Si une ligne est invalide ou impossible à classer, tout le calcul est refusé, sans résultat partiel ni facturation. error.param indique la ligne concernée, par exemple items.1.price.
Réponse 200
Extrait d’une réponse sandbox à deux produits (les champs lines, warnings et assumptions sont abrégés ou omis ici pour la lisibilité) :
{
"id": "calc_test_exemple",
"object": "calculation",
"livemode": false,
"created_at": "2026-11-18T09:12:44.512Z",
"reference": "commande-1042",
"input": {
"items": [
{ "product": "Casque audio Bluetooth", "price": 129.9, "reference": "casque-1" },
{ "product": "Câble USB", "price": 20, "reference": "cable-1" }
],
"shipping": 12,
"origin": "FR",
"currency": "EUR",
"vat_rate": 0.085
},
"classification": null,
"currency": "EUR",
"taxes": {
"customs_duty": 0,
"eu_flat_customs_duty": 0,
"eu_handling_fee": 0,
"octroi_de_mer": 11.33,
"octroi_de_mer_regional": 4.05,
"vat": 13.77,
"total": 29.15
},
"total_cost": 191.05,
"estimate_status": "complete",
"items": [
{
"index": 0,
"reference": "casque-1",
"input": { "product": "Casque audio Bluetooth", "price": 129.9, "shipping": 10.4, "origin": "FR", "currency": "EUR", "vat_rate": 0.085 },
"classification": { "code": "0000.00.00", "label": "Classification fictive (clé de test) : aucun tarif réel n’est recherché." },
"taxes": { "customs_duty": 0, "eu_flat_customs_duty": 0, "eu_handling_fee": 0, "octroi_de_mer": 9.82, "octroi_de_mer_regional": 3.51, "vat": 11.93, "total": 25.26 },
"total_cost": 165.56
},
{
"index": 1,
"reference": "cable-1",
"input": { "product": "Câble USB", "price": 20, "shipping": 1.6, "origin": "FR", "currency": "EUR", "vat_rate": 0.085 },
"classification": { "code": "0000.00.00", "label": "Classification fictive (clé de test) : aucun tarif réel n’est recherché." },
"taxes": { "customs_duty": 0, "eu_flat_customs_duty": 0, "eu_handling_fee": 0, "octroi_de_mer": 1.51, "octroi_de_mer_regional": 0.54, "vat": 1.84, "total": 3.89 },
"total_cost": 25.49
}
],
"warnings": [],
"assumptions": ["…"],
"tariff_version": "test"
}id- Identifiant du calcul, à conserver pour le retrouver avec GET /calculations/{id}.
livemode- true pour une clé live, false pour une clé sandbox.
items- Résultats par produit, dans l’ordre de la requête, même pour une liste d’un seul produit. Chaque résultat contient index (à partir de 0), reference, input, classification, taxes, total_cost, estimate_status, lines, warnings, assumptions et tariff_version.
items[].classification- Code douanier et libellé retenus pour ce produit. La classification à la racine vaut null avec une liste ; le format historique conserve sa classification à la racine.
items[].input.shipping- Part du transport total attribuée au produit. input.price contient le montant HT total de la ligne, arrondi au centime.
taxes.customs_duty- Droits de douane (envois hors UE).
taxes.eu_flat_customs_duty / eu_handling_fee- Droit forfaitaire et frais de traitement européens sur les petits colis (hors UE).
taxes.octroi_de_mer / octroi_de_mer_regional- Octroi de mer externe et régional, calculés sur prix + transport.
taxes.vat- TVA à La Réunion (l’octroi de mer est exclu de sa base).
taxes.total- Total des taxes à payer à l’arrivée.
total_cost- Coût de revient : prix + transport + taxes.
estimate_status- complete, ou conditional quand une partie dépend d’informations non fournies (voir warnings).
lines- Détail ligne par ligne, prêt à afficher. rate est un pourcentage, null quand il ne s’applique pas.
warnings / assumptions- Avertissements et hypothèses de calcul, à afficher avec le résultat.
La classification s’appuie sur un modèle de langage et traite au plus deux produits simultanément. Le délai augmente avec le nombre de descriptions différentes : prévoyez au moins 60 secondes pour un produit et augmentez ce délai pour une liste (par exemple 300 secondes).
Récupérer un calcul
GEThttps://api.fraisdouane.re/1.0/calculations/{id}
Renvoie à l’identique un calcul effectué avec une clé live de votre compte. Gratuit et hors quota. Les calculs effectués avec une clé sandbox ne sont pas conservés.
Consommation
GEThttps://api.fraisdouane.re/1.0/usage
Offre, période de facturation en cours et calculs consommés. Gratuit et hors quota.
{
"object": "usage",
"livemode": true,
"plan": { "id": "pro", "name": "Pro" },
"subscription_status": "active",
"period": { "start": "2026-11-05T10:00:00.000Z", "end": "2026-12-05T10:00:00.000Z" },
"calculations": {
"used": 5210, "limit": 5000, "remaining": 0, "lifetime": false,
"overage": 210, "overage_unit_price": 0.02
},
"rate_limit_per_minute": 120
}Erreurs
Les erreurs ont toujours la même forme. Le request_id, aussi présent dans l’en-tête X-Request-Id de chaque réponse, permet à notre support de retrouver l’appel.
{
"error": {
"code": "invalid_request",
"message": "price doit être positif.",
"param": "items.1.price"
},
"request_id": "req_8Hk2xWm4pQ7rT1vZ9cB3nD6f"
}| HTTP | code | Signification |
|---|---|---|
| 400 | invalid_request | Paramètre manquant ou invalide. param indique le champ en cause. |
| 400 | invalid_json | Le corps n’est pas un JSON valide. |
| 401 | unauthorized | En-tête Authorization absent ou mal formé. |
| 401 | invalid_api_key | Clé inconnue ou révoquée. |
| 402 | subscription_required | Clé live sans abonnement actif. |
| 403 | account_suspended | Compte suspendu : contactez-nous. |
| 404 | not_found | Route ou calcul introuvable. |
| 422 | calculation_failed | Produit impossible à classer ou nécessitant une vérification humaine. Le message explique quoi préciser. Non facturé. |
| 429 | rate_limited | Trop de requêtes par minute. Respectez Retry-After. |
| 429 | quota_exceeded | Requêtes de l’offre Test épuisées (les offres payantes facturent le dépassement). |
| 503 | service_unavailable | Indisponibilité temporaire. Réessayez avec un délai croissant. |
Offres et quotas
Chaque offre inclut un nombre de requêtes. Seuls les calculs réussis (200) avec une clé live sont décomptés ; les erreurs, /usage et GET /calculations/{id} ne le sont pas.
Un appel contenant plusieurs produits consomme une seule requête, quel que soit le nombre de lignes (50 maximum).
- Test : 50 requêtes au total, puis les appels sont refusés (
429 quota_exceeded). - Starter, Pro, Business : un quota mensuel, puis chaque requête supplémentaire est facturée au tarif de l’offre sur la facture suivante. Les appels ne sont jamais coupés ; l’en-tête
X-Quota-Overage: truesignale une requête facturée en supplément.
Les en-têtes X-Quota-Limit, X-Quota-Remaining et X-Quota-Reset indiquent votre solde ;GET /usage donne le détail. Le quota mensuel repart à zéro à chaque renouvellement.
Limites de débit
Un nombre de requêtes par minute selon votre offre (30 pour les clés sandbox). Les en-têtes RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset accompagnent chaque réponse ; au-delà, l’API répond 429 rate_limited avec Retry-After.
Clés sandbox
Les clés fd_test_ valident les paramètres exactement comme en production et renvoient une réponse de même forme, avec un code douanier fictif 0000.00.00 et des taux fixes (octroi de mer 7 %, régional 2,5 %, droits de douane hors UE 4 %). Aucune recherche de tarif n’est effectuée et rien n’est décompté : idéal pour développer votre intégration et vos tests automatisés.
Bonnes pratiques
- Appelez l’API depuis votre serveur et mettez en cache le calcul avec l’ensemble des lignes et paramètres du colis (prix, transport, origine, TVA et date).
- Sur
429et503, réessayez après le délai indiqué (Retry-After) puis avec un délai croissant. Ne réessayez pas une erreur4xxsans corriger la requête. - Affichez les
warningset précisez qu’il s’agit d’une estimation. - Utilisez
referencepour relier un calcul à votre commande dans vos journaux.
Une question ? Écrivez à contact@fraisdouane.re en indiquant le request_id concerné.