{"id":445107,"date":"2026-10-28T11:01:26","date_gmt":"2026-10-28T10:01:26","guid":{"rendered":"https:\/\/www.kafinea.com\/documentation\/uncategorized\/api-rest-regions-fiscales\/"},"modified":"2026-10-28T12:53:51","modified_gmt":"2026-10-28T11:53:51","password":"","slug":"api-rest-regions-fiscales","status":"publish","type":"docs","link":"https:\/\/www.kafinea.com\/fr\/documentation\/api\/api-rest-regions-fiscales\/","title":{"rendered":"API REST \u2013 Taxes, r\u00e9gions fiscales et r\u00e8gles territoriales"},"content":{"rendered":"

L’API donne acc\u00e8s \u00e0 tout le param\u00e9trage de l’\u00e9cran Calcul des taxes<\/strong> : les taxes et leur mode de calcul, les frais et leurs montants par r\u00e9gion, les r\u00e9gions fiscales, la r\u00e9gion de chaque pays, les exceptions territoriales, la proposition automatique et le testeur d’adresse. Les contr\u00f4les sont ceux de l’\u00e9cran : ce qu’il refuse, l’API le refuse avec le m\u00eame motif.<\/p>\n

Les trois op\u00e9rations utilisent la session de l’API REST<\/a> et sont r\u00e9serv\u00e9es aux comptes administrateurs<\/strong>.<\/p>\n

\n\n\n\n\n\n\n\n
Op\u00e9ration<\/th>\nM\u00e9thode<\/th>\nR\u00e9sultat<\/th>\n<\/tr>\n<\/thead>\n
tax_region_configuration<\/code><\/td>\nGET<\/td>\nParam\u00e9trage complet et contr\u00f4les de coh\u00e9rence<\/td>\n<\/tr>\n
tax_region_preview<\/code><\/td>\nGET<\/td>\nR\u00e9gion d’une adresse, et proposition pour un nouveau document, sans rien enregistrer<\/td>\n<\/tr>\n
tax_region_configure<\/code><\/td>\nPOST<\/td>\nUne modification, valid\u00e9e puis enregistr\u00e9e en une seule fois<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n

Le param\u00e8tre input<\/code> est un objet JSON. Les cases \u00e0 cocher (enabled<\/code>, active<\/code>, taxable<\/code>, documentTest<\/code>, intravatApproved<\/code>) attendent un vrai bool\u00e9en JSON : la cha\u00eene "false"<\/code> est refus\u00e9e.<\/p>\n

\n

1. Lire le param\u00e9trage<\/h2>\n

tax_region_configuration<\/code> ne prend aucun param\u00e8tre.<\/p>\n

curl 'https:\/\/apps.kafinea.com\/YourKafinea\/webservice.php?operation=tax_region_configuration&sessionName=YOUR_SESSION_ID'\n<\/code><\/pre>\n
\n\n\n\n\n\n\n\n\n\n\n\n
Cl\u00e9 de result.configuration<\/code><\/th>\nContenu<\/th>\n<\/tr>\n<\/thead>\n
regions<\/code><\/td>\nIdentifiant num\u00e9rique et nom de chaque r\u00e9gion fiscale<\/td>\n<\/tr>\n
taxes<\/code><\/td>\nChaque taxe des articles (appliesTo: product<\/code>) et des frais (shipping<\/code>), inactives comprises : taxId<\/code>, nom, active<\/code>, mode de calcul method<\/code>, type, compoundOn<\/code>, taux par d\u00e9faut defaultRate<\/code> et taux par r\u00e9gion ratesByRegionId<\/code><\/td>\n<\/tr>\n
charges<\/code><\/td>\nChaque frais de l’onglet Frais (& leurs taxes)<\/strong> : chargeId<\/code>, nom, format<\/code>, type, montant par d\u00e9faut defaultValue<\/code>, montants par r\u00e9gion valuesByRegionId<\/code>, taxable<\/code> et taxes appliqu\u00e9es taxIds<\/code><\/td>\n<\/tr>\n
countries<\/code><\/td>\nChaque pays : identifiant, code ISO, r\u00e9gion de base, r\u00e9gions professionnelle et particulier, condition professionnelle<\/td>\n<\/tr>\n
rules<\/code><\/td>\nLes exceptions territoriales, actives ou non, avec leur crit\u00e8re et leur priorit\u00e9<\/td>\n<\/tr>\n
enabled<\/code>, departure_country<\/code>, operation_kind<\/code>, organization_ids<\/code><\/td>\nLa proposition automatique et son p\u00e9rim\u00e8tre<\/td>\n<\/tr>\n
diagnostics<\/code><\/td>\nconfigurationIssues<\/code> (pays en double, exceptions qui se chevauchent, r\u00e9gion supprim\u00e9e) et missingRates<\/code> (taux absents pour une r\u00e9gion utilis\u00e9e)<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n
Les identifiants de cette r\u00e9ponse sont ceux \u00e0 renvoyer dans les modifications. Ils diff\u00e8rent d’une instance \u00e0 l’autre : lisez-les sur l’instance vis\u00e9e.<\/p>\n
\n
2. Tester une adresse ou un nouveau document<\/h2>\n
tax_region_preview<\/code> re\u00e7oit l’adresse dans input<\/code> : country<\/code> (code ISO, nom fran\u00e7ais ou anglais), postcode<\/code> et state<\/code>.<\/p>\n
curl -G 'https:\/\/apps.kafinea.com\/YourKafinea\/webservice.php' \\\n  --data-urlencode 'operation=tax_region_preview' \\\n  --data-urlencode 'sessionName=YOUR_SESSION_ID' \\\n  --data-urlencode 'input={"country":"France","postcode":"97300"}'\n<\/code><\/pre>\n
La r\u00e9ponse indique le pays reconnu, la r\u00e9gion g\u00e9ographique (geography<\/code>) et la r\u00e8gle ou le pays qui l’a choisie. Avec documentTest: true<\/code>, ajoutez les faits du client et de l’op\u00e9ration (partyNature<\/code>, intravatApproved<\/code>, vatNumber<\/code>, organizationId<\/code>, operation<\/code>, goodsOrServices<\/code>, departureCountry<\/code>, partyRegionId<\/code>) : la r\u00e9ponse contient alors la r\u00e9gion qu’un nouveau<\/strong> document recevrait (document<\/code>). Aucun fait n’est devin\u00e9. vatNumber<\/code> est le num\u00e9ro de TVA du client, une cha\u00eene JSON ; un autre type est refus\u00e9.<\/p>\n
organizationId<\/code> accepte l’identifiant de la soci\u00e9t\u00e9 ou son nom exact (\u00e9galement via organizationName<\/code>). Une soci\u00e9t\u00e9 absente, inconnue ou dont le nom est port\u00e9 par plusieurs soci\u00e9t\u00e9s est signal\u00e9e dans inputIssues<\/code>, avec les soci\u00e9t\u00e9s configur\u00e9es.<\/p>\n
Quand le contexte de l’op\u00e9ration ne permet pas de proposer une r\u00e9gion, document.advisories<\/code> contient UNSUPPORTED_TAX_CONTEXT<\/code> et document.advisory_details<\/code> en pr\u00e9cise la cause :<\/p>\n
\n\n\n\n\n\n\n\n\n\n\n\n
cause<\/code><\/th>\nSignification<\/th>\n<\/tr>\n<\/thead>\n
ORGANIZATION_NOT_CONFIGURED<\/code><\/td>\nLa soci\u00e9t\u00e9 ne fait pas partie des soci\u00e9t\u00e9s retenues pour la s\u00e9lection automatique<\/td>\n<\/tr>\n
OPERATION_KIND_NOT_SUPPORTED<\/code><\/td>\nL’op\u00e9ration ne porte pas sur des biens<\/td>\n<\/tr>\n
DEPARTURE_COUNTRY_NOT_CONFIGURED<\/code><\/td>\nLe pays de d\u00e9part du param\u00e9trage est absent ou non reconnu<\/td>\n<\/tr>\n
DEPARTURE_COUNTRY_UNKNOWN<\/code><\/td>\nLe pays de d\u00e9part fourni est absent ou non reconnu<\/td>\n<\/tr>\n
DEPARTURE_COUNTRY_MISMATCH<\/code><\/td>\nLe pays de d\u00e9part fourni diff\u00e8re de celui du param\u00e9trage<\/td>\n<\/tr>\n
MODULE_NOT_SUPPORTED<\/code><\/td>\nLe document n’est pas un document de vente<\/td>\n<\/tr>\n
OPERATION_NOT_SALE<\/code><\/td>\nL’op\u00e9ration n’est pas une vente<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n
Chaque entr\u00e9e donne aussi la valeur re\u00e7ue (actual<\/code>), la valeur attendue (expected<\/code>) et un message<\/code> lisible, par exemple : \u00ab La soci\u00e9t\u00e9 0 ne fait pas partie des soci\u00e9t\u00e9s configur\u00e9es pour la s\u00e9lection automatique de la r\u00e9gion : 530 (Ma soci\u00e9t\u00e9). \u00bb<\/p>\n
Pour essayer une modification avant de l’enregistrer, ajoutez configurationPreview<\/code> : le m\u00eame objet que celui de tax_region_configure<\/code>, compl\u00e9t\u00e9 par configurationKind<\/code> (settings<\/code>, country<\/code> ou rule<\/code>).<\/p>\n
\n
3. Modifier le param\u00e9trage<\/h2>\n
tax_region_configure<\/code> re\u00e7oit kind<\/code> et l’objet input<\/code> complet de la modification.<\/p>\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
kind<\/code><\/th>\nEffet<\/th>\ninput<\/code><\/th>\n<\/tr>\n<\/thead>\n
region<\/code><\/td>\nCr\u00e9e, renomme ou supprime une r\u00e9gion<\/td>\n{"action":"save","name":"\u2026"}<\/code> pour cr\u00e9er ; ajoutez region_id<\/code> pour renommer ; {"action":"delete","region_id":12}<\/code> pour supprimer<\/td>\n<\/tr>\n
tax_grid<\/code><\/td>\nRemplace le taux par d\u00e9faut et les taux par r\u00e9gion d’une taxe existante<\/td>\nappliesTo<\/code>, taxId<\/code>, defaultRate<\/code>, ratesByRegionId<\/code> complet, par exemple {"3":0,"5":20}<\/code><\/td>\n<\/tr>\n
tax<\/code><\/td>\nCr\u00e9e une taxe, ou red\u00e9finit une taxe existante<\/td>\nappliesTo<\/code>, name<\/code>, active<\/code>, method<\/code> (Simple<\/code>, Compound<\/code> ou Deducted<\/code>), type<\/code> (Fixed<\/code> ou Variable<\/code>), defaultRate<\/code>, ratesByRegionId<\/code>, compoundOn<\/code> ; taxId<\/code> pour modifier<\/td>\n<\/tr>\n
tax_status<\/code><\/td>\nActive ou d\u00e9sactive une taxe<\/td>\nappliesTo<\/code>, taxId<\/code>, active<\/code><\/td>\n<\/tr>\n
charge<\/code><\/td>\nCr\u00e9e un frais, ou red\u00e9finit un frais existant avec ses montants par r\u00e9gion<\/td>\nname<\/code>, format<\/code> (Flat<\/code> ou Percent<\/code>), type<\/code>, defaultValue<\/code>, valuesByRegionId<\/code>, taxable<\/code>, taxIds<\/code> ; chargeId<\/code> pour modifier<\/td>\n<\/tr>\n
charge_delete<\/code><\/td>\nSupprime un frais<\/td>\nchargeId<\/code><\/td>\n<\/tr>\n
country<\/code><\/td>\nChange la r\u00e9gion d’un pays, ou de plusieurs pays \u00e0 la fois<\/td>\ncountry_id<\/code>, mdstaxregionid<\/code>, mdsprofessionaltaxregionid<\/code>, mdsindividualtaxregionid<\/code>, mdsprofessionaltaxcondition<\/code> (nature_only<\/code>, qualified_customer<\/code> ou vat_number<\/code>) ; ou isocodes<\/code> avec seulement les champs \u00e0 changer (voir plus bas)<\/td>\n<\/tr>\n
rule<\/code><\/td>\nCr\u00e9e ou modifie une exception territoriale<\/td>\nlabel<\/code>, country<\/code>, criterion_type<\/code> (postcode_prefix<\/code>, postcode_range<\/code>, subdivision<\/code>), criterion_value<\/code>, criterion_end<\/code> pour une plage, priority<\/code>, active<\/code>, les trois r\u00e9gions et la condition ; ruleid<\/code> pour modifier<\/td>\n<\/tr>\n
settings<\/code><\/td>\nActive ou r\u00e8gle la proposition automatique<\/td>\nenabled<\/code>, departure_country<\/code>, operation_kind<\/code> (goods<\/code> pour activer), organization_ids<\/code><\/td>\n<\/tr>\n
french_baseline<\/code><\/td>\nEx\u00e9cute G\u00e9n\u00e9rer le param\u00e9trage fiscal France<\/strong><\/td>\n{}<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n
curl -X POST 'https:\/\/apps.kafinea.com\/YourKafinea\/webservice.php' \\\n  -d 'operation=tax_region_configure' \\\n  -d 'sessionName=YOUR_SESSION_ID' \\\n  -d 'kind=rule' \\\n  --data-urlencode 'input={"label":"Canaries \u2013 Las Palmas","country":"ES","criterion_type":"postcode_prefix","criterion_value":"35","priority":50,"active":true,"mdstaxregionid":5,"mdsprofessionaltaxregionid":0,"mdsindividualtaxregionid":0,"mdsprofessionaltaxcondition":"nature_only"}'\n<\/code><\/pre>\n
Dans cet exemple, 5<\/code> est l’identifiant de la r\u00e9gion \u00ab Hors UE \u00bb lu sur l’instance. Une r\u00e9gion vaut 0<\/code> quand elle n’est pas renseign\u00e9e. La r\u00e9ponse {"saved":true,"result":{\u2026}}<\/code> donne l’identifiant cr\u00e9\u00e9 ou modifi\u00e9 (region_id<\/code>, ruleid<\/code>, taxId<\/code>, chargeId<\/code>). Relisez ensuite le param\u00e9trage avec tax_region_configuration<\/code>, puis testez quelques adresses.<\/p>\n
Les garanties sont celles de l’\u00e9cran :<\/p>\n