Specifikation för leverantörsreskontra

Information om gjorda inköp med belopp, köpare- och leverantörsinformation - 2021-03-26

Denna version:: https://lankadedata.se/spec/leverantorsreskontra/1.1
Senaste versionen:: https://lankadedata.se/spec/leverantorsreskontra/
Förra version:: https://lankadedata.se/spec/leverantorsreskontra/1.0
Författare:: Eric Hjelmestam - MetaSolutions AB; Matthias Palmér - MetaSolutions AB; Mattias Axell - MetaSolutions AB
Bidragsgivare:: Björn Hagström - Hagström Consulting AB; Ingrid Halvorsen - Varbergs kommun; Jens Sundt - Uppsala kommun; Magnus Johansson - Myndigheten för Digital Förvaltning; Kim Lantto - Göteborgs stad; Magnus Kolsjö - Tietoevry; Maria Söderlind - Umeå kommun; Peter Mankenskiold - Tietoevry; Staffan Berge Holmbom - Örebro kommun
Attribution:: Arbete i Sambruk projekt “REF DATA” https://sambruk.github.io/Open-Accounts-Payable/
Licens:: CC-BY 4.0

1. Introduktion

Med leverantörsreskontra menas uppgifter som återfinns om gjorda inköp såsom värde på inköp, leverantörsnamn, inköpande organisation och identifierare till underlag för inköpet. I texten nedan används för enkelhets skull ordet “ett inköp” för att benämna detta.

Denna specifikation definierar en enkel tabulär informationsmodell för inköp. Specifikationen innefattar också en beskrivning av hur informationen uttrycks i formatet CSV, JSON och länkade data (RDF). Som grund förutsätts CSV kunna levereras då det är praktiskt format och skapar förutsägbarhet för mottagare av informationen. Det är också ett format som gör datautdrag enklare då snarlika processer ofta finns.

Ett inköp bokas ibland på flera olika konton då ett inköp kan innehålla olika typer av kostnader. Detta gör att ett inköp kan motsvara flera rader.

Uttrycket i länkade data återanvänder konstruktioner från andra initiativ och ger därmed en grund för interoperabilitet med data som uttrycks utan kunskap om denna specifikation.

Det rekommenderas att publicera månadsvisa dataleveranser i form av CSV och låta en datamängd definieras av ett kalenderår. Detta dels för att tagarna ofta använder tabelldata och för att det mellan ett kalenderår till nästa kan uppstå överlappande information.

2. Datamodell

Datamodellen är tabulär, där varje rad motsvarar exakt en kontering och varje kolumn motsvarar en egenskap för detta inköp. 15 kolumner är definierade, där de första 9 är obligatoriska, om köparen är en kommun bör kolumn 14, kommun_id, som innehåller kommunkod anges.

Observation 1Vi väljer att använda beskrivande men korta kolumnnamn som uttrycks med gemener, utan mellanslag (understreck för att separera ord) och utan å, ä och ö. Orsaken till detta är:

Observation 2För en enskild organisation är kolumn 1 och 2 (kopare) samma för alla rader. Det kan tyckas onödigt att upprepa detta för varje rad. Alternativet (som valts bort) är att varje mängd inköp måste kompletteras med denna information om datafiler från flera organisationer ska kombineras.

Observation 3Kolumn 3, verifikationsnummer, är en förutsättning för att den egna organisationen enkelt kunna göra en automatiserad förfrågan i en e-tjänst om begäran av fakturakopia.

Kolumner i datamodellen
#	Kolumnnamn	Värdemängd	Exempel och förklaring
1	kopare_id	text	Ange organisationsnummer för inköpande organisation utan mellanslag/bindestreck [Exempel: "2120001710" för Skövde kommun].
2	kopare	text	Ange organisationsnamnet på köparen. Förslagsvis stor bokstav först och sen gemener. [Exempel: "Skövde kommun"].
3	verifikationsnummer	text	Ange en unik och stabil identifierare för ett verifikationsnummer. Förslagsvis det verifikationsnummer som finns i ekonomisystemet. Undvik mellanslag och andra tecken som inte passar bra i en URI (webbadress).
4	leverantor	text	Ange namnet på leverantören. Förslagsvis stor bokstav först och sen gemener, men specifika skrivningar av leverantörers namn bör respekteras bara det sker konsekvent.
5	leverantor_id	text	Ange organisationsnummer för levererande organisation utan mellanslag/bindestreck [Exempel: "5560360793” Saab AB].
6	konto_nr	text	Ange kontonummer där inköpet har bokats enligt den kontoplan som används tex “64310” för facklitteratur.
7	konto_text	text	Ange texten på konto där inköpet har bokats enligt den kontoplan som används tex “facklitteratur”.
8	belopp	decimaltal	Ange beloppet i svenska kronor utan moms.
9	datum	datum	Ange datum när fakturan registreras enligt “2012-06-14” utan mellanslag.
10	forvaltning	text	Ange namn på förvaltningen som har gjort inköpet. T.ex. "Ekonomikontoret". Förslagsvis stor bokstav först och sen gemener, men specifika skrivningar av förvaltningens namn bör respekteras bara det sker konsekvent.
11	fakturanummer	text	Ange leverantörens fakturanummer så som den representeras i systemet. Detta blir inte en unik identifierare då två leverantörer kan använda samma fakturanummer.
12	grund	D \| R \| U \| A	Referens till vilken grund inköpet har gjorts på, antingen Direkt, via Ramavtal, Upphandling eller på Annat sätt.
13	avtal	url	Länk som identifierar avtal eller lagrum som grund för inköp, använd i första hand webbadresser som inleds med http:// eller https://.
14	kommun_id	text	Ange SCB:s kommunkod för er kommun eller region. Exempel: "0163" för Sollentuna kommun eller "12" för Region Skåne. Observera att en kommunkod måste vara exakt 4 siffror lång för en kommun och exakt 2 siffror lång för en region, inledande nollor får alltså inte tas bort.
15	s_kod_nr	text	Ange den inrapporteringskod (S-koden) som inköpet rapporterats på enligt ordningen för statsredovisningen i statens informationssystem Hermes exempelvis 'S5353' för tryckning, publikationer och pappersvaror, utgifter, utomstatliga.

2.1 Förtydlingar kring värdemängder

Alla reguljära uttryck angivna i tabellen nedan (förkortat reg. exp.) förutsätter att de matchar exakt, dvs inga inledande eller eftersläpande tecken tillåts. Det innebär att om uttrycket i tabellen nedan anges som -?\d+ (vilket motsvarar matcha heltal av obegränsad längd, eventuellt med ett minus framför) motsvaras det av det mer kompletta reguljära uttrycket som inleds av /^ och avslutas med $/, dvs /^-?\d+$/.

Kolumner i datamodellen
Värdemängd	Reg. Exp.	Exempel och förklaring
organisationsnummer	\d{6}\d{4}	Ett organisationsnummer anges med 6+4 siffror utan mellanslag/bindestreck. Exempelvis: "2120001710" för Skövde kommun.
heltal	-?\d+	Heltal anges alltid som en radda siffror utan mellanrum eventuellt med ett inledande minus. Se xsd:integer för en längre definition.
decimaltal	-?\d+\.\d+	Decimaltal anges i enlighet med xsd:decimal. Notera att i Sverige används ofta decimalkomma inte punkt. För att vara enhetlig mellan olika dataformat bör decimalpunkt användas istället (på det undviks problem med CSV formatet som använder komma som separator). Den kanoniska representationen i xsd:decimal är påbjuden, dvs inga inledande nollor eller +, samt att man alltid ska ha en siffra innan och efter decimalpunkt. Noll skrivs som 0.0 och ett utelämnat värde tolkas som noll.
datum	\d{4]-\d{2}-\d{2}	Datum skrivs på formatet 2010-01-01 och motsvarar antingen xsd:date. Ingen tid ska anges, inte heller tidszon.
url	-	En URL är en webbadress enligt specifikationen RFC 1738. I detta sammanhang förutsätts schemana http eller https. För webbadresser med speciella tecken tillåts UTF-8 enkodade domäner och pather, se då RFC 3986. Observera att man inte får utelämna schemat, dvs "www.example.com" är inte en tillåten webbadress, däremot är "http://www.example.com" ok. Relativa webbadresser accepteras inte heller. (Ett fullständigt reguljärt uttryck utelämnas då den är både för omfattande och opedagogisk.)

3. CSV formatet

Det enklaste formatet att stödja är CSV formatet enligt RFC4180. Se exemplet i Appendix A. Det som krävs är att första raden indikerar vilka kolumner som stöds (mellan X och Y stycken):

Utöver det som sägs i RFC4180 krävs alltid att informationen är uttryckt med teckenkodning UTF-8. På grund av att CSV har funnits länge och det finns en uppsjö av olika ramverk och program som inte alla följer RFC4180 så uppmanas man följa devisen:

För den här specifikationen innebär det att implementatörer rekommenderas även stödja semikolonseparerade filer. Orsaken är att Microsoft Excel använder semikolon istället för komma i CSV filer på operativsystem med svenska som default. Detta på grund av att komma används för decimaltal vilket ofta förekommer i CSV-filer vilket skulle kräva en omfattande användning av dubbla citationstecken kring värden. Denna specifikation kräver dock att man använder punkt i decimaltal (se 2.1).

För att särskilja data som är semikolonseparerade från kommaseparerade måste första raden se ut som:

Om några av de frivilliga kolumnerna utelämnas kan de helt tas bort från filen. Att hoppa över en mellanliggande kolumn, t.ex. kolumnen motsvarande "grund" men ändå tillhandahålla "kommun_id" är tillåtet då identifieringen av en viss kolumn sker via kolumnens namn som står överst, inte kolumnens nummer. Om värden saknas för en viss kolumn för en viss rad utelämnas värdet så att två komman (eller semikolon) kommer efter varandra. Att stoppa in nollvärden, t.ex. ett mellanslag, ett minus eller texten "null" är inte tillåtet och kommer misstolkas.

3.2 Åtkomst via HTTP

3.2 Schema

Du som är nöjd med att leverera eller använda data utifrån vad som beskrivs skriftligen i denna specifikation och exemplifieras i appendixen kan ignorera detta avsnitt.

De två sistnämnda kommer sig av att schemat också tillhandahåller saknad information, bland annat hur man konverterar ett visst CSV uttryck till RDF. Mer specifikt innehåller metadatan hur rader konverteras till instanser av schema.orgs Invoice.

Valet av schema.org gjordes eftersom den tillhandahåller en mängd egenskaper som till stor del täcker in fakturainformationen. För den som är intresserad går det att hitta andra representationer av fakturainformationen som RDF/länkade data.

4. JSON formatet

4.1 Åtkomst via HTTP

Samma gäller som för CSV förutom att content-type ska vara "application/json".

4.2 Schema

5. Beskrivning i datakatalog

För den som vill lägga in sin data som en datamängd i en datakatalog ska man använda sig av W3C rekommendationen DCAT. För svenska behov är det DCAT-AP-SE som gäller. För att göra det enklare att hitta alla datamängder som följer specifikationen på t.ex. dataportal.se är det viktigt att man markerar dessa datamängder. Man bör då göra följande: