Specifikation för leverantörsreskontra

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

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:

  1. Man vill använda kolumnnamn snarare än ordningen för att detektera om viss data finns. Korta och enkla kolumnnamn minskar risken för att problem uppstår.
  2. Det är vanligt att man erbjuder söktjänster där frågor mot olika kolumner skrivs in i webbadresser och det är bra om det kan göras utan speciella teckenkodningar.

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):

kopare_id,kopare,verifikationsnummer,leverantor,leverantor_id,konto_nr,konto_text,belopp,datum,forvaltning,faktura_nr,grund,avtal,kommun_id,s_kod_nr

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:

"Be conservative in what you do, be liberal in what you accept from others"

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:

kopare_id;kopare;verifikationsnummer;leverantor;leverantor_id;konto_nr;konto_text;belopp;datum;forvaltning;faktura_nr;grund;avtal;kommun_id;s_kod_nr

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

Om data görs tillgängligt på en webbadress bör följande gälla:

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.

Sedan 2015 finns, "Metadata Vocabulary for Tabular Data", en W3C rekommendation för hur man anger metadata för datamodeller uttryckta i CSV.

Schema: https://lankadedata.se/spec/leverantorsreskontra/1.1/schema.json

För detta fall innebär detta schema:

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

JSON uttrycket följer direkt ifrån CSV schemat och W3C rekommendationen "Generating JSON from Tabular Data on the Web" . Se exempel i appendix B.

4.1 Åtkomst via HTTP

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

4.2 Schema

Indirekt via CSV schemat.

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:

  1. På datamängden peka ut denna specifikation via propertyn dcterms:conformsTo (med fältnamnet "uppfyller").
  2. Lägg till "leverantörsreskontra", "inköp" som nyckelord på svenska.
  3. På distributionen som motsvarar CSV-filen peka ut schemat via propertyn dcterms:conformsTo (med fältnamnet "länkade scheman").

Appendix A: Exempel på inköp i CSV

Exempel: Nedan är en fil med två riktiga inköp från Göteborg stad, fälten grund och avtal innehåller påhittade värden dock.
kopare_id,kopare,verifikationsnummer,leverantor,leverantor_id,konto_nr,konto_text,belopp,datum,forvaltning,fakturanummer,grund,avtal,kommun_id,s_kod_nr
2120001355,3921217387,Jordbruksverket distriktsveterinärerna,2021004151,7459,övriga konsulttjänster,2022.31,2020-01-01,392 - Park- och Naturnämnden,,,,,
2120001355,8001020462,Folkhälsomyndigheten,7499,Övriga främmande tjänster,444.75,2020-01-01,2021006545,800 - Miljö- och klimatnämnden,,,,,

Appendix B: Exempel på inköp i JSON

Exempel: Samma två inköp som för CSV fast nu i json.
[
  {
    "kopare_id": "2120001710",
    "kopare": "Skövde kommun",
    "verifikationsnummer": "3921217387",
    "leverantor": "Jordbruksverket distriktsveterinärerna",
    "leverantor_id": "2021004151",
    "konto_nr": "7459",
    "konto_text": "övriga konsulttjänster",
    "belopp": "2022.31",
    "datum": "2020-01-01",
    "forvaltning": "392 - Park- och Naturnämnden",
    "fakturanummer": "",
    "grund": "",
    "avtal": "",
    "kommun_id": "",
    "s_kod_nr": ""
  },
  {
    "kopare_id": "2120001710",
    "kopare": "Skövde kommun",
    "verifikationsnummer": "8001020462",
    "leverantor": "Folkhälsomyndigheten",
    "leverantor_id": "2021006545",
    "konto_nr": "7499",
    "konto_text": "Övriga främmande tjänster",
    "belopp": "444.75",
    "datum": "2020-01-01",
    "forvaltning": "800 - Miljö- och klimatnämnden",
    "fakturanummer": "",
    "grund": "",
    "avtal": "",
    "kommun_id": "",
    "s_kod_nr": ""
  }
]

Appendix C: Versionshistorik