# Mappage des champs ZUGFeRD + Code QR suisse

## Aperçu

Lors du traitement des factures PDF contenant à la fois des données XML ZUGFeRD et un code QR suisse (Swiss QR Code), DocBits extrait les données des deux sources et les fusionne intelligemment.

## Comment ça marche

1. **Extraction XML ZUGFeRD** - DocBits extrait d'abord les champs du XML ZUGFeRD intégré
2. **Détection du Swiss QR Code** - Le barcode détecte et analyse les codes QR suisses
3. **Fusion Intelligente (Smart Merge)** - Les champs vides sont remplis à partir des données Swiss QR (les champs avec des valeurs sont préservés)
4. **Piste d'audit (Audit Trail)** - Les données complètes du code QR sont stockées dans `qr_code_data` pour vérification

## Tableau de Mappage des Champs

### Mappage des Champs Swiss QR Code → DocBits

| Champ Swiss QR        | Champ DocBits                         | Description                             |
| --------------------- | ------------------------------------- | --------------------------------------- |
| IBAN                  | `supplier_iban`                       | IBAN du créancier (ex. CH9300762011...) |
| Amount                | `total_amount`                        | Montant du paiement (ex. 1234.56)       |
| Currency              | `currency`                            | Code devise (CHF ou EUR)                |
| Reference             | `payment_reference` / `esr_reference` | Référence QR ou numéro BVR (ESR)        |
| Creditor.Name         | `supplier_name`                       | Nom de la société fournisseur           |
| Creditor.AddressLine1 | `supplier_address`                    | Adresse (rue)                           |
| Creditor.PostalCode   | `supplier_plz`                        | Code postal                             |
| Creditor.City         | `supplier_city`                       | Ville                                   |
| Creditor.Country      | `supplier_country`                    | Code pays (CH)                          |
| Debtor.Name           | `company_name`                        | Nom de la société destinataire          |
| Debtor.AddressLine1   | `company_street`                      | Adresse du destinataire                 |
| Debtor.PostalCode     | `company_plz`                         | Code postal du destinataire             |
| Debtor.City           | `company_city`                        | Ville du destinataire                   |

## Exemple : Traitement d'une facture type

### Document d'entrée

* **PDF** : Facture avec XML ZUGFeRD 1.0 intégré + code-barres Swiss QR Code

### Données extraites du Swiss QR Code

```json
{
  "supplier_iban": "CH9300762011623852957",
  "amount_to_pay": 1234.56,
  "currency": "CHF",
  "esr_reference": "210000000003139471430009017",
  "supplier_name": "Sample Company GmbH",
  "supplier": {
    "name": "Sample Company GmbH",
    "address_line_1": "Musterstrasse",
    "address_line_2": "123",
    "postal_code": "8000",
    "city": "Zürich",
    "country": "CH"
  },
  "recipient": {
    "name": "Demo Customer AG",
    "address_line_1": "Beispielweg 45",
    "postal_code": "3000",
    "city": "Bern",
    "country": "CH"
  }
}
```

### Résultats de l'extraction des champs

| Champ               | Valeur                      | Source      | Méthode   |
| ------------------- | --------------------------- | ----------- | --------- |
| `supplier_iban`     | CH9300762011623852957       | ZUGFeRD XML | ED        |
| `total_amount`      | 1234.56                     | ZUGFeRD XML | ED        |
| `currency`          | CHF                         | ZUGFeRD XML | ED        |
| `supplier_name`     | Sample Company GmbH         | ZUGFeRD XML | ED        |
| `supplier_address`  | Musterstrasse 123           | ZUGFeRD XML | ED        |
| `payment_reference` | 210000000003139471430009017 | Swiss QR    | SWISS\_QR |
| `supplier_plz`      | 8000                        | Swiss QR    | SWISS\_QR |
| `supplier_city`     | Zürich                      | Swiss QR    | SWISS\_QR |

## Méthodes d'extraction

| Code Méthode  | Description                                          |
| ------------- | ---------------------------------------------------- |
| **ED**        | Document Électronique (ZUGFeRD/XRechnung/PEPPOL XML) |
| **SWISS\_QR** | Extraction de code-barres Swiss QR Code              |
| **OCR**       | Reconnaissance Optique de Caractères                 |
| **ML**        | Extraction par Machine Learning                      |

## Priorité de fusion

1. **ZUGFeRD XML** a la priorité la plus élevée (données structurées et fiables)
2. **Swiss QR Code** remplit les champs vides (garanti précis pour les données de paiement)
3. **OCR/ML** utilisé pour les champs absents des sources électroniques

## Versions de Swiss QR Code prises en charge

* Format Swiss QR Bill (ISO 20022)
* Format QR-IBAN (commence par 30, 31)
* Format IBAN standard
* Avec/sans référence structurée (QRR, SCOR)

## Exigence de version

Cette fonctionnalité nécessite **api version 10.95.6** et **barcode version 1.0.5** ou supérieure.

### Versions des composants (Environnement Dev)

| Composant | Version | Description                                                     |
| --------- | ------- | --------------------------------------------------------------- |
| `api`     | 10.95.6 | API principale avec prise en charge de l'extraction ZUGFeRD 1.0 |
| `barcode` | 1.0.5   | Détection et analyse du Swiss QR Code                           |
| `Auth`    | 1.48.8  | Service d'authentification                                      |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-fr.docbits.com/administration-and-setup/settings/global-settings/document-types/edi/zugferd-and-swiss-qr-merge.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.