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 (Notice 4722 - 3310-CA3-SD)

A. Opérations imposables (Taxable Operations) - Notice 4722

CA-3 Line	Label	Description	PCG Accounts
A1	Montant HT des opérations imposables normales	HT amount of all taxable operations that form normal sales (goods + services taxable in France at 20%, 10%, 5,5%, 2,1%)	Sales: 7xxxx; VAT: 44571x / 44572x / 44573x / 44574x
A2	Montant HT des opérations imposables spéciales	HT amount of special taxable operations not part of ordinary turnover (e.g. cessions d'immobilisations, livraisons à soi-même)	775xxx (gains on disposal), 72xxx (production immobilisée), VAT: 44571x
A3	Montant HT des services achetés à des prestataires non établis	HT amount of services purchased from providers not established in France but taxable in France (reverse charge for foreign services)	6xxxx (services purchased), 4452xxx (TVA due autoliquidée)
A4	Montant HT des importations imposables en France	HT amount of imports taxable in France (non-EU), excluding petroleum products	6xxxx / 2xxxx purchases or assets; VAT: 4452xxx (import VAT)
A5	Montant HT des opérations à la sortie d'un régime suspensif	HT amount of taxable operations at exit from a suspensive fiscal regime (customs regimes, free zones, etc.)	Specific 6xxxx/2xxxx depending on goods; VAT: 4452xxx

B. Décompte de la TVA due (VAT Due Calculation) - Notice 4722

CA-3 Line	Label	Description	PCG Accounts
08	TVA due au taux de 20%	VAT amounts due, calculated on A1/A2 bases at 20% rate	44571x (TVA collectée à 20%)
09	TVA due au taux de 10%	VAT amounts due, calculated on A1/A2 bases at 10% rate	44572x (TVA collectée à 10%)
9B	TVA due aux taux réduits (5,5% et 2,1%)	VAT amounts due, calculated on A1/A2 bases at reduced rates (5,5% and 2,1%)	44573x (5,5%) / 44574x (2,1%) (TVA collectée aux taux réduits)
17	TVA due au titre des acquisitions intracommunautaires	VAT due on intra-EU acquisitions (autoliquidation)	4452xxx (TVA due intracommunautaire)

C. Décompte de la TVA déductible (Deductible VAT Calculation) - Notice 4722

CA-3 Line	Label	Description	PCG Accounts
20	TVA déductible sur immobilisations	Deductible VAT on capital goods (fixed assets)	44562x (TVA déductible sur immobilisations)
21	TVA déductible sur autres biens et services	Deductible VAT on other goods and services (operating expenses)	44566x (TVA déductible sur autres biens et services)
22	TVA déductible sur importations	Deductible VAT on imports	44566x / 44562x (TVA déductible sur importations)

D. Résultat (Result) - Notice 4722

CA-3 Line	Label	Description	PCG Accounts
25	TVA brute due (Total TVA due)	Total VAT due (sum of all VAT due amounts)	Sum of 08 + 09 + 9B + 17
26	TVA déductible totale (Total deductible VAT)	Total deductible VAT (sum of all deductible VAT amounts)	Sum of 20 + 21 + 22
28	TVA nette à payer	Net VAT to pay (if total due > total deductible)	445510 (État - TVA à décaisser)
29	Crédit de TVA à reporter ou remboursement	VAT credit to carry forward or refund (if total deductible > total due)	445670 (État - Crédit de TVA à reporter ou rembourser)

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

Core Tables

• llx_declarationtva_config: Module configuration and settings
• llx_declarationtva_account_mappings: PCG account mappings for CA-3 lines
• llx_declarationtva_periods: Declaration period management
• llx_declarationtva_declarations: Main declarations storage
• llx_declarationtva_ca3_lines: CA-3 form lines data
• llx_declarationtva_account_details: Detailed account breakdown

EU Transaction Tables

• llx_declarationtva_eu_suppliers: EU supplier configuration
• llx_declarationtva_eu_transactions: EU transaction tracking

Workflow Integration Tables

• llx_declarationtva_workflow_log: Workflow triggers and automation
• llx_declarationtva_audit_trail: Complete audit trail
• llx_declarationtva_compliance: Compliance validation results

Export and Integration Tables

• llx_declarationtva_exports: Export history and tracking

Performance Features

• Comprehensive Indexing: Optimized for large datasets
• Foreign Key Constraints: Data integrity enforcement
• Reporting Views: Pre-built views for analytics
• Multi-Entity Support: Full entity isolation

PCG Account Mapping System

Multiple Account Selection

Each CA-3 line can be mapped to multiple PCG accounts from Dolibarr's existing chart of accounts:

• Account Selection Interface: Multi-select dropdown from Dolibarr's llx_accounting_account table
• Account Validation: Real-time validation against existing chart of accounts
• Account Grouping: Group multiple accounts by CA-3 line
• Account Weighting: Optional weighting for account importance
• Account Filtering: Filter accounts by type (7xxxx, 4457xx, 4456xx, etc.)

Account Mapping Structure

-- PCG Account Mappings Table
llx_declarationtva_account_mappings:
- id (Primary Key)
- ca3_line (VARCHAR) -- A1, A2, B1, B2, B3, B4, 05, 06, 17, 20, 21, 22, 28, 29
- account_code (VARCHAR) -- PCG account code from llx_accounting_account
- account_label (VARCHAR) -- Account description
- vat_rate (DECIMAL) -- VAT rate (20%, 10%, 5.5%, 2.1%, 0%)
- account_type (VARCHAR) -- base, vat_collected, vat_deductible, vat_due
- is_active (BOOLEAN) -- Enable/disable this mapping
- weight (DECIMAL) -- Optional weighting (default 1.0)
- created_date (DATETIME)
- modified_date (DATETIME)

Account Selection Interface

• Multi-Select Dropdown: Select multiple accounts for each CA-3 line
• Account Search: Search accounts by code or description
• Account Filtering: Filter by account type (7xxxx, 4457xx, etc.)
• Account Preview: Show account details and current balances
• Account Validation: Ensure accounts exist and are active
• Bulk Operations: Add/remove multiple accounts at once

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

Dolibarr Workflow Integration

21. Autoliquidation Automation: Automatic EU VAT autoliquidation on invoice transfer
22. Hook System Integration: Extend Dolibarr core functionality
23. Invoice Processing Hooks: Intercept invoice accounting transfers
24. Supplier Invoice Automation: Auto-detect EU suppliers and apply autoliquidation
25. Customer Invoice Automation: Auto-apply EU transaction rules
26. Accounting Entry Automation: Generate VAT entries during transfer to accounting
27. Workflow Triggers: Automatic VAT processing based on invoice status
28. Custom Fields Integration: Extend invoices with VAT-specific fields
29. Status Change Automation: Trigger VAT processing on invoice validation
30. Batch Processing: Handle multiple invoices for VAT processing

Advanced Analytics & Intelligence

31. VAT Forecasting: Predict future VAT obligations based on historical data
32. Anomaly Detection: AI-powered detection of unusual VAT patterns
33. Cash Flow Impact: Calculate VAT impact on cash flow projections
34. VAT Optimization: Suggest strategies to minimize VAT payments
35. Trend Analysis: Identify VAT trends and seasonal patterns
36. Benchmarking: Compare VAT performance against industry standards
37. Risk Assessment: Flag potential VAT compliance risks
38. Predictive Alerts: Early warning system for VAT issues

Tax Authority Integration

39. Direct Submission: Submit CA-3 declarations directly to French tax authorities
40. API Integration: Connect with French tax authority APIs
41. Real-time Validation: Validate declarations against tax authority systems
42. Electronic Signatures: Digital signature for declaration submission
43. Receipt Management: Store and manage tax authority receipts
44. Status Tracking: Track declaration status with tax authorities
45. Amendment Handling: Process declaration amendments and corrections
46. Payment Integration: Direct payment of VAT obligations

Advanced Reporting & Compliance

47. Multi-Period Analysis: Compare VAT across multiple periods
48. VAT Reconciliation: Reconcile VAT with general ledger
49. Audit Trail: Complete audit trail for tax authorities
50. Compliance Dashboard: Real-time compliance status monitoring
51. Regulatory Updates: Automatic updates for tax law changes
52. Penalty Calculation: Calculate potential penalties for late submissions
53. Deadline Management: Automated deadline tracking and reminders
54. Document Generation: Auto-generate supporting documentation

Business Intelligence

55. VAT Analytics: Deep insights into VAT patterns and trends
56. Cost Analysis: Analyze VAT impact on business costs
57. Profitability Impact: Show how VAT affects product profitability
58. Customer VAT Analysis: Analyze VAT by customer segments
59. Supplier VAT Analysis: Analyze VAT by supplier categories
60. Geographic Analysis: VAT analysis by geographic regions
61. Product Analysis: VAT analysis by product categories
62. Seasonal Analysis: Identify seasonal VAT patterns

Integration & Connectivity

63. ERP Integration: Connect with other ERP systems
64. Banking Integration: Direct bank account integration for VAT payments
65. Accounting Software: Integration with other accounting software
66. CRM Integration: Connect with customer relationship management
67. E-commerce Integration: Connect with e-commerce platforms
68. API Gateway: Centralized API for external integrations
69. Webhook Support: Real-time notifications to external systems
70. Data Synchronization: Sync data across multiple systems

Dolibarr Hook Integration

Available Hooks for VAT Automation

• invoice_validate: Trigger when invoice is validated
• invoice_accountancy_transfer: Trigger when invoice is transferred to accounting
• supplier_invoice_validate: Trigger when supplier invoice is validated
• supplier_invoice_accountancy_transfer: Trigger when supplier invoice is transferred
• invoice_paid: Trigger when invoice is marked as paid
• invoice_unpaid: Trigger when invoice is marked as unpaid
• invoice_cancel: Trigger when invoice is cancelled

Automation Workflow

1. Invoice Creation: User creates supplier invoice from EU supplier
2. Hook Trigger: supplier_invoice_validate hook fires
3. EU Detection: Module checks if supplier is EU-based
4. Autoliquidation: Automatically creates VAT due (4452xxx) and VAT deductible (4456xx) entries
5. Accounting Transfer: When transferred to accounting, entries are already created
6. CA-3 Integration: Entries automatically appear in CA-3 calculations

Custom Fields for VAT Processing

• EU Supplier Flag: Mark suppliers as EU-based
• VAT Treatment: Specify autoliquidation vs normal VAT
• Transaction Type: B2B, B2C, special cases
• OSS Threshold: Track B2C sales thresholds
• DEB/DES Required: Flag invoices requiring exchange declarations

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
│   └── triggers/
│       ├── interface_99_modDeclarationTVA_DeclarationTVATrigger.class.php
│       └── action_99_modDeclarationTVA_DeclarationTVAAction.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