Aller au contenu
FraisDouane /api
Documentation
Se connecter← Retour à fraisdouane.re
FraisDouane /api

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_3kT9xQ2mV7pL4wZ8cN1bR6yH5jF0sD2a
  • fd_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

ChampTypeDéfautDescription
itemsarrayrequisDe 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[].productstringrequisNom du produit, 2 à 150 caractères. Précisez la matière, l’usage, la marque ou le modèle pour aider la classification.
items[].pricenumberrequisMontant 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_ratenumberhéritéTaux propre au produit : 0, 0.021 ou 0.085. Par défaut : vat_rate du colis.
items[].referencestring—Identifiant de la ligne (SKU, etc.), 100 caractères maximum, renvoyé avec son résultat.
shippingnumber0Transport total du colis en euros, 1 000 000 € maximum. Fourni une seule fois, réparti au prorata des prix HT avec conservation des centimes.
originstring"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.
currencystring"EUR"Seul l’euro est accepté.
vat_ratenumber0.085Taux de TVA par défaut du colis : 0, 0.021 ou 0.085. Chaque ligne peut le remplacer.
transaction_typestring"b2c"Hors UE : b2c, b2b, c2c ou unknown.
vat_regimestring"standard"Hors UE : standard, simplified ou ioss.
fees_included_in_priceboolean—Hors UE : le vendeur inclut déjà les frais européens dans son prix.
goods_in_free_circulationboolean—Hors UE : marchandise déjà dédouanée dans l’Union.
reference_datestringaujourd’huiDate d’importation au format AAAA-MM-JJ (règles en vigueur à cette date).
referencestring—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"
}
HTTPcodeSignification
400invalid_requestParamètre manquant ou invalide. param indique le champ en cause.
400invalid_jsonLe corps n’est pas un JSON valide.
401unauthorizedEn-tête Authorization absent ou mal formé.
401invalid_api_keyClé inconnue ou révoquée.
402subscription_requiredClé live sans abonnement actif.
403account_suspendedCompte suspendu : contactez-nous.
404not_foundRoute ou calcul introuvable.
422calculation_failedProduit impossible à classer ou nécessitant une vérification humaine. Le message explique quoi préciser. Non facturé.
429rate_limitedTrop de requêtes par minute. Respectez Retry-After.
429quota_exceededRequêtes de l’offre Test épuisées (les offres payantes facturent le dépassement).
503service_unavailableIndisponibilité 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: true signale 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 429 et 503, réessayez après le délai indiqué (Retry-After) puis avec un délai croissant. Ne réessayez pas une erreur 4xx sans corriger la requête.
  • Affichez les warnings et précisez qu’il s’agit d’une estimation.
  • Utilisez reference pour relier un calcul à votre commande dans vos journaux.

Une question ? Écrivez à contact@fraisdouane.re en indiquant le request_id concerné.

Sur cette page

  • Introduction
  • Authentification
  • Démarrage rapide
  • Créer un calcul
  • Récupérer un calcul
  • Consommation
  • Erreurs
  • Limites de débit
  • Offres et quotas
  • Clés sandbox
  • Bonnes pratiques