Convertisseur CII UBL

=Introduction=
L'objet du '''convertisseur e-Invoicing ''' est de convertir un fichier 'XML Pivot' (format de données facilitant l'intégration de Efalia Compose) en flux XML CII (pour la création d'un pdf factur-X) ou UBL.<br> 
Le convertisseur prend en entrée un flux XML Pivot soit fini, c'est à dire avec tous les informations nécessaires à la génération du CII ou UBL (recommandé) ou soit donne la possibilité au développeur de forcer la valeur d'un champ (soit par une simple valeur en dur ou soit via un calcul)

=Prérequis=

*La clé Connect doit être activée sur le serveur Efalia Compose
*Compatible avec la version Onyx sous Windows et Linux (Version 10.6.0 minimum)
*Les dates doivent être sous la forme YYYY-MM-DD (A la charge du programme générant le XML Pivot de les formatter comme cela)
*Les numériques ne doive pas avoir de séparateur de millier et doivent avoir un point comme séparateur de décimales (exemple : 11200.10)
*Etre informé des normes de facturation électronique (CII et UBL)
*Avoir un profil assez technique et connaitre les flux XML

=Principe de fonctionnement=

Le flux XML Pivot avec ou sans toutes les informations nécessaires est donnée à l'entrée du connecteur. Le connecteur prend en paramètre un fichier de paramétrage (pouvant être vide si besoin), le type de sortie (ubl ou factur-x) et le nom du fichier CII ou UBL en sortie.

*Sortie CII (pour factur-X)

"C:/MAPPING/M-Processing Server/Applications/maprunrpt" -rptname:EINVOICING -param:DB.data_file="C:\work\out_pivot.xml" -param:DB.param_file="C:\work\edi_param.xml" "-param:DB.output-type='''factur-x'''" -outfile:"C:\work\out_cii.xml"

*Sortie UBL

"C:/MAPPING/M-Processing Server/Applications/maprunrpt" -rptname:EINVOICING -param:DB.data_file="C:\work\out_pivot.xml" -param:DB.param_file="C:\work\edi_param.xml" "-param:DB.output-type='''ubl'''" -outfile:"C:\work\out_ubl.xml"

(la valeur par défaut de DB.output-type est factur-x)

=Fichier de paramétrage=
Dans l'idéal, le flux de donnée en entrée doit contenir toutes les informations nécessaires à la génération du fichier e-Invoicing (UBL ou CII).
Cependant, il est courant de traiter des flux non exhaustifs. 
Par conséquent, il est possible (dans certaines mesures) d'initaliser un champ avec une valeur (calculée ou en dur)

Pour ce faire, nous utiliserons le fichier de paramétrage.

==Initialisation d'un champ (hors liste) avec une valeur en dur==
Si par exemple dans le flux de données (XML Pivot), le champ dy typage de document (BT-3) est absent, on peut l'initialiser avec une valeur :

 <param>
  <field id="BT-3">380</field>
 </param>

Sa valeur sera alors 380 dans le flux CII ou UBL en sortie.

<u>Remarque</u> : Si BT-3 était présent mais avec une nouvelle valeur, alors sa nouvelle valeur sera 380.
<u>Remarque</u> : Cette fonctionnalité est disponible uniquement pour les champs présents au niveau <doc>. Il existe cependant l'élément <translations> qui permet de faire la même chose avec les champs de listes. (voir section plus bas)

==Initialisation d'un champ avec la valeur d'un autre champ==
Il est également possible d'initialiser ou de surcharger la valeur d'un champ avec la valeur d'un autre champ.

Par exemple, si la date d'échéance (BT-9) est absent du flux en entrée alors on peut l'initialiser avec la date d'émission de la facture (BT-2)
 
 <param>
  <field id="BT-9" xpath="/data/doc/field[@id='BT-2']"
 </param>

Dans le fichier UBL ou CII, la valeur de BT-9 sera la meme que le champ BT-2.


==Surcharger le chemin d'une liste==
Il est également possible de surcharger la valeur par défaut du chemin d'une liste. (liste de produits, liste de TVA ou autres)

Par exemple, si la liste des produits n'est pas /data/doc/list[@id='BG-25'], alors il est possible de lui donner un autre nom et chemin :

 <param>
  <list id="BG-25" xpath="/*/doc/list[@id='produits']"/>
  <list id="BG-23" xpath="/*/doc/list[@id='tvas']"/>
 </param>

Dans cet exemple, les produits (BG-25) sont localisés dans la liste "produits" et la liste de TVAs (BG-23) dans la liste "tvas" et tout cela au niveau <doc>

==Champs recalculables==
En V1.00 du connecteur EINVOICING, nous avons un champ qui est recalculable au besoin.
Ce champ est le BT-115 (Montant à payer)
Ce champ, à la demande, peut prendre une valeur automatiquement recalculée avec le BT-112, BT-113 et BT-114 selon la règle de gestion appropriée, soit : BT-115 = BT-112 - BT-113 + BT-114 .<br>
Pour demander son recalcul, il faut indiquer cela dans le fichier de paramétrage : <br>
 <field id="BT-115" calculate="true"/>

<u>Remarque</u> : La valeur par défaut est à "false", ce qui veut dire qu'on prend la valeur du fichier en entrée.

==Gestion des taxes==
La facturation électronique impose l'utilisation de code suivant les différents taux et type de de TVA possibles. Dans le flux en entrée, on peut éventuellement avoir non pas le code TVA comme attendu dans le flux CII ou UBL mais plutôt le taux de TVA en pourcentage ou autres.
Il faut alors faire une traduction entre la valeur présente dans le fichier en entrée et le Taux TVA ainsi que le Code TVA attendu par la norme CII et UBL .

Voici la liste des différents code de TVA attendus par la norme CII et UBL : 

 "Les entrées suivantes de l'UNTDID 5305 sont utilisées:
 S = Taux de TVA standard
 Z = Taux de TVA égal à 0
 E = Exempté de TVA
 AE = Autoliquidation de TVA
 K = Autoliquidation pour cause de livraison intracommunautaire
 G = Exempté de TVA pour Export hors UE
 O = Hors du périmètre d'application de la TVA
 L = Iles Canaries
 M = Ceuta et Mellila

Pour  traiter cela, nous utiliserons le bloc élément <taxes> du fichier de paramétrage.

===Exemple===

 <taxes>
  <codes>
   <value from="0" to="Z"/>
   <value from="1" to="S"/>
   <value from="2" to="S"/>
   <value from="3" to="S"/>
  </codes>
  <rates>
   <value from="0" to="0.00"/>
   <value from="1" to="20.00"/>
   <value from="2" to="8.50"/>
   <value from="3" to="4.00"/>
  </rates>		
 </taxes>

Les valeurs dans le "from" sont ceux récupérées dans le flux de donnée XML Pivot. Leurs correspondances "to" seront les valeurs retournées dans le fichier de sortie UBL ou CII.


==Table de correspondances de valeurs de listes==
A l'image de la gestion de taxes nécessitant la gestion de correspondances de valeurs entre une valeur et un code CII ou UBL, il peut parfois être utile de pouvoir donner une valeur à une valeur d'une liste (soit car celle-ci est absente ou soit car elle nécessite un recalcul)
Pour ce faire, nous avons la possibilité d'utiliser l'élément bloc <translations> du fichier de paramétrage.

===Exemple===

 <translations>
  <'''BT-129'''>
   <value from="" to="1.000"/>	
  </BT-129>
  <'''BT-146'''>
   <value from="*" to="calc()">
    <field op="" id="BT-148"/>
    <field op="-" id="BT-136"/>
   </value>
  </BT-146>
  <BT-131>
   <value from="*" to="calc()">
    <field op="" id="'''BT-146'''"/>
    <field op="*" id="'''BT-129'''"/>
   </value>
  </BT-131>
 </translations>	

Dans cette exemple nous avons 3 recalculs personalisés :

*<u>Recalcul du BT-129 (quantité facturée)</u> :
Dans le cas où le "BT-129 ne serait pas présent dans le flux en entrée, on aurait en sortie la valeur "1.000"

*<u>Recalcul du BT-146(Prix HT de l’article (unitaire))</u> :
Dans ce cas là, BT-146 (prix net de l'article) sera égale à BT-148 (prix brut de l'article) - BT-136 (montant d'une remise hors TVA) et cela peu importe la valeur présente dans le flux en entrée

*<u>Recalcul du BT-131(montant net de ligne de facture)</u> :
Dans ce cas là, BT-131 (montant net de ligne de facture) sera égale à BT-146 (rix net de l'article) * BT-129 (quantité facturée) et cela peu importe la valeur présente dans le flux en entrée.
Les valeurs BT-129 et BT-146 seront les valeurs issues du bloc <translations> car le recalcul BT-129 et BT-146 ont été fait avant le recalcul du BT-131.
<u>Remarque</u> : L'ordre des éléments dans <translations> est, par conséquent, très important.

=Valeurs par défaut=
==Champs==
Dans le cas où l'information serait absente dans le flux de données en entrée et dans le fichier de paramétrage, alors les valeurs suivantes seraient utilisées par défaut :

{| class="wikitable"
|-
! Champs !! valeurs par défaut
|-
| BT-3 || 380
|-
| BT-5 || EUR
|-
| BT-9 || BT-2
|-
| BT-30-1 || 0002
|-
| BT-31-0 || (VA pour factur-X et VAT pour UBL)
|}

==Listes==

{| class="wikitable"
|-
! Listes!! Chemins par défaut
|-
| BG-1|| /data/doc/list[@id='BG-1']
|-
| BG-3|| /data/doc/list[@id='BG-3']
|-
| BG-17|| /data/doc/list[@id='BG-17']
|-
| BG-20|| /data/doc/list[@id='BG-20']
|-
| BG-21|| /data/doc/list[@id='BG-21']
|-
| BG-23|| /data/doc/list[@id='BG-23']
|-
| BG-24|| /data/doc/list[@id='BG-24']
|-
| BG-25|| /data/doc/list[@id='BG-25']
|-
| BG-27|| /data/doc/list[@id='BG-27']
|-
| BG-28|| /data/doc/list[@id='BG-28']
|-
| BG-32|| /data/doc/list[@id='BG-32']
|-
| BT-29-a|| /data/doc/list[@id='BT-29-a']
|-
| BT-29-b|| /data/doc/list[@id='BT-29-b']
|-
| BT-29-c|| /data/doc/list[@id='BT-29-c']
|-
|| BT-46-a|| /data/doc/list[@id='BT-46-a']
|-
| BT-46-b|| /data/doc/list[@id='BT-46-b']
|-
| BT-46-c|| /data/doc/list[@id='BT-46-c']
|-
| BT-29-a|| /data/doc/list[@id='BT-29-a']
|-
| BT-29-a|| /data/doc/list[@id='BT-29-a']
|-
| BT-60|| /data/doc/list[@id='BT-60']
|-
| BT-71|| /data/doc/list[@id='BT-71']
|-
| BT-127-00|| /data/doc/list[@id='BT-127-00']
|-
| BT-128|| /data/doc/list[@id='BT-128']
|-
| BT-158|| /data/doc/list[@id='BT-158']
|}

</u>remarque</u> : Tous ces champs et toutes ces listes peuvent être surchargés au niveau du fichier de paramétrage

=Exemple de flux XML Pivot=
==Flux complet==
Le flux suivant pourra être traité par le convertisseur avec un fichier de paramétrage vide 

====Fichier de paramétrage====
 
 <param/>
 
====Fichier de donnée XML Pivot====

 <nowiki><?xml version="1.0" encoding="UTF-8"?>
  <data>
   <doc type="FACTURE">		
   <!--id type of the invoice : Default :380 for commercial invoices  (Code de type de facture)-->
    <field id="BT-3">380</field>
    <!--Invoice date (Date d'émission facture initiale / facture rectificative) - YYYY-MM-DD-->
    <field id="BT-2">2022-11-19</field>
    <!--Invoice number (Numéro de facture)-->
    <field id="BT-1">0024657</field>
    <!--Currency code of the invoice : Default :EUR  (Code de devise de la facture)-->
    <field id="BT-5">EUR</field>
    <!--Total amount before VAT of the invoice (Montant total de la facture HT)-->
    <field id="BT-109">35600.00</field>
    <!--Total amount of VAT of the invoice (Montant total de TVA de la facture)-->
    <field id="BT-110">7120.00</field>
    <!--Total amount after VAT of the invoice  (Montant total de la Facture, avec la TVA.)-->
    <field id="BT-112">42720.00</field>
    <!--Already paid amount  (Montant déjà payé)-->
    <field id="BT-113">0.00</field>
    <!--Total amount to pay  (Montant à payer TTC)-->
    <field id="BT-115">42720.00</field>
    <!--Sum of all the amounts before VAT of the invoice on the line level  (Somme des montants nets des lignes de facture HT)-->
    <field id="BT-106">35600.00</field>
    <!--Due date  (Date d'échéance) - YYYY-MM-DD-->
    <field id="BT-9">2022-12-19</field>
    <!--Seller name  (Raison sociale du vendeur)-->
    <field id="BT-27">Efalia</field>
    <!--Seller Country code  (Code de pays du vendeur)-->
    <field id="BT-40">FR</field>
    <!--Seller VAT identifier  (Identifiant à la TVA du vendeur)-->
    <field id="BT-31">FR9876543210</field>
    <!--Buyer name  (Raison sociale de l'acheteur)-->
    <field id="BT-44">M. Lenoir</field>
    <!--Buyer Country code  (Code de pays de l'acheteur)-->
    <field id="BT-55">FR</field>
    <!--Buyer VAT identifier  (Identifiant à la TVA de l'acheteur)-->
    <field id="BT-48">FR1234567890</field>
    <!--List of products-->
     <list id="BG-25">
      <item>			
       <!--Item line number identifier (Identifiant de la ligne de facture)-->
        <field id="BT-126">1</field>
        <!--Billed quantity  (quantité facturée)-->
        <field id="BT-129" unitCode="C62">1</field>
        <!--Invoiced quantity unit of measure code  (Unité de mesure de la quantité facturée)--> 
        <field id="BT-130">PAL</field>
        <!--Item unit price before VAT  (Prix HT de l’article (unitaire))-->
        <field id="BT-146">20050.00</field>
        <!--VAT code type of the billed item  (Code de type de TVA de l’artice facturé)-->
        <field id="BT-151">S</field>
        <!--Item description  (Nom de l’article)-->
        <field id="BT-153">Infoprint 20 IBM</field>
        <!--Total amount before VAT of the billed item  (Montant Total HT de ligne article)-->
        <field id="BT-131">20050.00</field>
        <!--VAT type of the billed item-->
        <field id="itemVatTypeCode">VAT</field>
        <!--VAT applicable rate of the billed item (% de l'article facturé)-->
        <field id="BT-152">20.00</field>
      </item>
      <item>
        <field id="BT-126">2</field>
        <field id="BT-129" unitCode="C62">1</field>
        <field id="BT-130">PAL</field>
        <field id="BT-146">15550.00</field>
        <field id="BT-151">S</field>
        <field id="BT-153">Infoprint 60 IBM</field>
        <field id="BT-131">15550.00</field>
        <field id="itemVatTypeCode">VAT</field>
        <field id="BT-152">20.00</field>
      </item>			
     </list>
     <list id="BG-23">
      <item>				
        <!--VAT basis amount for this type of VAT  (Base d'imposition du type de TVA)-->
        <field id="BT-116">35600.00</field>
        <!--VAT amount for this type of VAT  (Montant de la TVA pour chaque type de TVA)-->
        <field id="BT-117">7120.00</field>
        <!--VAT type code  (Code de type de TVA)-->
        <field id="BT-118">S</field>
        <!--VAT rate for this type of VAT  (Taux de type de TVA)-->
        <field id="BT-119">20.00</field>
      </item>     
     </list>
   </doc>
  </data></nowiki>

=Exemple général=
==XML Pivot de données==

 <doc type="CII_FLUX200010">
  <field id="BT-1" title="Numéro de facture">F10207217</field>
  <field id="BT-2" title="Date Emission Facture">2023-09-21</field>
  <field id="BT-3" title="Code Type Facture">380</field>
  <field id="BT-5" title="Code Devise Facture">EUR</field>
  <field id="BT-109" title="Montant total facture hors TVA">1619.00</field>
  <field id="BT-112" title="Montant total facture  avec TVA">1915.80</field>
  <field id="BT-115" title="Montant  A payer">0.00</field>
  <field id="BT-110" title="Montant total de TVA de la facture">296.80</field>
  <field id="BT-106" title="Somme des montants nets lig fac">1619.00</field>
  <field id="BT-40" title="Code de pays du vendeur">FR</field>
  <field id="BT-55" title="Code de pays de l'acheteur">FR</field>
  <field id="BT-27" title="Raison sociale du vendeur">EFALIA EXPERTISE</field>
  <field id="BT-31" title="TVA intercommunautaire vendeur">FR59552108722</field>
  <field id="BT-44" title="Raison social acheteur">M EFA JEAN-JACQUES</field>
  <field id="BT-9_BT-9-DISP_1_BT-9">2023-09-25</field>
  <list id="BG-25">
   <item type="BG-25">
    <field id="BT-153" title="Nom Article">ASSISTANCE EFALIA 07 A 09/22</field>
    <field id="BT-130" title="Code de l'unité de mesure de la quantité facturée">E48</field>
    <field id="BT-131" title=" montant net ligne facture"></field>
    <field id="BT-151">1</field>
    <field id="BT-152" title="Taux Tva">1</field>
    <field id="BT-129" title="Quantité facturée"></field>
    <field id="BT-148" title="prix brut article">1686.00</field>
    <list id="BG-27">
     <item type="BG-27">
      <field id="BT-139">   REMISE APPLIQUEE</field>
      <field id="BT-136">-337.00</field>
     </item>
    </list>
   </item>
   <item type="BG-25">
    <field id="BT-153" title="Nom Article">COMPOSE</field>
    <field id="BT-130" title="Code de l'unité de mesure de la quantité facturée">E48</field>
    <field id="BT-131" title=" montant net ligne facture"></field>
    <field id="BT-151">1</field>
    <field id="BT-152" title="Taux Tva">1</field>
    <field id="BT-129" title="Quantité facturée"></field>
    <field id="BT-148" title="prix brut article">135.00</field>
   </item>
   <item type="BG-25">
    <field id="BT-153" title="Nom Article">COMPOSE - DOSSIER SUIVI A. GED</field>
    <field id="BT-130" title="Code de l'unité de mesure de la quantité facturée">E48</field>
    <field id="BT-131" title=" montant net ligne facture"></field>
    <field id="BT-151">0</field>
    <field id="BT-152" title="Taux Tva">0</field>
    <field id="BT-129" title="Quantité facturée"></field>
    <field id="BT-148" title="prix brut article">135.00</field>
   </item>
  </list>
  <list id="BG-23">
   <item type="BG-23">
    <field id="BT-116">135.00</field>
    <field id="BT-117">0.00</field>
    <field id="BT-118">0</field>
    <field id="BT-119">0</field>
   </item>
   <item type="BG-23">
    <field id="BT-116">1484.00</field>
    <field id="BT-117">296.80</field>
    <field id="BT-118">1</field>
    <field id="BT-119">1</field>
   </item>
  </list>
  <list id="BT-29a">
   <item type="None">
    <field id="BT-29A" title="Identifiant Siren Asujetti">FR12345678911</field>
    <field id="BT-29A-1" title="Code Siren">0018</field>
   </item>
  </list>
 </doc>
 </data>

==XML de paramétrage==
 <param>
  <field id="BT-113" xpath="/data/doc[1]/field[@id='BT-113_None_1_BT-113']"/>
  <field id="BT-9" xpath="/data/doc[1]/field[@id='BT-9_BT-9-DISP_1_BT-9']"/>
	
  <!--calcule automatiquement le montant à payer : BT-115 = BT-112 - BT-113 + BT-114 -->
  <field id="BT-115" calculate="true"/>
  <list id="BG-23" xpath="/*/doc[1]/list[@id='BG-23']"/>
  <list id="BG-25" xpath="/*/doc[1]/list[@id='BG-25']"/>
 
   <taxes>
    <codes>
     <value from="0" to="Z"/>
     <value from="1" to="S"/>
     <value from="2" to="S"/>
     <value from="3" to="S"/>
    </codes>
    <rates>
     <value from="0" to="0.00"/>
     <value from="1" to="20.00"/>
     <value from="2" to="8.50"/>
     <value from="3" to="4.00"/>
    </rates>		
    </taxes>	
   <translations>
    <BT-129>
     <value from="" to="1.000"/>	
    </BT-129>
    <BT-146>
     <value from="*" to="calc()">
      <field op="" id="BT-148"/>
      <field op="-" id="BT-136"/>
     </value>
    </BT-146>
    <BT-131>
     <value from="*" to="calc()">
      <field op="" id="BT-146"/>
      <field op="*" id="BT-129"/>
     </value>
    </BT-131>
   </translations>	
 </param>