Technische Omschrijving SALES005 v1.0.4

Versie: Procesbeschrijving SALES005 v1.0.4

1 Inleiding

Dit document geeft algemene informatie over de technische afspraken voor het gebruik van de DICO Standaard in de sector Bouw en Installatie. Voor de procesbeschrijving zie het document “Procesbeschrijving Databerichten SALES005” of “Procesbeschrijving transactieberichten SALES005”. Dit document betreft de algemene specificaties voor XML-berichten:

• Opbouw van de invoeringsconventies;
• Opbouw van de technische documentatie;
• Aandachtspunten XML;
• Verzenden van XML-berichten.

Dit document is generiek voor alle andere DICO berichten SALES005. De specificaties uit dit document moeten gebruikt worden in combinatie met het document “Procesbeschrijving Databerichten SALES005” of “Procesbeschrijving Transactieberichten SALES005”. De documentatie is met zorg samengesteld, mochten er onverhoopt toch fouten of onduidelijkheden in staan wordt u verzocht contact op te nemen met Ketenstandaard voor uitsluitsel. Gelieve niet zelf een interpretatie te maken, dit om dialecten van de standaard te voorkomen.

De documentatie beschrijft het toepassingsgebied van de DICO Standaard. De structuur, inhoud en gebruikersregels worden toegelicht. Uiteindelijke DICO XML berichten moeten voldoen aan de beschreven eisen. Voor de daadwerkelijke uitwisseling van DICO berichten is een licentie vereist. Voor meer informatie en gebruikersvoorwaarden hierover, zie de website van Ketenstandaard Bouw en Techniek.

1.1 Wat is het doel van dit document?

In dit document leest u welke overkoepelende afspraken zijn gemaakt binnen de branche over het gebruik van de DICO XML verhuurberichten. Dit procesmodel is bedoeld voor de verhuurberichten en geeft een overzicht van de spelregels die gelden binnen de DICO Standaard.

1.2 Welke documenten maken deel uit van de gebruikersdocumentatie?

De gebruikersdocumentatie voor de verhuurberichten bestaat uit twee documenten: een procesbeschrijving (dit document) van de verhuurberichten en een technisch document. Overige (technische) informatie is gepubliceerd op Semantic Treehouse. Hier zijn onder andere voorbeeldberichten te vinden maar ook tools zoals een validatietool om berichten te valideren. De documentatie is met zorg samengesteld, mochten er onverhoopt toch fouten of onduidelijkheden in staan wordt u verzocht contact op te nemen met Ketenstandaard voor uitsluitsel. Gelieve niet zelf een interpretatie te maken, om zo dialecten van de standaard te voorkomen. De documentatie beschrijft het toepassingsgebied, proces en technische uitgangspunten van de DICO Standaard. De structuur, inhoud en gebruikersregels worden verder toegelicht op Semantic Treehouse. Uiteindelijke DICO XML berichten moeten voldoen aan de beschreven eisen. Voor de daadwerkelijke uitwisseling van DICO berichten is een licentie vereist. Voor meer informatie en gebruikersvoorwaarden hierover, zie Ketenstandaard Bouw & Techniek.

1.3 Samenstellers

Dit document wordt onderhouden door Ketenstandaard Bouw en Techniek. Ketenstandaard Bouw en Techniek beheert de DICO Standaard en faciliteert DICO Commissies voor de Bouw en Installatie sector. Bedrijven uit de sector zijn vertegenwoordigd binnen deze commissies, waarmee aansluiting op de informatiebehoefte van de sector gewaarborgd blijft. Voor vragen of opmerkingen over dit document kunt u contact opnemen met dico@ketenstandaard.nl.

2 Wijzigingstabel

Eventuele wijziging(en) t.o.v. een voorgaande versie worden getoond in een wijzigingstabel. De informatie is vindbaar op de website van Ketenstandaard Bouw en Techniek: www.ketenstandaard.nl.

3 Algemene specificaties SALES005

3.1 Opbouw specificaties

3.1.1 Functionele documentatie

De functionele beschrijving van de invoeringsconventies bestaat uit attributen (gegevens) en gegevensgroepen (entiteiten). Elke gegevensgroep bestaat uit een aantal attributen. Een attribuut komt slechts eenmaal voor in een gegevensgroep. Een gegevensgroep kan meerdere malen voorkomen (herhalende gegevensgroep). De gegevensgroepen zijn hiërarchisch gegroepeerd, dat wil zeggen dat een gegevensgroep afhankelijk kan zijn van een andere gegevensgroep. De pdf bijlages zijn vervangen door een publicatie tool (Semantic Treehouse). Het voordeel is dat alle informatie up to date is en eventuele verduidelijking toegevoegd kan worden. De documentatie kan gevonden worden op Semantic Treehouse:

Figuur 1: Klik op 'Standaard'

Figuur 2: Klik op het bericht dat u wilt bekijken

Figuur 3: Overzicht boomstructuur in Semantic Treehouse

Figuur 4: U kunt hier de berichtspecificaties bekijken

3.1.2 Overzicht van entiteiten (gegevensgroepen)

Per gegevensgroep is het volgende aangegeven:
• 'Element': naam van de gegevens/gegevensgroep;
• [1..1] beschrijft de cardinaliteit: de verplichting en de multipliciteit. Het eerste cijfer kan een waarde van ‘0’ of ‘1’ hebben waarbij ‘0’ aangeeft dat het optioneel is en ‘1’ aangeeft dat het verplicht is. Het tweede cijfer geeft de multipliciteit aan en kan een waarde van ‘1’ of hoger of ‘n’ hebben. N geeft aan dat de entiteit onbeperkt gebruikt mag worden.
• Plaats in de hiërarchie. Een gegevensgroep bevat één of meer gegevens. Een gegevensgroep kan gelijkwaardig zijn aan een andere gegevensgroep. Ook kan het zijn dat een gegevensgroep een andere gegevensgroep bevat. Dit verschijnsel noemen we 'nesting'.

Figuur 5: Overzicht boomstructuur in Semantic Treehouse

3.1.3 Elementen beschrijving

Elk element is als volgt beschreven:

• Naam van het attribuut of entiteit en bijbehorende omschrijving.
• Het gegevenstype van het attribuut.
• Het pad van het attribuut.
• De namespace van het attribuut.
• Het formaat van de gegevens, indien van toepassing.
• Lengte van het attribuut, indien van toepassing.
• Business rules die gelden voor het attribuut.
• Codelijst die van toepassing is.

Figuur 6 - Informatie over het betreffende element

3.1.4 Syntaxen

De DICO berichten worden uitsluitend in XML aangeboden. In de onderstaande schema’s wordt verwezen naar het model. De berichten dienen altijd conform de XML standaard ingevuld te worden.

3.1.5 Validatietool

Ketenstandaard stelt een validatietool beschikbaar aan haar licentiehouders waarmee de DICO berichten gecontroleerd kunnen worden. De validatietool maakt onderscheid tussen een technische validatie (de structuur) en een functionele validatie (business rules). De tool is te vinden via www.ketenstandaard.nl achter de inlog.

Figuur 7 - De validatietool

Figuur 8 - Selecteer het project waar binnen het bericht valt

Figuur 9 - Selecteer het bericht

Figuur 10 - Selecteer de juiste versie

Figuur 11 - Selecteer het bestand dat u wilt valideren vanaf uw eigen computer

Figuur 12 - Klik op 'validate message'

Figuur 13 - U krijgt het resultaat teruggekoppeld

3.2 XML berichten

XML staat voor eXtensible Markup Language. Dit is een standaard die is ontwikkeld voor het uitwisselen van informatie via internet. De berichten van de DICO Standaard zijn op maat ontwikkeld waardoor er verschillen bestaan met andere internationale XML standaards.

Als ontvanger van de DICO XML-berichten moet men er rekening mee houden dat alle velden aangeleverd kunnen worden met alle mogelijke codes en statussen die gedefinieerd zijn. De verzendende partij heeft de verantwoordelijkheid om te zorgen dat het aangeboden bestand aan de DICO Standaard voldoet. In beide gevallen is het belangrijk rekening te houden met het feit dat de codelijsten dynamisch zijn en dus aan verandering onderhevig kunnen zijn.

3.2.1 Opzet van de technische documentatie

De technische documentatie voor de DICO XML is te vinden op Semantic Treehouse. Onder meer:

• Voorbeeld XML
  Voorbeeld is beschikbaar. Dus is ook meteen te valideren;
• De technische beschrijvingen op Semantic Treehouse (voorheen: Functionele attributenlijst) Binnen Semantic Treehouse worden de volgorde van de velden, de eigenschappen van de velden, regels (business rules), codelijsten en alle relevante informatie weergegeven;
• XSD Schema's

Deze schema’s implementeert u in de software, zij vormen de basis van de berichten zowel inkomend als uitgaand. Advies is de XSD’s in zijn geheel te implementeren;

3.2.2 Externe codelijsten

De codelijsten staan met de komst van de SALES005 extern gedefinieerd. De codes staan niet meer in de bericht-XSD gedefinieerd maar worden op een andere, externe codelijst beschreven en blijven onderdeel van de DICO Standaard. Dit om codelijsten flexibeler te maken m.b.t. wijzigingen. In de attributenlijst wordt de verwijzing naar de te gebruiken codesubset gemaakt. De codelijst kan aan verandering onderhevig zijn, de meest actuele codelijst is leidend. De meest actuele codelijst kan gevonden worden in de downloadsectie van www.ketenstandaard.nl. Het is zaak bij implementatie van de DICO berichten in de software met een veranderende, externe codelijst rekening te houden. De DICO Standaard gebruikt ook internationaal gestandaardiseerde non-DICO codelijsten:

non-DICO codelijsten		URL organisatie
Country	ISO 1166 two alpha code	https://www.iso.org/iso-1166-country-codes.html
Currency	ISO 4217 three alpha code	https://www.iso.org/iso-4217-currency-codes.html
Language	ISO 619 two alpha code	https://www.iso.org/iso-619-language-codes.html
Package type description code	EANCOM manual part III code list 7065 (incl. UN/ECE Recommendation No. 21)	http://apps.gs1.org/GDD/bms/EANCOM/Pages/clDetails.aspx?semanticURN=urn:gs1:gdd🆑7065PackageTypeDescriptionCode&release=1 http://www.unece.org/uncefact/codelistrecs.html
Units of Measure	Units of Measure Code UNECE Recommendation No. 20	http://tfig.unece.org/contents/recommendation-20.htm

Tabel 1 - non-DICO codelijsten

3.2.3 Extensies

Sinds de SALES005 wordt er gebruik gemaakt van extensies. Deze extensies zijn met het oog op backward compatibility geïmplementeerd. Door het gebruik van extensies kan er functionaliteit worden toegevoegd aan de standaard zonder dat er een nieuwe release moet komen. Het toevoegen van officiële extensies aan de DICO Standaard is voorbehouden aan de commissies en kan via een RFC worden aangevraagd. Een officiële extensie zal in een nieuwe release permanent onderdeel gaan uitmaken van de DICO Standaard. De officiële extensies worden beschikbaar gesteld op de beheeromgeving. In de DICO Standaard zijn de specifieke locaties voor een extensie al gedefinieerd in de XML en XSD. Voor het gebruik en valideren van een extensie wordt in de header een verwijzing naar locatie van de extensie gemaakt, zie paragraaf 3.3.2. In de extensie XSD staan de structuur en eisen van de officiële extensies gedefinieerd. De entiteiten en velden in het XML bericht worden voorafgegaan door de exs: verwijzing. In het XML bericht wordt op de volgende wijze naar de extensie gemaakt verwezen:

  <UserDefinedExtension xsi:schemaLocation="http://www.ketenstandaard.nl/SALES/Extensies extensies.xsd">
    <exs:newextension1>
      <exs:veldnaam1>Uw waarde</exs:veldnaam1>
    </exs:newextension1>

Eventuele meerdere extensies kunnen als volgt worden bijgevoegd:

   </exs:newextension1>
   <exs:newextension2>
        <exs:veldnaam1>Uw andere waarde</exs:veldnaam1>
   </exs:newextension2>

3.2.4 Bijlagen en certificaten

Doormiddel van bijlagen en certificaten is het mogelijk om additionele informatie mee te sturen zoals veiligheidsbladen (SDS), tekeningen en handleidingen. De structuur van de certificaten biedt ruimte om informatie zoals geldigheidsdatum van een certificaat mee te geven. Getracht is om de velden een duidelijke naam en functie mee te geven. Er wordt een beroep op gebruikers gedaan om de informatie correct te plaatsen. Daarbij is de informatie in (de inhoud van) het certificaat altijd leidend ten opzichte van de informatie in het bericht.

3.3 Technische uitgangspunten

3.3.1 Naamgeving van XML bestanden

Om de herkenbaarheid van de SALES005 XML berichten te vergroten kan de volgende naamgevingsconventie worden gebruikt:

<berichttype>_<GLN van de zendende partij>_<documentnummer>_<datum/tijd>

Voorbeeld: Order_8712145000011_0001_20180110.xml Binnen de SALES005 is de volgende naamgeving afgesproken bij factuurberichten:

<GLN van de zendende partij>_<factuurnummer>

Voorbeeld: 8712145000011_FAC10648.xml

3.3.2 Header

Voor de XML versie en de karakterset wordt resp. 1.0 en UTF 8 gebruikt in de berichten:

<?xml version="1.0" encoding="UTF-8"?>

Om diverse berichtenversies te kunnen onderscheiden dient de structuur van de onderstaande header overgenomen te worden. In dit voorbeeld gaat het om het factuurbericht. Alle voorbeeldberichten bevatten de juiste header en dienen overgenomen te worden. De namespace EXS wordt door Ketenstandaard voorbehouden voor het gebruik van extensies. Voorbeeld voor het factuurbericht met extensie verwijzing:

<Invoice xmlns:xs="http://www.w1.org/2001/XMLSchema" xmlns="http://www.ketenstandaard.nl/factuur/SALES/005" xmlns:exs="http://www.ketenstandaard.nl/SALES/Extensies" xmlns:xsi="http://www.w1.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ketenstandaard.nl/factuur/SALES/005 Factuur_SALES005.xsd">

Opmerking: er zit een spatie in de laatste regel van de header

3.3.3 Lege optionele elementen

Indien een optioneel element niet gebruikt wordt, wordt het betreffende element in zijn geheel weg gelaten. Omdat bij string element definities veelal een ‘MinLength’=1 wordt gebruikt, overeenkomstig XML best practices, kan alleen onderstaande methode 1 worden gebruikt. Ook voor elementen van het type ‘decimal’ geldt dat deze alleen met methode 1 leeg gelaten kunnen worden. In XML kan op drie manieren een leeg optioneel element worden ‘weergegeven’:

1. Door er niets in te zetten, bijvoorbeeld: <naam></naam>
2. Door de start-sluit tag te vervangen door één tag, als volgt: <naam/>
3. Door het betreffende element geheel weg te laten.

3.3.4 Verboden tekens

Sommige karakters hebben een speciale betekenis in XML en kunnen niet in XML-elementen gebruikt worden. Het gaat om de volgende karakters:

Verboden tekens
<	>	&	'	"
Less than	Greater than	Ampersand	Apostrophe	Quotation mark

Tabel 2 - Verboden tekens

Een verboden teken kan vervangen worden door een entity reference, zoals in onderstaande tabel.

Entity references
<	>	&	'	"
Less than	Greater than	Ampersand	Apostrophe	Quotation mark
\&lt;	\&gt;	\&amp;	\&apos;	\&quot;

Tabel 3 - Entity references

Onderstaand een referentie naar W1Schools. Hier vindt u meer informatie over de XML Standaard: http://www.w1schools.com/xml/xml_syntax.asp.

3.3.5 Gebruik CDATA tag

De CDATA tag kan gebruikt worden om in XML code verboden tekens te gebruiken. Doormiddel van de CDATA tag interpreteert het systeem alles binnen de tag als tekst. Het gebruik van de CDATA tag is toegestaan zolang dit geen conflict oplevert met de in het model beschreven veldlengte. Voor het toepassen van CDATA notering zie W1Schools. Hier vindt u meer informatie over de XML Standaard: http://www.w1schools.com/xml/xml_syntax.asp.

3.3.6 Gegevenstypen

Binnen de DICO Standaard hanteren we een aantal vooraf gespecificeerde gegevenstypen. De formaten en significantie zijn in onderstaand schema vastgelegd:

Soort numeriek gegeven		Aantal cijfers voor decimaalteken	Aantal cijfers achter decimaalteken
Bedragen	n..18	12	6 *
Belastingtarieven	n..17	11	4
Controlewaarden	n..18	14	4
Gewichten	n..18	15	1
Hoeveelheden (aantal)	n..15	12	1
Inhouden (volume)	n..9	5	4
Percentages	n..10	6	4
Percentage bereikwaarden	n..18	14	4
Overige bereikwaarden	n..18	15	1
Prijsbasis	n..9	6	1
Prijzen	n..15	11	4
Valuta	n..12	6	6

*In XML berichten met als valuta de euro worden 2 decimalen gebruikt, omdat bedragen in hele Euro en in eurocenten kunnen worden uitgedrukt.

Tabel 4 - Gegevenstypen, bron: Basisdocument GS1 eCom versie 1.1, 12-08-2014

3.3.7 GTIN (GS1 artikelcode)

Met de GS1 artikelcode (of Global Trade Item Number, GTIN) kunt u uw artikelen coderen. Deze codes kunt u gebruiken voor elektronische gegevensuitwisseling met uw handelspartners. Een GTIN kent verschillende vormen met verschillende lengtes; meest voorkomend is de GTIN11 (11 posities). Deze bestaat uit 11 cijfers en kan worden weergegeven in een EAN11-symbool. Op bepaalde consumenteenheden is niet voldoende ruimte voor het EAN11-symbool. In dat geval kunt u een GTIN-8 gebruiken, weergegeven in een EAN8-symbool. Beheerder van de artikelcodering (GTIN) is GS1 Nederland. De lengte van een GTIN die binnen de DICO Standaard gebruikt wordt staat vast op 14 numerieke posities, hierdoor moet er vaak een of meerdere ‘0’ voor de GTIN geplaatst worden.

GTIN		Voorbeeld
GTIN-8	87121012	00000087121012
GTIN-11	8712145678906	08712145678906
GTIN-14	18712145678907	18712145678907

Tabel 5 - Voorbeelden van gebruik GTIN

3.3.8 GLN (GS1 adrescode)

Met de GS1 adrescode (of Global Location Number, GLN) kunt u interne en externe bedrijfsadressen coderen. De code kunt u gebruiken voor elektronische gegevensuitwisseling met uw handelspartners. Hierdoor kunt u uw gegevens synchroniseren met die van de handelspartners. U kunt goederenstromen beter beheersen: met de GS1 adrescode kunt u aangeven voor welk adres de goederen bestemd zijn. Voorbeelden van interne adressen zijn afdelingen, laadplatforms, productiestraten, lopende banden etc. Externe adressen kunnen een hoofdkantoor, vestigingen of bijvoorbeeld distributiecentra zijn. U creëert een GS1 adrescode op basis van uw GS1 bedrijfsnummer of u kunt een apart blok van GS1 adrescodes aanvragen. Beheerder van de adrescode standaard (GLN) is GS1 Nederland. Ketenstandaard verstrekt namens GS1 voor de bouw- en installatiesector de GLN’s aan haar deelnemers.

3.3.9 SSCC (GS1 verzendcode)

Logistieke verzendeenheden codeert u met de zogenoemde GS1 verzendcode, ook wel bekend als de Serial Shipping Container Code: de SSCC. Met deze code kunt u logistieke verzendeenheden, zoals pakketten, pallets en rolcontainers met goederen wereldwijd uniek coderen en identificeren. De GS1 verzendcode is een nummer van 18 cijfers. De GS1 verzendcode dient als sleutel voor een computerbestand waarin de informatie over de bijbehorende verzendeenheid is opgenomen. U creëert een GS1-verzendcode op basis van uw GS1 bedrijfsnummer of u kunt een apart blok van GS1 verzendcodes aanvragen. De GS1 verzendcode kan worden weergegeven in een GS1-128 symbool. Beheerder van de verzendcode (SSCC) is GS1 Nederland.

3.4 Ontbrekende functionaliteit

Wanneer de markt bepaalde functionaliteit mist, kan zij een wijzigingsverzoek (Request for Change) indienen via Semantic Treehouse. Een Request for Change wordt beoordeeld op duidelijkheid en compleetheid door Ketenstandaard en wordt voorgelegd aan de expert commissie(s). Zo blijft de kwaliteit van de standaard gewaarborgd. Wanneer een Request for Change wordt ingewilligd, wordt de gevraagde functionaliteit in een volgende release opgenomen.

Figuur 14 - Indienen RFC via Semantic Treehouse

3.5 XML berichten verzenden en ontvangen

Voor het verzenden en/of ontvangen van XML-berichten bestaan verschillende manieren. Er zijn grofweg twee methodes te onderscheiden. Bilaterale (point-to-point) verbindingen. Voorbeelden van dergelijke verbindingen zijn: AS2, SFTP, FTPS, E-mail, webservices, OFTP, OFTP2. Naast deze methoden biedt de DICO Standaard een eigen MessageService (in SOAP en REST protocol) aan. Deze protocollen zijn op Semantic Treehouse te vinden.

• Voordeel: Geen bijkomende kosten per bericht;
• Nadeel: U dient zelf uw koppelingen naar uw partners in te richten en te beheren. Een tussenpartij die de connectiviteit naar de verschillende platformen levert. Voor deze methode kan ook de Messaservice worden gebruikt om te communiceren met deze tussenpartij.
• Voordeel: U onderhoudt slechts één connectie met de provider. De provider zorgt voor de connectiviteit met uw partners;
• Nadeel: Kosten worden vaak verrekend op basis van berichtgrootte en -aantal.