XML-factuur veldindeling

XML-factuur veldindeling

Inleiding

In een ander artikel, Digitale factuurverwerking in combinatie met XML-facturen is beschreven wat het voordeel is van het ontvangen en verwerken van XML-facturen. Om een XML-factuur uit te kunnen lezen moet een bestaande XML-factuur veldindeling beschikbaar zijn. In het menuonderdeel 'Applicatiebeheer / Factuurverwerking / XML-factuur veldindeling' vind je alle XML veldindelingen, ook wel XML mappings genoemd, terug die beschikbaar zijn in jouw omgeving.

Er is een standaard set XML veldindelingen beschikbaar voor alle klantomgevingen. Deze set wordt beheerd door Visma | ProActive en dat kun je zien doordat deze XML veldindelingen niet bewerkt/verwijderd kunnen worden. Aanvullend bestaat er de mogelijkheid om zelf een XML veldindeling aan te maken, dit zou je kunnen overwegen op het moment dat de XML-factuur:
  1. Helemaal niet wordt herkend omdat de XML velden afwijkend zijn ten opzichte van de standaard XML veldindelingen;
  2. Specifieker moet worden uitgelezen omdat je op factuur(regel) niveau bepaalde extra waardes wilt overnemen ten behoeve van een completere/gedetailleerde factuurregel codering. 
Om een XML waarde uit te kunnen lezen moet deze uiteraard wel worden meegegeven in de XML-factuur. Zolang een waarde niet wordt meegegeven dan kan deze ook niet worden overgenomen. Stem in dat geval eerst met je de crediteur af of een ontbrekende waarde meegegeven kan worden in een bestaand XML veld dat leeg is, niet het juiste formaat bevat of in een extra XML veld dat door hen toegevoegd zou moeten worden met een waarde naar wens.

XML veldindeling

Er is een onderscheid te maken tussen de standaardmapping en de crediteurspecifieke mappings. Het standaardformaat voor XML-facturen is UBL (Universal Business Language), meest voorkomend zijn de versies UBL 2.0 en UBL 2.1. Uitgebreide algemene info kan worden teruggevonden op de site van Forum Standaardisatie. Verdere uitleg in dit artikel is gebaseerd op deze standaard. 

Zelf een nieuwe XML veldindeling toevoegen

Inventariseer eerst of het XML-bestand waarvoor je een veldindeling wilt toevoegen qua veldnamen overeenkomsten vertoond met een reeds bestaande XML veldindeling. In het geval je een specifiekere XML veldindeling wilt maken waarbij de XML gebaseerd is op een reeds bestaand XML formaat dan is het te adviseren om een bestaande XML veldindeling te kopiëren.  Kopieer bijvoorbeeld de mapping 'Standaard UBL factuur veldindeling' door op de drie puntjes aan het eind van de regel te klikken en te kiezen voor kopiëren:

Je kunt hierbij een XML-bestand uploaden dat je van de crediteur hebt ontvangen. 



Voordat je een gekopieerde XML veldindeling opslaat moet je eerst het veld 'Herkenningsstring' aanpassen/uitbreiden omdat er anders een conflict optreed met de reeds bestaande XML veldindeling. Zie ook de volgende alinea 'Herkenningsstring' in dit artikel.

Wanneer het een geheel nieuw XML formaat is die niet lijkt op een reeds bestaande XML veldindeling dan kun je via de knop 'Toevoegen', bovenaan het menuonderdeel 'XML-factuur veldindeling', een geheel nieuwe toevoegen. Het nadeel is dat je dan alle velden zelf moet mappen.

Herkenningsstring

Om een XML-factuur te kunnen verwerken, moet er een Herkenningsstring aanwezig zijn. Dit is een reeks van tekens aan de hand waarvan het bestand door Spend Cloud wordt herkend als factuur. Voor de UBL-facturen komt het erop neer dat elk XML-bestand waarin één van onderstaande reeksen terugkomt, altijd kan worden verwerkt vanuit de postbus:
  • //cbc:UBLVersionID='2.0' --> ziet eruit in de XML als <cbc:UBLVersionID>2.0
  • //cbc:UBLVersionID='2.1' --> ziet eruit in de XML als <cbc:UBLVersionID>2.1
  • //cac:AccountingCustomerParty --> ziet eruit in de XML als <cac:AccountingCustomerParty>
Als je een specifieke mapping voor een crediteur wil aanmaken, zal er dus een unieke herkenningsstring moeten worden ingesteld. Het is hierbij handig om te kijken naar andere specifieke mappings en deze als voorbeeld te gebruiken. Zo is de naam van de crediteur altijd aanwezig in het veld AccountingSupplierParty en zoals in het overzicht kan worden gezien zijn er dan ook meerdere mappings die de volgende herkenningsstring ingesteld hebben: //cac:AccountingSupplierParty/cac:Party/cac:PartyName/cbc:Name='[Naam crediteur]', waarbij het laatste gedeelte wordt vervangen door de naam van de crediteur, zoals in XML-factuur te achterhalen.

Alert
Maak je een kopie van een bestaande standaard crediteurspecifieke XML mapping? Zet dan achter de herkenningstring de tekst 'and 1', hierdoor zal deze mapping worden toegepast in plaats van de bestaande mapping, bijvoorbeeld bij de mapping van Albert Heijn. Dit komt omdat de de mapping met de meeste overeenkomsten wordt toegepast. De toevoeging 'and 1' maakt de mapping specifieker dan de algemene mapping, al zou je natuurlijk ook een andere XML waarde kunnen uitkiezen om de mapping  specifieker te maken dan de standaard XML mapping.

(//cbc:UBLVersionID='2.0' or //cbc:UBLVersionID='2.1') and (//cac:AccountingSupplierParty/cac:Party/cac:PartyName/cbc:Name='Albert Heijn') and 1

Om te testen of de herkenningsstring en de XML mapping werkt, stuur je de XML-factuur handmatig naar de postbus van jouw Spend Cloud. Als de mail in Spend Cloud is ontvangen en wordt geopend, kan de bijlage worden gedownload als PDF.

Deze PDF is een visualisatie van de XML-factuur en bovenaan deze visualisatie is zichtbaar welke mapping er zal worden gebruikt om de factuur te verwerken.

Idea
Is de XML-factuur al toegevoegd aan jouw Spend Cloud omgeving? Dan kun je de XML-veldindeling opnieuw toepassen door bij Coderen rechts van de factuur op de drie puntjes te klikken en daarna op 'XML-toewijzing opnieuw toepassen'. De Spend Cloud gaat dan opnieuw de mapping toepassen die op basis van de herkenningstring kan worden toegepast en maakt zo nodig ook factuurregels opnieuw aan. Je kunt dit alleen doen bij facturen die nog niet gecodeerd zijn.

Line identifier

Nadat het instellen van een herkenningsstring is gelukt, moet er een line identifier worden ingesteld. Dit is een veld binnen het XML-bestand waarmee elke factuurregel wordt uitgelezen. Standaard is dit //cac:InvoiceLine en in het geval van UBL-facturen hoeft hier verder niets aan te worden gewijzigd. Als de crediteur een XML-factuur aanlevert die niet is opgebouwd volgens het UBL-formaat is het dus van belang dat elke factuurregel in het bestand met dezelfde tag wordt geopend en gesloten.

Factuuropbouw

Als bijlage is een XML-bestand toegevoegd met daarin de standaard opbouw volgens UBL, met daarbij een korte uitleg welke informatie er doorgaans wordt meegegeven in deze velden. Een XML-factuur is in bijna alle gevallen opgebouwd met als eerst een algemeen deel, de kop van de factuur (factuurdatum, totaalbedrag, IBAN, etc.), waarna de factuur wordt gespecificeerd per factuurregel (artikel 1 op regel 1, artikel 2 op regel 2, etc.) met per regel o.a. de prijs en omschrijving.

Factuur kop gegevens mappen
In de kop van de factuur komen de gegevens terug die je bij het mappen kunt gebruiken voor de secties 'Factuur gegevens', 'Relatie/Crediteur gegevens' en 'Ontvanger gegevens'. 

Om bijvoorbeeld de juiste crediteur te herkennen wordt er door Spend Cloud primair naar het bankrekeningnummer (IBAN) gezocht. Standaard wordt deze in het UBL formaat meegegeven in het veld //cac:PaymentMeans/cac:PayeeFinancialAccount/cbc:ID. Als de crediteur niet herkend wordt is een mogelijke oorzaak dat het bankrekeningnummer niet matcht met het bankrekeningnummer dat bij de crediteur staat ingesteld in de Spend Cloud of dat de crediteur deze bijvoorbeeld niet heeft meegestuurd in het XML bestand.

Hieronder een voorbeeld van het XML pad dat gebruikt wordt voor het uitlezen van een IBAN bij een XML-factuur met een UBL formaat. Let hierbij vooral op de manier van noteren. Je moet een veld mappen door met '//' te beginnen en elke verdere verdieping (inspinging of tab) is te mappen door een slash '/' gevolgd door het onderliggende veld. 



Factuurregel gegevens mappen
Geeft jouw crediteur specifieke gegevens mee, denk aan het nummer van de grootboekrekening, kostenplaats of kostendrager, dan kun je deze velden uitlezen voor een zo volledig mogelijk automatisch gevulde factuur codering. Stel dat de crediteur een kostenplaatsnummer meegeeft in het veld <cbc:AccountingCost> dan zou je dit kunnen mappen. Aangezien het hierbij om een veld gaat op factuurregel niveau en er bovenaan de XML veldindeling een line identifier is opgegeven (//cac:InvoiceLine) hoef je dat gedeelte niet nog een keer op te nemen in de veld mapping, oftewel cbc:AccountingCost volstaat als veldwaarde in dit geval.



Op deze manier kun je met crediteuren afstemmen welke gegevens je graag terug zou willen zien komen in het XML-bestand en ben je zelf in staat om deze gegevens juist door de Spend Cloud uit te laten lezen. Hiermee kan het factuurverwerkingsproces voor deze crediteuren geautomatiseerd worden. Je zal wellicht moeten wennen aan de manier waarop XML-bestanden zijn opgebouwd maar als je het eenmaal doorhebt dan kun je via een maatwerk XML-veldindeling de codering van facturen tot grote mate automatisch laten vullen.

Als de XML factuurregel velden naar wens door de crediteur worden meegegeven dan zou je de crediteur (relatie) in de Spend Cloud moeten bewerken en het soort 'XML-factuur groepering' moeten wijzigen. Standaard wordt namelijk alleen de XML factuur kop gegevens uitgelezen en worden alle XML factuurregels gegroepeerd tot één factuurregel. De reden is dat sommige crediteuren soms erg veel factuurregels meegeven waardoor er binnen het Coderen menu in de Spend Cloud vele factuurregels ontstaan, terwijl de codering van de factuurregel hetzelfde moet zijn. Om die reden is de instelling 'Regels overnemen uit XML-factuur' niet te adviseren want als er bijvoorbeeld 15 verschillende artikelen worden meegegeven in de XML factuur dan worden er ook 15 factuurregels aangemaakt. Een betere optie op relatie niveau is 'Eigen groepering' waarbij je de XML factuurregels zou kunnen groeperen op een specifiek veld zoals grootboekrekening óf een combinatie van velden zoals grootboekrekening, kostenplaats en btw percentage (indien btw van toepassing). Zie hieronder hoe dit laatste voorbeeld op crediteurniveau ingesteld zou kunnen worden:




LET OP: wanneer je met de module Inkoop werkt dan is de inkooporder match leidend ten opzichte van de XML factuurregel gegevens. Voor die crediteuren (leveranciers) zou je beter kunnen focussen op een zo volledig mogelijk inkooporder codering. Wat van belang is voor dergelijke crediteuren is dat het inkoopordernummer wordt meegegeven in het XML-bestand zodat er een automatische match kan plaatsvinden. Standaard wordt het inkoopordernummer in het UBL formaat meegegeven binnen de XML factuurregels (cac:InvoiceLine) in het veld cac:OrderLineReference/cac:OrderReference/cbc:ID en is in te stellen in de sectie 'Order gegevens'. Eventueel zou het ordernummer ook in de kop van de factuur meegegeven kunnen worden maar dit is alleen mogelijk als er per factuur maar één inkoopordernummer van toepassing is. Wanneer je een specifiekere match wilt realiseren dan zou je binnen de sectie 'Order gegevens' ook de velden Artikelnummer en Aantal kunnen mappen zodat deelleveringen op artikelniveau in de match kunnen worden gemaakt.


Tips & Tricks

Het komt voor dat een crediteur niet de specifieke informatie in de XML kan meegeven zodat Spend Cloud het kan uitlezen. Denk aan onderstaande voorbeelden:
  1. In plaats van het kostenplaatsnummer, wordt altijd het nummer en de naam meegegeven. Dus '1000 - Kostenplaats A'
  2. De crediteur kan het nummer van de kostenplaats en kostendrager wel meegeven, maar in 1 veld. Dus bijvoorbeeld '1000-4800' 
  3. De crediteur kan het nummer in een veld meegeven waar meerdere gegevens in staan die variabel zijn. Dus bijvoorbeeld 'Straatnaam 12B 1000' waarbij je altijd eindigt met het kostenplaatsnummer.
  4. De crediteur geeft per factuurregel een omschrijving mee, maar voor het verwerken van de factuur wil je altijd de combinatie 'Naam crediteur - Omschrijving' in de regel hebben
  5. De crediteur geeft (per) factuurregel een element meerdere keren mee, waardoor je niet op het element zelf kunt sturen maar een bovenliggend element nodig hebt, bijvoorbeeld:
    <cac:AdditionalItemProperty>
       <cbc:Item>Kostenplaatscode</cbc:Item>
       <cbc:Value>1000</cbc:Item>
    </cac:AdditionalItemProperty>
    <cac:AdditionalItemProperty>
       <cbc:Item>Grootboekrekening</cbc:Item>
       <cbc:Value>4400</cbc:Item>
    </cac:AdditionalItemProperty>
  6. De crediteur geeft een element meerdere keren mee waardoor je niet op het element zelf kunt sturen, bijvoorbeeld:
    <cac:InvoiceLine>
       <cac:Item>
          <cbc:Name>Artikelomschrijving</cbc:Name>
       </cac:Item>
    </cac:InvoiceLine>
    <cac:InvoiceLine>
       <cac:Item>
          <cbc:Name>I.1.24.123456</cbc:Name>
       </cac:Item>
    </cac:InvoiceLine

Met bepaalde functies is het mogelijk om alsnog de juiste waarden uitgelezen te krijgen. Om de juiste waardes uit te lezen volgen nu een paar functies om de juiste waardes uitgelezen te krijgen:

1. <cbc:AccountingCost>1000 - Kostenplaats A</cbc:AccountingCost> --> Kostenplaats 1000 moet uitgelezen worden
Functie: substring(cbc:AccountingCost,0,4) --> met deze functie wordt een deel uitgelezen; startend vanaf positie 0, waarna de eerstvolgende 4 karakters worden uitgelezen 

2. <cbc:AccountingCost>1000-4800</cbc:AccountingCost> --> Kostenplaats 1000 moet worden uitgelezen en Kostendrager 4800
Functie voor kostenplaats: substring-before(cbc:AccountingCost,'-') --> een deel wordt uitgelezen, namelijk het gedeelte vóór het koppelteken
Functie voor kostendrager: substring-after(cbc:AccountingCost,'-')  --> een deel wordt uitgelezen, namelijk het gedeelte ná het koppelteken

3. <cbc:AccountingCost>Richard Holkade 9 1000</cbc:AccountingCost>  --> Kostenplaatsnummer 1000 moet worden uitgelezen. Het adres voor het nummer kan per factuur anders zijn, je kunt dus niet sturen op een vaste waarde zoals bij de substring-before of substring-after functie. 
Functie: substring(//cbc:AccountingCost, string-length(//cbc:AccountingCost) - 3) --> met deze functie wordt het totaal aantal karakters binnen de cbc:AccountingCost element berekent en leest vervolgens het laatste karakter mét de drie karakters voor het laatste karakter uit. Dus in totaal vier karakters, de lengte van het kostenplaatsnummer uit dit voorbeeld

4. <cac:AccountingSupplierParty/cac:Party/cac:PartyName/cbc:Name>Visma|ProActive</cac:AccountingSupplierParty/cac:Party/cac:PartyName/cbc:Name> & <cac:InvoiceLine/cac:Item/cbc:Description>Factuur Kwartaal 1<cac:InvoiceLine/cac:Item/cbc:Description> --> Omschrijving moet zijn Visma|Proactive - Factuur Kwartaal 1
Functie: concat(//cac:AccountingSupplierParty/cac:Party/cac:PartyName/cbc:Name,' - ',cac:InvoiceLine/cac:Item/cbc:Description) --> Met de concatenate functie worden verschillende waardes gecombineerd en deze worden van elkaar gescheiden door een komma. Door aanhalingstekens te gebruiken kan platte tekst worden toegevoegd, in deze functie is een koppelteken gebruikt.

5. <cac:AdditionalItemProperty><cbc:Item>Kostenplaatscode</cbc:Item><cbc:Value>1000</cbc:Item>
De factuurregel bevat meerdere van dit soort elementen, je kunt dus niet enkel sturen op cbc:Value, omdat dit element niet uniek is. Je kunt hem wel uniek maken door middel van het element wat erboven staat, 'Kostenplaatscode'. Deze waarde is namelijk wel uniek, en we weten dat onder de Kostenplaatscode altijd de betreffende code staat.
Functie: //cac:AdditionalItemProperty[cbc:Name='Kostenplaatscode']/cbc:Value --> in de string geven we aan dat we de waarde uit de cbc:Value willen hallen mits het hoofdelement een cbc:Name element bevat met de waarde 'Kostenplaatscode'.

6. <cac:InvoiceLine><cac:Item><cbc:Name>I.1.24.123456</cbc:Name></cac:Item></cac:InvoiceLine>
De factuur bevat meerdere cbc:Name elementen waar de leverancier unieke waarden in mee geeft, het hoofdelement is echter niet uniek waardoor ze in eerste instantie niet te onderscheiden zijn van elkaar. In dit voorbeeld willen we een inkoop ordernummer uit de factuur overnemen.
Functie: //cac:Item/cbc:Name[starts-with(., 'I.') and string-length(.) = 13] --> In dit voorbeeld willen we de waarde uit het element cbc:Name overnemen mits deze start met een I en 13 karakters lang is. Dit is een unieke reeks die alleen voor het ordernummer gebruikt zal worden en heeft ook altijd dezelfde opbouw. Wanneer je een kostenplaatscode wilt overnemen kun je ook zo sturen dat alleen de waarde uit de cbc:Name wordt overgenomen als deze enkel cijfers bevat en een bepaalde lengte heeft, Bijvoorbeeld: //cbc:Name[string-length(translate(., '0123456789', '')) = 0 and string-length(.) = 6] --> in dit voorbeeld is de kostenplaatscode 6 karakters lang.



XML-veldindeling testen

Als je zelf een XML-veldindeling hebt aangemaakt of aangepast dan kan je daarna testen of het XML-bestand naar wens wordt uitgelezen. XML-facturen kunnen alleen worden toegevoegd via het menu 'Postbus', mail daarom het XML-bestand naar het e-mailadres en zet het XML-bestand door als factuur naar het menu 'Coderen'. Wanneer je de factuur opent zie je als het goed is dat de ingestelde XML- veldindeling is toegepast doordat de gewenste velden zijn overgenomen in de codering.

Om na te gaan of daadwerkelijk de juiste XML-veldindeling is toegepast kun je bij het coderen van de factuur bovenaan de pagina de knop 'Download visualisatie' klikken (als je alleen een XML factuur zonder originele PDF hebt toegevoegd dan zie je de digitale visualisatie van de XML-factuur direct al in het PDF venster aan de rechter kant). Bovenaan de visualisatie zie je de toegepaste XML-veldindeling voorafgegaan door "Dit document is gegenereerd op basis van de mapping:". 

De 'Download visualisatie' knop zie je bovenaan de pagina bij het coderen van een factuur (afhankelijk van je schermgrootte onder de knop "Meer"):



Als blijkt dat de XML-veldindeling niet het gewenste resultaat geeft (sommige velden worden niet overgenomen uit de XML-factuur zoals van te voren bedacht) dan kun je de aangemaakt/aangepaste XML-veldindeling aanpassen waar nodig en via de onderstaande manier de XML-veldindeling opnieuw toepassen. Je ziet dan direct het resultaat van je wijziging als je daarna de factuur opnieuw opent. Je kunt net zo vaak de XML-veldindeling aanpassen en opnieuw toepassen totdat je de XML-factuur naar volle tevredenheid wordt uitgelezen.



LET OP: deze optie is alleen beschikbaar wanneer je de factuur nog niet hebt gecodeerd, zo is deze optie niet beschikbaar voor de status 'Deels gecodeerd' en 'Te verzenden'. Bij het testen van de XML-veldindeling is het om die reden om de knop 'Opslaan' niet te gebruiken zolang de XML-veldindeling nog niet naar volle tevredenheid werkt.


    • Related Articles

    • Standaard definitie van UBL in de Spend Cloud

      Deze technische informatie kan worden gebruikt door de ontwikkelaar/applicatiebeheerder van jouw boekhoudpakket. Dit is hoe de Spend Cloud UBL-facturen leest en de waarden verwerkt. Ben je benieuwd hoe je een eigen unieke XML-veldindeling (mapping) ...

    • Alles wat je wilt weten over XML-facturen

      Waarom XML-facturen verwerken? Ons doel is om gebruikers zo min mogelijk tijd te laten spenderen in de Spend Cloud. De software moet zoveel mogelijk automatisch doen, zodat onze gebruikers zich kunnen focussen op andere belangrijke taken. Digitale ...

    • Hoe kan ik XML-facturen ontvangen in de Spend Cloud?

      De (ontwerp) doelstelling van XML is eenvoud, uniformiteit en bruikbaarheid. Om deze facturen door alle computers wereldwijd te kunnen laten uitlezen zijn er bepaalde regels vastgelegd over hoe een XML-factuur moet worden opgebouwd. Deze set aan ...

    • Waarom is mijn factuur niet automatisch gematcht met de bijbehorende order?

      Je denkt net alle handelingen uitgevoerd te hebben zodat een nieuwe factuur van een bepaalde relatie automatisch door de Spend Cloud gematcht kan gaan worden met de betreffende inkooporder, maar tot je verbazing gebeurt dit niet. Voordat je in paniek ...

    • Factuurverwerkingsproces - van factuur toevoegen tot exporteren

      Van factuur toevoegen tot exporteren Er zijn verschillende mogelijkheden om de Spend Cloud module Factuurverwerking in te richten. Afhankelijk van jouw eigen factuurverwerkingsproces sluit de Spend Cloud hierop aan. In onderstaande afbeelding staat ...