API octroi de mer : calcul des taxes DOM en JSON

Démarrage rapide

URL de base : https://octroimer.fr/api
Requêtes et réponses en JSON (Content-Type: application/json), encodées en UTF-8.
Montants en euros, taux en pourcentage (8.5 signifie 8,5 %).
Aucune clé d'API n'est nécessaire.

Avec curl

curl -X POST https://octroimer.fr/api/simulations \
  -H "Content-Type: application/json" \
  -d '{"territoire":"reunion","provenance":"pays_tiers","articles":[{"categorie":"vetements","description":"T-shirt","valeur":15,"quantite":4},{"categorie":"chaussures","description":"Baskets","valeur":60}],"transport":18,"transporteur":"fedex"}'

En JavaScript

const response = await fetch('https://octroimer.fr/api/simulations', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"territoire":"reunion","provenance":"pays_tiers","articles":[{"categorie":"vetements","description":"T-shirt","valeur":15,"quantite":4},{"categorie":"chaussures","description":"Baskets","valeur":60}],"transport":18,"transporteur":"fedex"}),
});
const simulation = await response.json();
console.log(simulation.totaux.a_payer); // 57.56

Les appels depuis le navigateur ne fonctionnent que depuis ce site : le partage entre domaines (CORS) n'est pas activé. Depuis un autre site, appelez l'API depuis votre serveur.

En PHP, depuis votre serveur

<?php

$body = [
    'territoire' => 'reunion',
    'provenance' => 'pays_tiers',
    'articles' => [
        [
            'categorie' => 'vetements',
            'description' => 'T-shirt',
            'valeur' => 15,
            'quantite' => 4,
        ],
        [
            'categorie' => 'chaussures',
            'description' => 'Baskets',
            'valeur' => 60,
        ],
    ],
    'transport' => 18,
    'transporteur' => 'fedex',
];

$ch = curl_init('https://octroimer.fr/api/simulations');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($body, JSON_THROW_ON_ERROR),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
]);
$json = curl_exec($ch) ?: throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$simulation = json_decode($json, true, flags: JSON_THROW_ON_ERROR);

if (200 === $status) {
    echo $simulation['totaux']['a_payer']; // 57.56
} else {
    echo $simulation['detail']; // pour une 422, détail par champ dans $simulation['violations']
}

Seule l'extension curl de PHP est nécessaire. Les visiteurs de votre site passent alors tous par l'adresse IP de votre serveur et se partagent sa limite d'appels : gardez les catalogues en cache et, en cas de 429, attendez le délai indiqué par Retry-After.

Endpoints

Méthode	Chemin	Rôle
POST	`/api/simulations`	Calcule les taxes et frais d'un envoi
GET	`/api`	Description de l'API et exemple de requête
GET	`/api/territoires`	Territoires, régime fiscal (octroi de mer ou taxes propres de la Polynésie française et de la Nouvelle-Calédonie), TVA, seuils, fiabilité et source des taux
GET	`/api/territoires/{code}`	Un territoire, par son code ou son code département (`/api/territoires/974`)
GET	`/api/categories`	Catégories, droits de douane, octroi de mer par département et taxes locales des collectivités d'outre-mer
GET	`/api/categories/{code}`	Une catégorie
GET	`/api/transporteurs`	Frais de traitement, avec le montant par territoire

POST /api/simulations

Calcule ce que coûte un envoi à l'arrivée. Les champs portent les mêmes noms que les paramètres d'URL du simulateur : un lien de simulation se traduit directement en appel d'API.

Champ	Type	Défaut	Description
`territoire`	code	obligatoire	`guadeloupe`, `martinique`, `guyane`, `reunion`, `mayotte`, `polynesie`, `nouvelle_caledonie`, `saint_pierre_miquelon`, `saint_barthelemy`, `saint_martin`, `wallis_futuna`, ou le code département : `971`, `972`, `973`, `974`, `976`, `987`, `988`, `975`, `977`, `978`, `986`
`articles`	liste	obligatoire	Les produits du colis, de 1 à 20 articles (voir ci-dessous)
`acheteur`	texte	`particulier`	`particulier` ou `professionnel` (la TVA à l'importation est autoliquidée et déduite, elle ne coûte rien)
`provenance`	texte	`metropole`	`metropole`, `ue` ou `pays_tiers`
`envoi`	texte	`achat`	`achat` ou `cadeau` (entre particuliers, refusé avec `acheteur: professionnel`)
`devise`	code	`EUR`	Devise des prix des articles, du transport et de l'assurance : `EUR`, `USD`, `GBP`, `CNY`, `CHF`, `CAD`, `AUD`, `JPY`, `HKD`, `BRL`, `ZAR`, `XPF`. Convertis au taux de référence du jour de la BCE, ou à la parité fixe pour le franc Pacifique `XPF` (voir `conversion` dans la réponse). `frais` reste en euros.
`transport`	nombre	`0`	Frais de port, dans la `devise`
`assurance`	nombre	`0`	Assurance, dans la `devise`
`ttc`	booléen	`false`	Les prix incluent la TVA métropolitaine, retirée au taux de chaque catégorie (provenance `metropole` uniquement)
`transporteur`	code	aucun	`colissimo`, `chronopost`, `ups`, `dhl`, `fedex`, `ocx`. Ses frais s'ajoutent quand des taxes sont dues.
`paiement_en_ligne`	booléen	`false`	Taxes payées en ligne avant la livraison (frais réduits chez certains transporteurs)
`frais`	nombre	aucun	Frais de traitement connus, en euros : remplacent ceux du transporteur

Chaque élément de `articles`

Champ	Type	Défaut	Description
`categorie`	code	obligatoire	`telephonie`, `informatique`, `televiseurs`, `consoles`, `audio`, `accessoires_telephone`, `electromenager`, `vetements`, `chaussures`, `maroquinerie`, `cosmetiques`, `parfums`, `montres`, `bijoux`, `bagagerie`, `alimentation`, `vins`, `spiritueux`, `pieces_auto`, `pneus`, `voiture_thermique`, `voiture_electrique`, `meubles`, `linge_maison`, `luminaires`, `jouets`, `sport`, `trottinettes_velos`, `livres`, `medicaments`, `materiaux`, `outillage`
`valeur`	nombre	obligatoire	Prix unitaire, dans la `devise` (strictement positif)
`quantite`	entier	`1`	Nombre d'exemplaires (1 à 10 000)
`description`	texte	aucune	Libellé libre, repris dans la réponse (80 caractères maximum)
`taux_om`	nombre	catalogue	Taux d'octroi de mer exact de cet article, en % (0 à 200) ; ignoré en Polynésie française et en Nouvelle-Calédonie
`taux_omr`	nombre	catalogue	Taux d'octroi de mer régional exact, en % (0 à 10)
`taux_dd`	nombre	catalogue	Taux de droits de douane exact, en % (0 à 100), du tarif européen ou de celui de la collectivité

Chaque article est taxé aux taux de sa catégorie. Le port et l'assurance sont répartis entre les articles au prorata de leur valeur. Les seuils (cadeaux, petits colis de 150 €) portent sur la valeur totale du colis, et le forfait de droits de douane est compté une fois par catégorie.

Pour un seul article, les champs categorie, valeur et taux_* peuvent aussi être placés directement à la racine, à la place de articles (mais pas les deux à la fois).

Exemple de requête

Quatre t-shirts et une paire de baskets (120 € au total) achetés hors de l'Union européenne, livrés à La Réunion par FedEx :

Requête

{
    "territoire": "reunion",
    "provenance": "pays_tiers",
    "articles": [
        {
            "categorie": "vetements",
            "description": "T-shirt",
            "valeur": 15,
            "quantite": 4
        },
        {
            "categorie": "chaussures",
            "description": "Baskets",
            "valeur": 60
        }
    ],
    "transport": 18,
    "transporteur": "fedex"
}

Réponse d'une simulation

Réponse 200 à la requête ci-dessus, calculée à l'instant avec les taux du 08/11/2026 :

Réponse

{
    "territoire": {
        "code": "reunion",
        "nom": "La Réunion",
        "regime": "octroi_de_mer",
        "devise": "EUR",
        "tva_applicable": true,
        "fiabilite_taux": "moyenne"
    },
    "acheteur": "particulier",
    "provenance": "pays_tiers",
    "envoi": "achat",
    "montants": {
        "prix_saisi": 120.0,
        "tva_metropole_deduite": 0.0,
        "marchandise": 120.0,
        "transport": 18.0,
        "assurance": 0.0,
        "valeur_en_douane": 138.0
    },
    "taxes": [
        {
            "code": "droits_douane",
            "libelle": "Droits de douane (forfait petit colis)",
            "base": 138.0,
            "taux": null,
            "forfait": true,
            "montant": 6.0,
            "deductible": 0.0,
            "note": "Achat en ligne ≤ 150 € : droit forfaitaire de 3 € par type d'article (règlement UE 2026/382), au lieu du tarif douanier."
        },
        {
            "code": "frais_traitement_ue",
            "libelle": "Frais de traitement UE",
            "base": 138.0,
            "taux": null,
            "forfait": true,
            "montant": 4.0,
            "deductible": 0.0,
            "note": "Achat à distance hors UE : 2 € par type d'article, quelle que soit la valeur (règlement délégué UE 2026/2152)."
        },
        {
            "code": "octroi_de_mer",
            "libelle": "Octroi de mer",
            "base": 138.0,
            "taux": 4.0,
            "forfait": false,
            "montant": 5.52,
            "deductible": 0.0,
            "note": null
        },
        {
            "code": "octroi_de_mer_regional",
            "libelle": "Octroi de mer régional",
            "base": 138.0,
            "taux": 2.5,
            "forfait": false,
            "montant": 3.46,
            "deductible": 0.0,
            "note": null
        },
        {
            "code": "tva",
            "libelle": "TVA (taux normal)",
            "base": 148.0,
            "taux": 8.5,
            "forfait": false,
            "montant": 12.58,
            "deductible": 0.0,
            "note": null
        }
    ],
    "articles": [
        {
            "categorie": {
                "code": "vetements",
                "libelle": "Vêtements"
            },
            "description": "T-shirt",
            "quantite": 4,
            "prix_unitaire": 15.0,
            "valeur": 60.0,
            "marchandise": 60.0,
            "transport": 9.0,
            "assurance": 0.0,
            "valeur_en_douane": 69.0,
            "taxes": [
                {
                    "code": "droits_douane",
                    "libelle": "Droits de douane (forfait petit colis)",
                    "base": 69.0,
                    "taux": null,
                    "forfait": true,
                    "montant": 3.0,
                    "deductible": 0.0,
                    "note": "Achat en ligne ≤ 150 € : droit forfaitaire de 3 € par type d'article (règlement UE 2026/382), au lieu du tarif douanier."
                },
                {
                    "code": "frais_traitement_ue",
                    "libelle": "Frais de traitement UE",
                    "base": 69.0,
                    "taux": null,
                    "forfait": true,
                    "montant": 2.0,
                    "deductible": 0.0,
                    "note": "Achat à distance hors UE : 2 € par type d'article, quelle que soit la valeur (règlement délégué UE 2026/2152)."
                },
                {
                    "code": "octroi_de_mer",
                    "libelle": "Octroi de mer",
                    "base": 69.0,
                    "taux": 4.0,
                    "forfait": false,
                    "montant": 2.76,
                    "deductible": 0.0,
                    "note": null
                },
                {
                    "code": "octroi_de_mer_regional",
                    "libelle": "Octroi de mer régional",
                    "base": 69.0,
                    "taux": 2.5,
                    "forfait": false,
                    "montant": 1.73,
                    "deductible": 0.0,
                    "note": null
                },
                {
                    "code": "tva",
                    "libelle": "TVA (taux normal)",
                    "base": 74.0,
                    "taux": 8.5,
                    "forfait": false,
                    "montant": 6.29,
                    "deductible": 0.0,
                    "note": null
                }
            ],
            "total_taxes": 15.78,
            "taux_personnalises": false
        },
        {
            "categorie": {
                "code": "chaussures",
                "libelle": "Chaussures"
            },
            "description": "Baskets",
            "quantite": 1,
            "prix_unitaire": 60.0,
            "valeur": 60.0,
            "marchandise": 60.0,
            "transport": 9.0,
            "assurance": 0.0,
            "valeur_en_douane": 69.0,
            "taxes": [
                {
                    "code": "droits_douane",
                    "libelle": "Droits de douane (forfait petit colis)",
                    "base": 69.0,
                    "taux": null,
                    "forfait": true,
                    "montant": 3.0,
                    "deductible": 0.0,
                    "note": "Achat en ligne ≤ 150 € : droit forfaitaire de 3 € par type d'article (règlement UE 2026/382), au lieu du tarif douanier."
                },
                {
                    "code": "frais_traitement_ue",
                    "libelle": "Frais de traitement UE",
                    "base": 69.0,
                    "taux": null,
                    "forfait": true,
                    "montant": 2.0,
                    "deductible": 0.0,
                    "note": "Achat à distance hors UE : 2 € par type d'article, quelle que soit la valeur (règlement délégué UE 2026/2152)."
                },
                {
                    "code": "octroi_de_mer",
                    "libelle": "Octroi de mer",
                    "base": 69.0,
                    "taux": 4.0,
                    "forfait": false,
                    "montant": 2.76,
                    "deductible": 0.0,
                    "note": null
                },
                {
                    "code": "octroi_de_mer_regional",
                    "libelle": "Octroi de mer régional",
                    "base": 69.0,
                    "taux": 2.5,
                    "forfait": false,
                    "montant": 1.73,
                    "deductible": 0.0,
                    "note": null
                },
                {
                    "code": "tva",
                    "libelle": "TVA (taux normal)",
                    "base": 74.0,
                    "taux": 8.5,
                    "forfait": false,
                    "montant": 6.29,
                    "deductible": 0.0,
                    "note": null
                }
            ],
            "total_taxes": 15.78,
            "taux_personnalises": false
        }
    ],
    "frais_transporteur": {
        "transporteur": "fedex",
        "nom": "FedEx",
        "source": "tarif",
        "tarif": 26.0,
        "remise_paiement_en_ligne": 0.0,
        "tva": null,
        "approximatif": true,
        "manutention": null,
        "pourcentage": null,
        "palier": null,
        "montant": 26.0
    },
    "totaux": {
        "taxes": 31.56,
        "frais": 26.0,
        "a_payer": 57.56,
        "cout_total": 195.56,
        "surcout_pourcentage": 41.7,
        "fourchette": null,
        "en_xpf": null
    },
    "conversion": null,
    "comparaison_transporteurs": [
        {
            "transporteur": "colissimo",
            "nom": "Colissimo",
            "frais": 8.0,
            "a_payer": 39.56,
            "approximatif": false
        },
        {
            "transporteur": "dhl",
            "nom": "DHL Express",
            "frais": 20.62,
            "a_payer": 52.18,
            "approximatif": false
        },
        {
            "transporteur": "ups",
            "nom": "UPS",
            "frais": 21.7,
            "a_payer": 53.26,
            "approximatif": false
        },
        {
            "transporteur": "chronopost",
            "nom": "Chronopost",
            "frais": 22.0,
            "a_payer": 53.56,
            "approximatif": false
        },
        {
            "transporteur": "fedex",
            "nom": "FedEx",
            "frais": 26.0,
            "a_payer": 57.56,
            "approximatif": true
        },
        {
            "transporteur": "ocx",
            "nom": "OCX",
            "frais": 26.0,
            "a_payer": 57.56,
            "approximatif": true
        }
    ],
    "remarques": [
        "Le forfait de 3 € s'applique à chaque type d'article du colis (même code douanier) : 5 t-shirts = 3 €, un t-shirt et une montre = le double.",
        "Ce colis contient 2 catégories de produits, comptées comme autant de types d'articles : 2 × 3 € = 6 € (deux produits d'une même catégorie peuvent pourtant avoir des codes douaniers différents).",
        "Frais de traitement UE : 2 € par type d'article sur tout achat à distance venant d'un pays hors UE depuis le 1er novembre 2026, même au-delà de 150 €. Dus par le vendeur, la plateforme ou le transporteur qui dédouane, ils vous sont refacturés : vérifiez s'ils sont déjà compris dans le prix payé à la commande.",
        "À La Réunion, FedEx confie le dédouanement à OCX, qui facture ses propres frais de traitement.",
        "Taux indicatifs pour les catégories « Vêtements », « Chaussures ». Le taux exact dépend du code douanier à 8 chiffres du produit : utilisez le mode expert si vous le connaissez."
    ],
    "taux_personnalises": false,
    "lien": "https://octroimer.fr/?acheteur=particulier&territoire=reunion&provenance=pays_tiers&envoi=achat&articles%5B0%5D%5Bcategorie%5D=vetements&articles%5B0%5D%5Bdescription%5D=T-shirt&articles%5B0%5D%5Bvaleur%5D=15&articles%5B0%5D%5Bquantite%5D=4&articles%5B1%5D%5Bcategorie%5D=chaussures&articles%5B1%5D%5Bdescription%5D=Baskets&articles%5B1%5D%5Bvaleur%5D=60&articles%5B1%5D%5Bquantite%5D=1&transport=18&transporteur=fedex#resultat"
}

Champ	Description
`territoire`, `acheteur`	Rappel de la destination et du type d'acheteur. `regime` vaut `octroi_de_mer`, `polynesie` ou `nouvelle_caledonie`, `devise` la monnaie locale (`EUR` ou `XPF`). `fiabilite_taux` vaut `elevee`, `moyenne` ou `faible`.
`montants`	Prix saisi, TVA métropolitaine déduite, prix retenu, port, assurance et `valeur_en_douane` (base des taxes).
`taxes[]`	Une ligne par taxe du régime du territoire, dans l'ordre : `droits_douane`, `octroi_de_mer`, `octroi_de_mer_regional`, `tva` dans les départements d'Outre-mer ; `taxation_forfaitaire` (colis d'un particulier jusqu'au plafond du forfait) ou `droits_douane`, `tdl`, `tva` en Polynésie française ; `droits_douane`, `tgc` en Nouvelle-Calédonie. Totaux du colis : chaque ligne donne `base`, `taux` (`null` pour un forfait ou quand les articles ont des taux différents), `forfait`, `montant` (ce que l'acheteur paie), `deductible` (TVA autoliquidée et déduite par un professionnel, non comprise dans `montant`) et une `note` (exonération, forfait…).
`articles[]`	Détail par article : `categorie`, `description`, `quantite`, `prix_unitaire`, `valeur`, `marchandise` (hors TVA métropolitaine), part du `transport` et de l'`assurance`, `valeur_en_douane`, `taxes` (même format, avec le taux de l'article), `total_taxes` et `taux_personnalises`.
`frais_transporteur`	`null` sans frais. Sinon : transporteur, `source` (`tarif` ou `saisie`), tarif publié, remise, TVA ajoutée, `palier` du barème appliqué (avec les droits et taxes avancés ou la `valeur_en_douane`, ses bornes et `tarif_professionnel`, sinon `null`), `pourcentage` pour un transporteur qui facture une part des droits et taxes (DHL, FedEx : `taux`, `droits_et_taxes_avances`, `minimum` et `minimum_applique`, sinon `null`), `manutention` comprise dans le tarif (FedEx en Martinique, sinon `null`), `approximatif` et `montant` payé.
`comparaison_transporteurs[]`	Frais de chaque transporteur pour ce colis, du moins cher au plus cher : `transporteur`, `nom`, `frais`, `a_payer` (taxes et frais) et `approximatif`. Vide quand aucune taxe n'est due.
`conversion`	`null` pour des prix en euros. Sinon : `devise`, `taux` (unités de la devise pour 1 €), `parite_fixe` (`true` pour le franc Pacifique), `date` du taux BCE (`null` à parité fixe) et `marchandise_dans_la_devise` (valeur saisie). Tous les autres montants de la réponse sont en euros.
`totaux`	`taxes`, `frais` (connus : transporteur indiqué ou montant saisi), `a_payer` (taxes et frais à l'arrivée), `cout_total` (tout compris) et `surcout_pourcentage`. Quand des taxes sont dues sans `transporteur` ni `frais`, un transporteur facturera tout de même des frais : `fourchette` donne alors `frais`, `a_payer`, `cout_total` et `surcout_pourcentage` en `{min, max}`, du transporteur le moins cher (`transporteur_le_moins_cher`) au plus cher (`transporteur_le_plus_cher`), et `approximatif`. Sinon `fourchette` vaut `null`. En Polynésie française et en Nouvelle-Calédonie, `en_xpf` redonne `valeur_en_douane`, `taxes`, `a_payer` et `cout_total` en francs Pacifique (`null` ailleurs).
`remarques[]`	Informations à afficher à l'utilisateur : fiabilité des taux, forfaits, partenaires des transporteurs…
`taux_personnalises`	`true` si un des champs `taux_*` a été fourni.
`lien`	Adresse de la même simulation sur le site.

Catalogue des taux

Les endpoints GET exposent les données utilisées par le calcul, par exemple pour construire vos propres listes de choix. Leurs réponses peuvent être mises en cache une heure.

/api/territoires : TVA par catégorie (null en Guyane et à Mayotte), fiabilité et source des taux.
/api/categories : droits de douane hors UE, catégorie de TVA, TVA métropolitaine et couple om/omr par territoire.
/api/transporteurs : tarif publié, HT ou TTC, remise et montant réellement payé dans chaque territoire. Là où le transporteur applique un barème selon les droits et taxes (UPS à La Réunion) ou selon la valeur du colis (Chronopost dans les DOM), frais_par_territoire vaut null et paliers donne chaque palier : ses bornes (…_au_dela_de exclue et …_jusqu_a incluse, ou …_a_partir_de incluse et …_moins_de exclue), frais publiés, frais_professionnel quand un professionnel paie un autre montant (sinon null) et montant payé par un particulier. Un transporteur qui facture une part des droits et taxes (DHL, FedEx) a un pourcentage_des_taxes : frais et frais_par_territoire sont alors son minimum, pourcentage_par_territoire donne la part propre à un territoire (null là où le montant est fixe). manutention_par_territoire donne les frais de manutention ajoutés dans un territoire (FedEx en Martinique), et territoires_approximatifs les territoires où le montant n'est qu'une estimation, faute de barème publié.

Un élément de /api/transporteurs

{
    "code": "colissimo",
    "nom": "Colissimo",
    "frais": 8,
    "pourcentage_des_taxes": null,
    "ttc": true,
    "remise_paiement_en_ligne": 3,
    "approximatif": false,
    "territoires": [
        "guadeloupe",
        "martinique",
        "guyane",
        "reunion",
        "mayotte",
        "polynesie",
        "nouvelle_caledonie",
        "saint_pierre_miquelon"
    ],
    "frais_par_territoire": {
        "guadeloupe": 8.0,
        "martinique": 8.0,
        "guyane": 8.0,
        "reunion": 8.0,
        "mayotte": 8.0,
        "polynesie": 6.45,
        "nouvelle_caledonie": null,
        "saint_pierre_miquelon": 3.15,
        "saint_barthelemy": null,
        "saint_martin": null,
        "wallis_futuna": null
    },
    "paliers": {
        "nouvelle_caledonie": [
            {
                "valeur_au_dela_de": null,
                "valeur_jusqu_a": 25.14,
                "frais": 0,
                "frais_professionnel": null,
                "montant": 0
            },
            {
                "valeur_au_dela_de": 25.14,
                "valeur_jusqu_a": 251.4,
                "frais": 16.34,
                "frais_professionnel": null,
                "montant": 16.34
            },
            {
                "valeur_au_dela_de": 251.4,
                "valeur_jusqu_a": null,
                "frais": 27.65,
                "frais_professionnel": null,
                "montant": 27.65
            }
        ]
    },
    "pourcentage_par_territoire": {},
    "manutention_par_territoire": {},
    "territoires_approximatifs": [],
    "notes": {
        "polynesie": "En Polynésie française, Colissimo est livré par Fare Rata (OPT) : 770 XPF de frais d'arrivée pour un colis taxé au forfait. Au-delà de 50 000 XPF, le dossier de dédouanement par commissionnaire coûte à partir de 6 000 XPF.",
        "nouvelle_caledonie": "En Nouvelle-Calédonie, Colissimo est livré par l'OPT-NC : 1 950 XPF de frais de dédouanement jusqu'à 30 000 XPF de valeur, 3 300 XPF jusqu'à 100 000 XPF. Au-delà, un déclarant privé facture ses propres honoraires.",
        "saint_pierre_miquelon": "À Saint-Pierre-et-Miquelon, La Poste facture 3,15 € par colis présenté à la douane."
    }
}

Limite d'appels

Chaque adresse IP (en IPv6, chaque bloc /64) peut faire 60 appels par minute, tous endpoints confondus, sur une fenêtre glissante. Les requêtes invalides comptent aussi. Au-delà, l'API répond 429 avec un en-tête Retry-After : le nombre de secondes à attendre avant de réessayer.

Les catalogues changent rarement : gardez-les en cache une heure au lieu de les redemander à chaque simulation.

Erreurs

Toutes les erreurs sont en JSON, au format « problem details » (RFC 7807), avec status et detail.

Statut	Cause
`400`	Le corps n'est pas du JSON valide.
`404`	Chemin ou code inconnu (`/api/categories/xyz`).
`405`	Mauvaise méthode HTTP (par exemple `GET /api/simulations`).
`413`	Corps de plus de 64 Ko (une simulation en fait quelques-uns).
`415`	Corps envoyé dans un autre format que JSON.
`422`	Données invalides : champ manquant, mauvais type, code inconnu, valeur hors limites.
`429`	Trop d'appels (plus de 60 par minute) : réessayer après le délai indiqué par `Retry-After`.
`503`	Prix dans une autre `devise` que l'euro alors que les taux de la BCE sont momentanément indisponibles : envoyer les montants en euros ou réessayer plus tard.

Pour une erreur 422, violations liste chaque problème : propertyPath est le nom du champ envoyé et title le message en français, prêt à être affiché.

Réponse 422

{
  "type": "https://symfony.com/errors/validation",
  "title": "Validation Failed",
  "status": 422,
  "detail": "territoire: Code inconnu \"atlantide\". Valeurs possibles : guadeloupe, martinique, guyane, reunion, mayotte, polynesie, nouvelle_caledonie, saint_pierre_miquelon, saint_barthelemy, saint_martin, wallis_futuna.",
  "violations": [
    {
      "propertyPath": "territoire",
      "title": "Code inconnu \"atlantide\". Valeurs possibles : guadeloupe, martinique, guyane, reunion, mayotte, polynesie, nouvelle_caledonie, saint_pierre_miquelon, saint_barthelemy, saint_martin, wallis_futuna.",
      "template": "Code inconnu {{ value }}. Valeurs possibles : {{ choices }}.",
      "parameters": { "{{ value }}": "\"atlantide\"", "{{ choices }}": "guadeloupe, martinique, guyane, reunion, mayotte, polynesie, nouvelle_caledonie, saint_pierre_miquelon, saint_barthelemy, saint_martin, wallis_futuna" },
      "type": "urn:uuid:6a0e3f8e-6f4f-4d0f-9a43-2f7b8f6c9d21"
    }
  ]
}

Essayer l'API

Modifiez le corps de la requête puis envoyez-le : la réponse brute de POST /api/simulations s'affiche en dessous.

Corps de la requête (JSON)

Documentation de l'API