API douanière DOM-TOM

Pourquoi une API douane pour les DOM-TOM ?

Calculer les taxes d'importation vers les Outre-mer est complexe : chaque territoire vote ses propres taux d'octroi de mer, produit par produit, la TVA varie de 0 % à 8,5 % selon la destination, et une marchandise venue de l'Union européenne ne paie pas les droits de douane d'un pays tiers. Vous envoyez le prix, le code HS, le territoire, l'origine de la marchandise et le profil de l'acheteur : l'API renvoie le détail des taxes.

Démarrage rapide

1. Créez un compte et souscrivez le plan Premium (accès API inclus)
2. Générez votre clé API depuis le tableau de bord
3. Envoyez vos requêtes depuis votre serveur, avec l'en-tête X-API-Key

curl -X POST https://tropicadouane.com/api/v1/public/calculate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: td_votre_cle_ici" \
  -d '{
      "product_price": 100,
      "shipping_cost": 15,
      "hs_code": "6109.10",
      "territory": "REU",
      "origin": "EU",
      "recipient_profile": "individual"
    }'

Réponse : 18 € de taxes (octroi de mer 5 €, OMR 3 €, TVA 10 €, pas de droit de douane pour une marchandise venue de l'UE), 133 € au total. Le même t-shirt expédié de Chine (origin NON_EU) à un particulier : forfait de 3 € par article au lieu du droit de douane (plus 2 € de frais de traitement de l'UE depuis le 1er novembre 2026) ; à un professionnel : droit de douane de 12 %.

Authentification

Chaque requête doit inclure votre clé API dans l'en-tête HTTP :

X-API-Key: td_XXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

• Les clés commencent par td_. La clé n'est montrée qu'à sa création ; ne la partagez jamais.
• Appelez l'API depuis votre serveur : les navigateurs sont refusés pour les autres domaines (CORS), pour que la clé ne soit jamais visible de vos visiteurs.
• Une clé révoquée depuis le tableau de bord est refusée aussitôt (401).

Champs du calcul

Corps JSON, montants en euros. Les trois champs de l'envoi (territory, origin, recipient_profile) sont obligatoires : ils changent fortement le montant, l'API ne les devine pas. Un champ inconnu (faute de frappe) est ignoré et signalé dans warnings. « lot : envoi » : champ donné une fois pour tout le lot ; « lot : ligne » : dans chaque ligne de « items ».

product_priceobligatoirelot : ligne

Prix d'un exemplaire, en euros (nombre, point décimal : 120.5).

hs_codeobligatoirelot : ligne

Code douanier (code HS / NC), en texte entre guillemets : 4 à 10 chiffres, avec ou sans points ("6109.10", "6109100010"). Un nombre JSON est refusé (6109.10 deviendrait 6109.1).

territoryobligatoirelot : envoi

Destination : REU, GLP, MTQ, GUF ou MYT (minuscules acceptées).

originobligatoirelot : envoi

EU : marchandise expédiée de métropole ou d'un pays de l'Union européenne (pas de droit de douane). NON_EU : expédiée d'ailleurs (Chine, États-Unis…).

recipient_profileobligatoirelot : envoi

individual (particulier : forfait de 3 € et franchises des petits colis), business (professionnel), gift (cadeau entre particuliers).

quantityfacultatiflot : ligne

Nombre d'exemplaires ou d'unités, 1 par défaut ; décimale possible (0.5 kg). Les montants rendus portent sur la ligne entière.

shipping_costfacultatiflot : envoi

Port jusqu'au territoire, en euros (0 par défaut). Dans un lot : port de tout l'envoi, réparti selon la valeur des lignes.

insurancefacultatiflot : envoi

Assurance, en euros (0 par défaut). Dans un lot : répartie comme le port.

pays_originefacultatiflot : envoi ou ligne

Hors UE : pays d'origine (2 lettres : CN, VN…). Sert aux préférences tarifaires et aux droits antidumping.

preuve_originefacultatiflot : envoi ou ligne

true si le vendeur fournit la preuve d'origine : la préférence tarifaire du pays est alors appliquée.

carrier_idfacultatiflot : envoi

Transporteur, pour ses frais de dédouanement : champ « id » de la liste GET https://tropicadouane.com/api/v1/carriers (sans clé).

weight_kgfacultatif

Calcul d'un article seulement : poids, pour les frais de certains transporteurs.

descriptionfacultatiflot : ligne

Lot seulement : libellé de la ligne, renvoyé tel quel (200 caractères au plus).

Principaux champs de la réponse (« calculation ») : valeur_en_douane (prix, port et assurance, arrondis à l'euro), octroi_mer, octroi_mer_regional, droits_douane (forfait de 3 € compris), tva, total_taxes (taxes perçues par la douane), carrier_fee (frais du transporteur), total_with_product (coût total, marchandise comprise). Les détails (franchises, préférence, exonérations, taux à préciser) sont dans les champs *_detail.

Territoires supportés

Gestion des erreurs

Toute erreur a la même forme : success vaut false, error est un texte lisible ; s'y ajoutent errors (détail par champ, saisie invalide) ou code (limites).

{
  "success": false,
  "error": "origin obligatoire : EU (marchandise expédiée de métropole ou de l'UE) ou NON_EU (hors UE)",
  "errors": [ { "field": "origin", "message": "origin obligatoire : EU (...) ou NON_EU (hors UE)" } ]
}

400

Saisie invalide : champ obligatoire absent ou valeur refusée (le message dit lequel), JSON mal formé, code HS ou territoire inconnu.

Lisez « error » ; « errors » donne le détail par champ.

401

Clé absente, au mauvais format, inconnue ou révoquée.

Vérifiez l'en-tête X-API-Key.

403

Formule sans accès à l'API, ou compte désactivé.

Vérifiez votre abonnement Premium.

404

Chemin inconnu (« Route non trouvée »).

Vérifiez l'adresse et la méthode (GET, POST).

429

code « DEBIT » : trop de requêtes dans la minute. code « QUOTA_MENSUEL » : quota du mois épuisé.

DEBIT : attendez quelques secondes. QUOTA_MENSUEL : attendez le 1er du mois ou écrivez-nous.

500

Erreur interne.

Réessayez ; si elle persiste, écrivez au support.

Questions fréquentes sur l'API

Les plans détaillés sont sur la page Tarifs. Pour tester le moteur de calcul sans clé API, utilisez le simulateur en ligne.