DeclarationTVA/CA3_FIELD_NAMING.md

# CA-3 Fillable PDF Field Naming Convention

This document provides the complete field naming convention for creating a fillable CA-3 PDF template that integrates seamlessly with the DeclarationTVA module.

## ⚠️ **IMPORTANT: Use Text Fields Only**

**All fields should be created as TEXT fields in your PDF template.** The module will handle the formatting of amounts, dates, and other data automatically.

## 📝 **Font Settings**

**The module automatically applies Courier New 9pt formatting to all form fields** for professional, official document appearance. No additional font configuration is needed.

## 🎯 **Field Naming Strategy**

### **📋 Company Information Fields**
```
company_name
company_address
company_city
company_postal_code
company_siret
company_vat_number
declaration_period_start
declaration_period_end
declaration_number
```

### **📊 Section A: Opérations imposables**
```
A1_amount
A2_amount
A3_amount
A4_amount
A5_amount
```

### **📊 Section B: TVA due (Base + VAT columns)**
```
B08_base_amount
B08_vat_amount
B09_base_amount
B09_vat_amount
B9B_base_amount
B9B_vat_amount
B17_amount
```

### **📊 Section C: TVA déductible**
```
C20_amount
C21_amount
C22_amount
```

### **📊 Section F: Intracom Acquisitions**
```
F1_amount
F2_amount
```

### **📊 Section D: Résultat (Calculated)**
```
D25_amount
D26_amount
DTD_amount
D28_amount
D29_amount
```

### **📊 Subtotals (For Reference)**
```
subtotal_B16_amount    # Subtotal of B08+B09+B9B VAT
subtotal_C23_amount    # Subtotal of C20+C21+C22
```

### **📊 Grand Totals**
```
total_vat_collected
total_vat_deductible
net_vat_due
vat_credit
```

## 📋 **Complete Field List for PDF Creation**

### **Company Information Section**
| Field Name | Description | Type | Format |
|------------|-------------|------|--------|
| `company_name` | Company name | Text | - |
| `company_address` | Company address | Text | - |
| `company_city` | City | Text | - |
| `company_postal_code` | Postal code | Text | - |
| `company_siret` | SIRET number | Text | - |
| `declaration_period_start` | Period start date | Date | DD/MM/YYYY |
| `declaration_period_end` | Period end date | Date | DD/MM/YYYY |
| `declaration_number` | Declaration number | Text | - |

### **Section A: Opérations imposables**
| Field Name | Description | Type | Format |
|------------|-------------|------|--------|
| `A1_amount` | Line A1 amount | Currency | € 0.00 |
| `A2_amount` | Line A2 amount | Currency | € 0.00 |
| `A3_amount` | Line A3 amount | Currency | € 0.00 |
| `A4_amount` | Line A4 amount | Currency | € 0.00 |
| `A5_amount` | Line A5 amount | Currency | € 0.00 |

### **Section B: TVA due**
| Field Name | Description | Type | Format |
|------------|-------------|------|--------|
| `B08_base_amount` | Line 08 base amount | Currency | € 0.00 |
| `B08_vat_amount` | Line 08 VAT amount | Currency | € 0.00 |
| `B09_base_amount` | Line 09 base amount | Currency | € 0.00 |
| `B09_vat_amount` | Line 09 VAT amount | Currency | € 0.00 |
| `B9B_base_amount` | Line 9B base amount | Currency | € 0.00 |
| `B9B_vat_amount` | Line 9B VAT amount | Currency | € 0.00 |
| `B17_amount` | Line 17 amount | Currency | € 0.00 |

### **Section C: TVA déductible**
| Field Name | Description | Type | Format |
|------------|-------------|------|--------|
| `C20_amount` | Line 20 amount | Currency | € 0.00 |
| `C21_amount` | Line 21 amount | Currency | € 0.00 |
| `C22_amount` | Line 22 amount | Currency | € 0.00 |

### **Section F: Intracom Acquisitions**
| Field Name | Description | Type | Format |
|------------|-------------|------|--------|
| `F1_amount` | Line F1 amount | Currency | € 0.00 |
| `F2_amount` | Line F2 amount | Currency | € 0.00 |

### **Section D: Résultat (Calculated)**
| Field Name | Description | Type | Format |
|------------|-------------|------|--------|
| `D25_amount` | Line 25 amount | Currency | € 0.00 |
| `D26_amount` | Line 26 amount | Currency | € 0.00 |
| `DTD_amount` | Line TD amount | Currency | € 0.00 |
| `D28_amount` | Line 28 amount | Currency | € 0.00 |
| `D29_amount` | Line 29 amount | Currency | € 0.00 |

### **Subtotals (For Reference)**
| Field Name | Description | Type | Format |
|------------|-------------|------|--------|
| `subtotal_B16_amount` | Subtotal B08+B09+B9B VAT | Currency | € 0.00 |
| `subtotal_C23_amount` | Subtotal C20+C21+C22 | Currency | € 0.00 |

### **Grand Totals**
| Field Name | Description | Type | Format |
|------------|-------------|------|--------|
| `total_vat_collected` | Total VAT collected | Currency | € 0.00 |
| `total_vat_deductible` | Total VAT deductible | Currency | € 0.00 |
| `net_vat_due` | Net VAT due | Currency | € 0.00 |
| `vat_credit` | VAT credit | Currency | € 0.00 |

## 🔧 **Integration Code Example**

```php
// In DeclarationTVA_PDF::fillPDFTemplate method
$field_mapping = array(
    // Company information
    'company_name' => $company->name,
    'company_address' => $company->address,
    'company_city' => $company->town,
    'company_postal_code' => $company->zip,
    'company_siret' => $company->idprof2, // SIRET
    'declaration_period_start' => dol_print_date($declaration->start_date, 'day'),
    'declaration_period_end' => dol_print_date($declaration->end_date, 'day'),
    'declaration_number' => $declaration->declaration_number,
    
    // Section A
    'A1_amount' => $ca3_data['A1']['vat_amount'],
    'A2_amount' => $ca3_data['A2']['vat_amount'],
    'A3_amount' => $ca3_data['A3']['vat_amount'],
    'A4_amount' => $ca3_data['A4']['vat_amount'],
    'A5_amount' => $ca3_data['A5']['vat_amount'],
    
    // Section B
    'B08_base_amount' => $ca3_data['08']['base_amount'],
    'B08_vat_amount' => $ca3_data['08']['vat_amount'],
    'B09_base_amount' => $ca3_data['09']['base_amount'],
    'B09_vat_amount' => $ca3_data['09']['vat_amount'],
    'B9B_base_amount' => $ca3_data['9B']['base_amount'],
    'B9B_vat_amount' => $ca3_data['9B']['vat_amount'],
    'B17_amount' => $ca3_data['17']['vat_amount'],
    
    // Section C
    'C20_amount' => $ca3_data['20']['vat_amount'],
    'C21_amount' => $ca3_data['21']['vat_amount'],
    'C22_amount' => $ca3_data['22']['vat_amount'],
    
    // Section D
    'D25_amount' => $ca3_data['25']['vat_amount'],
    'D26_amount' => $ca3_data['26']['vat_amount'],
    'DTD_amount' => $ca3_data['TD']['vat_amount'],
    'D28_amount' => $ca3_data['28']['vat_amount'],
    'D29_amount' => $ca3_data['29']['vat_amount'],
    
    // Subtotals
    'subtotal_B16_amount' => $ca3_data['16']['vat_amount'],
    'subtotal_C23_amount' => $ca3_data['23']['vat_amount'],
    
    // Grand totals
    'total_vat_collected' => $declaration->total_vat_collected,
    'total_vat_deductible' => $declaration->total_vat_deductible,
    'net_vat_due' => $declaration->net_vat_due,
    'vat_credit' => $declaration->vat_credit,
);
```

## 🎯 **Field Properties Recommendations**

### **Text Fields**
- **Type**: Text field
- **Alignment**: Left-aligned
- **Font**: Arial, 10pt
- **Background**: White

### **Amount Fields**
- **Type**: Text field with currency format
- **Alignment**: Right-aligned
- **Font**: Arial, 10pt, Bold
- **Format**: € 0.00
- **Background**: White

### **Date Fields**
- **Type**: Text field
- **Format**: DD/MM/YYYY
- **Alignment**: Center
- **Font**: Arial, 10pt

### **Read-Only Fields (Calculated)**
- **Type**: Text field
- **Read-only**: Yes
- **Background**: Light gray (#F5F5F5)
- **Font**: Arial, 10pt, Bold

## 📋 **PDF Creation Checklist**

- [ ] Create fillable PDF with all field names listed above
- [ ] Set proper field types and formats
- [ ] Test field tab order
- [ ] Verify field positioning matches official form
- [ ] Test PDF form filling with sample data
- [ ] Validate field names match exactly (case-sensitive)
- [ ] Ensure all fields are properly named and positioned
- [ ] Test PDF generation with module integration

## 🚀 **Benefits of This Naming Convention**

- ✅ **Easy Integration**: Direct mapping to module data
- ✅ **Maintainable**: Clear, logical field names
- ✅ **Extensible**: Easy to add new fields
- ✅ **Professional**: Consistent naming across all fields
- ✅ **Future-Proof**: Compatible with form updates

## 📝 **Notes**

- All field names are **case-sensitive**
- Field names must **exactly match** the convention above
- Use **underscores** for multi-word field names
- Keep field names **descriptive** but **concise**
- Test thoroughly with the module integration

This naming convention ensures seamless integration between the fillable PDF and the DeclarationTVA module!