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

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