Documentation technique

Architecture du moteur fiscal, des parsers Amazon et de l’interface Streamlit.

Checklist de Conformité

  • Compléter l'Onboarding Lighthouse pour configurer votre fiche entreprise.
  • Vérifier la validité des numéros TVA B2B via l'onglet VIES.
  • S'assurer que le Pays de Siège est correctement configuré.
  • Vérifier les alertes de Stock FBA pour les immatriculations locales.
  • Réconcilier le CA HT Net avec votre comptabilité via l'export FEC.

Sources de données & API

  • VIES (EU) : Validation des numéros de TVA en temps réel.
  • BCE (SDW) : Récupération quotidienne des taux de change officiels.
  • Polars / Pandas : Parsing haute performance des gros volumes de données (Amazon).
  • DGFIP / Schémas XSD : Validation des fichiers XML OSS.

Cœur du Moteur

  • engine.py : Moteur de classification fiscale (Directive 2006/112/CE).
  • rates.py : Taux TVA historisés par pays et catégorie (Standard/Réduit).
  • ecb_rates.py : Synchro auto avec la Banque Centrale Européenne (BCE).
  • vies_engine.py : Validation VIES avec cache et piste d'audit conforme (365 jours).
  • ca3_report.py / oss_xml.py : Générateurs de liasses fiscales (HTML/XML).
  • local_vat_report.py : Rapports de TVA locaux pour les autres pays de l'UE.
  • billing.py : Moteur de facturation Stripe et gestion des quotas.

📄 Spécifications Techniques Complètes (README)

Accédez à la documentation brute du projet, incluant la structure des fichiers et les scénarios détaillés.

Arborescence du dépôt

tva-intracom/
├── .devcontainer/
├── .github/
│   └── workflows/
│       └── ci.yml                    Pipeline CI (pytest)
├── data/
├── schemas/                          Schémas XSD officiels (DGFIP/UE)
├── tests/                            Tests unitaires et d'intégration
├── tva_intracom/
│   ├── i18n/                         Fichiers de traduction (7 langues)
│   ├── parsers/
│   │   ├── amazon/                   Import Amazon formats 1-5
│   │   ├── aliexpress.py             Parser AliExpress
│   │   ├── mirakl.py                 Parser Mirakl
│   │   ├── shopify.py                Parser Shopify
│   │   └── woocommerce.py            Parser WooCommerce
│   ├── ui/                           Interface Streamlit modulaire
│   │   ├── admin.py                  Gestion des rôles et organisation
│   │   ├── auth_flow.py              Flux d'authentification UI
│   │   ├── background_calc.py        Calculs longs et file d'attente (MAX=1)
│   │   ├── billing_gate.py           Gating de facturation et quotas
│   │   ├── calc_cache.py             State management (CalcCacheState)
│   │   ├── display_mode.py           Mode Simple / Détaillé global
│   │   ├── files.py                  Cache compressé des uploads (MD5)
│   │   ├── formatting.py             Helpers d'affichage et conversion
│   │   ├── glossary.py               Gestion du glossaire TVA et tooltips d'aide
│   │   ├── onboarding.py             Stepper guidé Lighthouse CSS
│   │   ├── rerun_utils.py            Gestion des st.rerun()
│   │   ├── sidebar.py                Barre latérale de configuration
│   │   ├── theme.py                  Thème et CSS adaptatif
│   │   └── tabs/                     Modules d'onglets (OSS, Ventes, VIES...)
│   ├── amazon_adapter.py             Passerelle de compatibilité modèles
│   ├── auth_supabase.py              Authentification Supabase Auth
│   ├── billing.py                    Facturation Stripe et quotas SIREN
│   ├── ca3_report.py                 Rapport CA3 (HTML)
│   ├── database.py                   Pooling Postgres centralisé
│   ├── ecb_rates.py                  Taux BCE (cache multi-niveaux)
│   ├── engine.py                     Moteur de classification fiscale
│   ├── excel_report.py               Export Excel multi-onglets
│   ├── fec_export.py                 Export comptable FEC
│   ├── local_vat_report.py           Rapports TVA locaux UE
│   ├── models.py                     Dataclasses (Pydantic)
│   ├── oss_export.py                 Agrégation OSS et exports CSV
│   ├── oss_xml.py                    Génération XML OSS officiel
│   ├── product_tax_code_category.py  Classification Amazon (PRODUCT_TAX_CODE -> catégorie interne)
│   ├── rates.py                      Taux TVA historisés
│   ├── security.py                   Sécurité Amazon DPP (Fernet)
│   ├── vat_rates_db.py               Taux de TVA dynamiques via l'API TEDB
│   ├── vies_engine.py                Validation VIES avec cache Postgres
│   └── vies_certificate.py           Génération de certificat VIES PDF
│
├── vercel_webhook/                   Webhook Stripe (Vercel)
├── app.py                            Orchestrateur Streamlit principal
├── Procfile                          Configuration démarrage cloud
├── pyproject.toml                    Dépendances et config projet
└── README.md                         Documentation générale

Scénarios modélisés

Scénario Situation Règle appliquée
DOMESTIC Stock et acheteur dans le même pays UE (y compris Monaco). TVA locale du pays.
OSS_B2C B2C transfrontalier intra-UE. TVA du pays de destination (OSS).
B2B_REVERSE B2B intra-UE avec n° TVA valide. Exonération (Autoliquidation).
DEEMED_SUPPLIER Vendeur hors UE ou import ≤ 150€. Collecté par Amazon.
EXPORT Acheteur hors UE. Exonération (Exportation).
IMPORT_STD Import > 150€ (B2C). TVA importation (Douane).
IOSS_DIRECT Import ≤ 150€ avec n° IOSS propre. Collecté par le vendeur via IOSS.
IMPORT_DDP Import > 150€ (Vendeur importateur). TVA locale pays destination.

Formats Amazon supportés

  • Format 1-2 : Anciens formats TSV.
  • Format 3-4 : Formats 2024-2025.
  • Format 5 : Rapport fiscal détaillé V5 (Multi-juridictions).

Roadmap

  • ⏳ Intégration directe EDI-TVA (Télédéclaration automatique Cerfa).
  • 📄 Export XML IOSS officiel (Import Scheme).