Ce guide explique comment renseigner correctement le tableau taxes_attributes lors de la création de factures via l’API afin que les intégrateurs sachent quels noms et catégories de taxe sont attendus selon le pays.
Important
Les pourcentages indiqués sont les valeurs par défaut de B2Brouter pour faciliter l’intégration ; les taux de taxe peuvent changer. Vérifiez toujours la législation en vigueur dans chaque pays.
Les noms des taxes doivent correspondre aux valeurs attendues dans ce guide. N’inventez pas de nouveaux noms (par ex. "Exento", "Umsatzsteuer", "Sales tax").
De nombreux formats réutilisent comment comme motif d’exonération / « non soumis ». Renseignez-le dès que vous définissez 0 % / exonéré / autoliquidation, sauf si votre compte a déjà le bon motif par défaut.
Utilisez uniquement ces champs dans chaque objet taxes_attributes : name (string), category (string, enum), percent (float), comment (string ou null). N’ajoutez aucune autre clé comme amount, base, type, etc.
Les pourcentages sont les valeurs par défaut que nous attendons ; les lois évoluent. Si votre cas d’usage utilise un taux différent, envoyez ce taux tout en conservant le bon name et la bonne category.
Pour les retenues à la source / rétentions, utilisez un percentnégatif et le nom de taxe approprié (IRPF, IRNR, IRPEF, etc.).
comment est utilisé comme motif d’exonération / « non soumis » dans de nombreux formats (Facturae/Verifactu, catégories Peppol, etc.). Fournissez un motif dès que percent vaut 0 et que l’opération est exonérée / non soumise / en autoliquidation (exemple : comment: "E2").
Les paramètres du compte ont un impact sur le calcul : apply_taxes_per_line (boolean) contrôle si les taxes sont appliquées par ligne ou sur la somme ; rounding_method contrôle l’arrondi.
Chaque ligne de facture (invoice_lines_attributes) peut contenir un tableau de taxes :
"taxes_attributes": [
{
"name":"VAT",
"category":"S",
"percent":21.0,
"comment":"Standard VAT"
}
]
Pour chaque objet taxe :
name (obligatoire) : nom de la taxe (doit correspondre à l’une des valeurs attendues pour le pays de l’entreprise, voir Référence par pays).
category (recommandé) : code de catégorie de taxe (voir Catégories de taxe).
percent (obligatoire) : pourcentage de taxe. Utilisez des valeurs négatives pour les retenues ou rétentions.
comment (optionnel mais recommandé pour 0 % / exonération / autoliquidation) : motif en texte libre utilisé par plusieurs formats et administrations fiscales.
Plusieurs taxes peuvent être appliquées à une même ligne en ajoutant plusieurs objets dans taxes_attributes.
Seuls ces champs sont valides. N’incluez pasamount, base ou d’autres champs personnalisés ; ils sont calculés en interne pour éviter les incohérences.
field
type
required
description
name
string
yes
Nom de la taxe (doit correspondre aux valeurs par défaut du pays)
category
string, enum
recommended
Code de catégorie de taxe (voir la liste ci-dessous)
percent
float
yes
Pourcentage de taxe (négatif pour les retenues)
comment
string or null
optional
Motif / explication, requis pour de nombreux cas exonérés / non soumis
Paramètres fiscaux du compte qui affectent les calculs
apply_taxes_per_line (boolean) : lorsqu’il vaut true, les taxes sont appliquées par ligne puis additionnées ; lorsqu’il vaut false, les bases sont additionnées et la taxe est appliquée au total.
rounding_method : stratégie d’arrondi (half_up par défaut). Voir Calcul de facture.
B2Brouter utilise des catégories de taxe alignées sur la liste de codes PEPPOL/UNCL5305 et, pour certains pays, des codes supplémentaires exigés par l’administration fiscale locale.
Codes de catégorie courants :
S – Taux standard.
H – Taux élevé.
AA – Taux réduit.
AAA – Taux super réduit.
Z – Opération à taux zéro (0 % mais soumise à TVA).
E – Exonéré (0 % et exonéré de TVA).
AE – Autoliquidation / « Inversión del sujeto pasivo ».
G – Exportation exonérée, TVA non facturée.
K – Livraison intracommunautaire de biens/services (exonérée de TVA dans l’EEE).
NS – Non soumis.
O – Hors champ de la taxe / autres opérations.
Seules ces valeurs de catégorie sont acceptées ; les autres codes seront rejetés.
Singapour utilise des codes de catégorie GST supplémentaires (voir Singapour) et l’Italie utilise les codes « natura » FatturaPA N.. (voir Italie).
Utilisez les noms de taxe par défaut du pays dans les tableaux ci-dessous (ils correspondent à la configuration par défaut de B2Brouter lors de la création d’une entreprise). Conservez les noms / codes même si votre taux diffère.
Pour la TVA standard, utilisez le nom principal de TVA et category: "S" avec le percent approprié.
Pour les taux réduits, utilisez category: "AA" ou category: "AAA" selon les valeurs par défaut indiquées.
Pour les opérations à taux zéro ou exonérées :
Utilisez percent: 0.
Choisissez category en fonction de la situation juridique :
Z : taxable mais à 0 %.
E : exonéré.
AE : autoliquidation.
Codes locaux pour des régimes spécifiques (Italie N.., catégories GST de Singapour, etc.).
Pour les retenues / rétentions, utilisez des pourcentages négatifs (par ex. -19 pour l’IRPF espagnol) et le nom de taxe correspondant à la retenue (par ex. IRPF, IRNR, IRPEF).
Lors de l’intégration avec des déclarations fiscales (Verifactu, TicketBAI, LHDN, etc.), assurez-vous que vos taxes_attributes sont compatibles avec le guide correspondant.
Référence par pays – noms de taxe valides et taux par défaut
Les tableaux suivants listent les noms de taxe attendus par pays, avec les taux par défaut et catégories que nous préchargeons. Utilisez-les comme référence pour les noms et catégories ; ajustez percent si la législation ou votre scénario l’exige.
Les pourcentages peuvent évoluer dans le temps ; vérifiez toujours la législation locale en vigueur. Les taux et catégories sont alignés par position dans chaque ligne (premier taux → première catégorie, etc.).
L’Espagne comporte plusieurs régimes de TVA selon le code postal de l’entreprise :
Péninsule / Îles Baléares : IVA.
Îles Canaries : IGIC.
Ceuta / Melilla : IPSI.
comment est utilisé comme motif d’exonération / non-soumis dans Facturae/Verifactu. Si vous envoyez percent: 0 pour une opération exonérée ou non soumise, ajoutez le motif dans comment (exemple : comment: "E2"). Si votre compte définit déjà le motif par défaut, vous pouvez l’omettre.
Utilisez IVA/IGIC/IPSI avec percent: 0 et la bonne category (E, Z ou AE) plus un motif dans comment pour les opérations exonérées / non soumises (par ex. E2).
Utilisez un percent négatif pour les retenues IRPF.
Retenue à la source (si applicable via FatturaPA).
Pour FatturaPA, les opérations non imposables utilisent des codes category comme N1, N2.1, N2.2, N3.1, N3.2, N3.3, N3.4, N3.5, N3.6, N4, N5, N6.1… (voir votre configuration FatturaPA). Ils doivent être envoyés avec 0 % de TVA, name: "IVA" et category: "N..".
Recommandation (Italie)
Pour les opérations standard : name: "IVA", category: "S", percent: 22.
Pour les opérations non imposables : name: "IVA", percent: 0 et le code N.. approprié dans category.
Utilisé pour indiquer « pas de TVA » / hors champ.
Recommandation (États-Unis)
Pour les entreprises sans numéro de TVA, utilisez une seule taxe avec name: "VAT", percent: 0, category: "O" et éventuellement comment: "Company without VAT ID".
Ne créez pas de noms de taxes locales de type sales tax dans taxes_attributes ; la gestion de la TVA est modélisée comme 0 % hors champ.
