Patterns
TVA intra-UE et autoliquidation
Résolution serveur autoritaire de la catégorie TVA et mentions CGI
Pour une vente B2B intra-UE, la TVA est en principe autoliquidée par l'acheteur (reverse charge) : le vendeur facture HT et porte une mention légale. Scell.io résout la catégorie TVA côté SERVEUR de façon autoritaire (`buyers.vatContext`) selon des règles : franchise en base (CGI 293 B) → catégorie E, biens intra-UE → K, services intra-UE → AE (autoliquidation art. 196 directive 2006/112/CE), export hors UE → G. La résolution s'appuie sur le statut TVA de l'acheteur (vérifié VIES) et le type de fourniture (biens/services). Anti-pattern : faire confiance à une catégorie TVA fournie par le client sans contrôle — l'API renvoie un 409 `VAT_CORRECTION_REQUIRED` si la catégorie soumise diverge de la résolution autoritaire, sauf override tracé (`vat_override_reason`). Le Factur-X émis porte alors le code de catégorie BT-118 et la mention CGI/directive correspondante (BT-120), bilingue selon la langue de l'acheteur.
À retenir
- Résolution TVA autoritaire côté serveur (`buyers.vatContext`)
- Catégories : E (franchise 293 B), K (biens UE), AE (services UE), G (export)
- Statut TVA acheteur vérifié via VIES
- Guard 409 `VAT_CORRECTION_REQUIRED` si divergence (override tracé)
- Factur-X : code BT-118 + mention CGI/directive BT-120 bilingue
- Autoliquidation services UE = art. 196 directive 2006/112/CE
Exemple de code
import { ScellApiClient } from '@scell/sdk'; // v3.5.0
const client = new ScellApiClient({ apiKey: process.env.SCELL_API_KEY! });
// 1. Résolution autoritaire de la catégorie TVA pour un acheteur UE
const vat = await client.buyers.vatContext('buyer-uuid', {
// type de fourniture : biens (goods) ou services
supply_type: 'services',
});
console.log('Catégorie TVA résolue :', vat.category, '→ taux', vat.rate);
// services intra-UE → 'AE' (autoliquidation), taux 0
// 2. Facturer : laisser le serveur appliquer la catégorie autoritaire.
// Soumettre une catégorie divergente → 409 VAT_CORRECTION_REQUIRED.
const invoice = await client.invoices.create({
format: 'factur-x',
profile: 'EN16931',
currency: 'EUR',
buyer: {
name: 'Müller GmbH',
vat_number: 'DE123456789',
address: { street: 'Hauptstr. 1', city: 'Berlin', postal_code: '10115', country: 'DE' },
},
lines: [{ description: 'Prestation de conseil', quantity: 1, unit_price: 3000, vat_rate: 0 }],
// Factur-X émis avec BT-118='AE' + mention autoliquidation BT-120
});
console.log('Facture autoliquidée :', invoice.id);