DeclarationTVA/PLANNING.md

DeclarationTVA - French CA-3 VAT Declaration Module

Project Overview

This Dolibarr module creates the French VAT declaration CA-3 (Déclaration de TVA CA3) with PCG account mapping functionality. The module allows users to configure PCG (Plan Comptable Général) accounts for each CA-3 box and generates the appropriate VAT declaration.

Architecture

Core Components

• Module Class: modDeclarationTVA.class.php - Main module descriptor
• Setup Interface: admin/setup.php - Configuration page for PCG account mapping
• Database Schema: sql/dolibarr_allversions.sql - Database structure
• Language Support: Bilingual (French/English) interface
• Main Interface: declarationtvaindex.php - Main module page

CA-3 Box Structure

The module handles the complete French CA-3 VAT declaration structure:

CA-3 Form Structure (n° 3310-CA3-SD)

A. Opérations imposables (Taxable Operations)

CA-3 Line	Label	Description	PCG Accounts	Form Mapping
A1	Montant hors TVA des opérations imposables	Base HT of taxable operations (sales/services)	7xxxx (Sales)	Domestic sales base amounts
A2	Opérations imposables mais ne relevant pas du CA courant	Special taxable operations (asset sales, self-deliveries)	7xxxx (Special sales)	Non-ordinary taxable operations
B1	Répartition 20% (base + taxe)	20% VAT operations (base + VAT)	7xxxx → 44571x	Standard rate operations
B2	Répartition 10% (base + taxe)	10% VAT operations (base + VAT)	7xxxx → 44572x	Reduced rate operations
B3	Répartition 5,5% (base + taxe)	5.5% VAT operations (base + VAT)	7xxxx → 44573x	Reduced rate operations
B4	Répartition 2,1% (base + taxe)	2.1% VAT operations (base + VAT)	7xxxx → 44574x	Reduced rate operations

A. Opérations intracommunautaires (Intra-EU Operations)

CA-3 Line	Label	Description	PCG Accounts	Form Mapping
05	Livraisons intracommunautaires (B2B)	Intra-EU sales to businesses (no French VAT)	7xxxx (EU sales)	Base HT only, no VAT
06	Prestations intracommunautaires (B2B)	Intra-EU services to businesses (no French VAT)	7xxxx (EU services)	Base HT only, no VAT
B2C	Ventes B2C intracommunautaires	Intra-EU sales to individuals (French VAT)	7xxxx → 4457xx	Normal French VAT rules

B. TVA due (VAT Due)

CA-3 Line	Label	Description	PCG Accounts	Form Mapping
17	TVA due au titre des acquisitions intracommunautaires	VAT due on intra-EU acquisitions (autoliquidation)	4452xxx (TVA due intracom)	Reverse charge VAT

C. TVA déductible (Deductible VAT)

CA-3 Line	Label	Description	PCG Accounts	Form Mapping
20	TVA déductible sur immobilisations	Deductible VAT on capital goods	44562x	Fixed assets VAT
21	TVA déductible sur autres biens et services	Deductible VAT on other goods and services	44566x	Operating expenses VAT

D. Résultat (Result)

CA-3 Line	Label	Description	PCG Accounts	Form Mapping
22	Crédit de TVA reportable	VAT credit to carry forward	445670	If deductible > due
28	TVA nette à payer	Net VAT to pay	445510	If due > deductible
29	Crédit de TVA à reporter ou remboursement	VAT credit to carry forward or refund	445670	Credit amount

EU Transaction Handling

1️⃣ Incoming Invoices (EU Purchases)

• Scenario: Supplier in another EU country invoices HT (no VAT)
• French Treatment: Self-assess VAT (autoliquidation)
• Accounting: Book both VAT due (4452xxx) and VAT deductible (44566x/44562x)
• Net Effect: Zero if fully deductible
• CA-3 Impact: Line 17 (VAT due) and Lines 20/21 (VAT deductible)

2️⃣ Outgoing Invoices (EU Sales)

Case A: B2B Intra-EU Sales (Business Customers)

• Invoice Treatment: No French VAT charged
• Invoice Text: "Exonération de TVA, article 138" (goods) or "Autoliquidation par le preneur, article 196" (services)
• Accounting: No 4457xxx VAT output booked
• CA-3 Declaration: Lines 05/06 (base HT only, no VAT)
• Additional: DEB/DES declarations required

Case B: B2C Intra-EU Sales (Individual Customers)

• Under OSS Threshold (€10,000): Charge French VAT (4457xx)
• Over OSS Threshold: Register for OSS/IOSS, charge customer's country VAT rate
• CA-3 Declaration: Normal French VAT rules or OSS portal

Case C: Special Reverse Charge Cases

• Construction Services: Subcontractor invoices HT, contractor self-assesses
• Energy Products: Specific reverse charge rules
• Accounting: Similar to EU purchases (4452xxx + 4456xx)

3️⃣ DEB/DES Integration

• DEB (Déclaration d'échanges de biens): Goods movement declarations
• DES (Déclaration d'échanges de services): Services movement declarations
• Integration: Link CA-3 lines 05/06 with DEB/DES data
• Validation: Cross-check amounts between CA-3 and DEB/DES

Technical Requirements

Database Structure

• Main table: llx_declarationtva_config - Stores PCG account mappings
• Declaration table: llx_declarationtva_declarations - Stores generated declarations
• Period table: llx_declarationtva_periods - Manages declaration periods

Key Features

1. PCG Account Configuration: Setup page to map PCG accounts to CA-3 boxes
2. Period Management: Handle quarterly/monthly declaration periods
3. Data Extraction: Query Dolibarr accounting data based on PCG mappings
4. Declaration Generation: Create CA-3 format declarations
5. Export Functionality: Export to various formats (PDF, XML, CSV)
6. Bilingual Interface: French and English language support

Advanced Features

7. Draft System: All declarations start as drafts with detailed account breakdowns
8. Validation Workflow: User validation with detailed verification
9. Accounting Integration: Automatic journal entry generation for validated declarations
10. Audit Trail: Complete history of changes and validations
11. Comparison Tools: Compare declarations across periods
12. Exception Handling: Flag unusual amounts or missing data
13. Multi-Entity Support: Handle multiple companies/entities
14. Automated Calculations: Real-time calculation updates
15. Document Management: Attach supporting documents
16. Notification System: Email alerts for deadlines and status changes
17. Reporting Dashboard: Visual analytics and trends
18. Backup/Restore: Declaration data backup and recovery
19. Integration APIs: Connect with external tax systems
20. Mobile Support: Responsive design for mobile access

File Structure

declarationtva/
├── admin/
│   ├── setup.php (Enhanced with PCG configuration)
│   └── about.php
├── core/
│   ├── modules/modDeclarationTVA.class.php
│   └── class/
│       ├── declarationtva.class.php
│       ├── declarationtva_config.class.php
│       └── declarationtva_period.class.php
├── lib/
│   └── declarationtva.lib.php
├── langs/
│   ├── en_US/declarationtva.lang
│   └── fr_FR/declarationtva.lang
├── sql/
│   └── dolibarr_allversions.sql
├── templates/
│   └── declarationtva/
│       ├── ca3_form.tpl
│       └── ca3_pdf.tpl
└── declarationtvaindex.php

Development Phases

Phase 1: Foundation (Week 1-2)

• Database schema design and implementation
• Core class structure
• Basic module setup and configuration

Phase 2: Configuration Interface (Week 3-4)

• PCG account mapping interface
• Period management
• User permissions and access control

Phase 3: Data Processing (Week 5-6)

• Accounting data extraction
• CA-3 calculation logic
• Data validation and error handling

Phase 4: User Interface (Week 7-8)

• Main declaration interface
• Period selection and management
• Declaration preview and editing

Phase 5: Export and Reporting (Week 9-10)

• PDF generation
• XML export for tax authorities
• CSV export for analysis

Phase 6: Testing and Documentation (Week 11-12)

• Unit testing
• Integration testing
• User documentation
• French tax compliance validation

Success Criteria

1. Functional Requirements

   • Complete CA-3 form generation
   • Accurate PCG account mapping
   • Proper period management
   • Export functionality

2. Technical Requirements

   • Dolibarr compatibility (v19+)
   • Bilingual interface (FR/EN)
   • Database integrity
   • Performance optimization

3. Compliance Requirements

   • French tax authority format compliance
   • Data accuracy and validation
   • Audit trail maintenance

Risk Mitigation

1. Tax Compliance: Regular validation with French tax requirements
2. Data Accuracy: Comprehensive testing with real accounting data
3. Performance: Optimization for large datasets
4. User Experience: Intuitive interface for non-technical users

Future Enhancements

1. Automated Submission: Direct submission to tax authorities
2. Advanced Analytics: VAT analysis and reporting
3. Multi-Entity Support: Support for multiple companies
4. Integration: Enhanced integration with other Dolibarr modules