Tillbaka till api.kvittar.se »

Commerce/0.1/sv

Från Kvittar API

Innehåll

Beskrivning av Kvittars API-lösning

Kvittars API bygger på REST (Representational State Transfer) över krypterade HTTP (HTTPS). Följande HTTP headers måste finnas i varje förfrågan (utöver autentisering):

Header Giltiga värden Beskrivning
Content-type application/json, application/xml
Enbart för uppladdning: application/pdf, application/tif
Vilket dataformat klienten skickar.
Accept application/json, application/xml Önskat dataformat för svar från servern.

Alla anrop görs mot:

https://api.commerce.kvittar.se/

Autentisering

Kvittar har utvecklat en autentiseringlösning som är baserad på OAuth-standarden (RFC 5849). Varje tillverkare som önskar integrera med Kvittar får enligt avtal tillgång till följande uppsättning API-nycklar:

Beteckning Exempel Beskrivning
kvittar_api_key e0e32074248acb1be4b5979eb73a5e4a Tillverkarens unika API-nyckel.
kvittar_shared_secret 7efa3179939a0773 Tillverkarens unika privata nyckel.


Den första nyckeln (kvittar_api_key) används för att hämta en ny uppsättning nycklar för varje individuell kassaapparat, medan (kvittar_shared_secret) är en privat nyckel som enbart används för signering av denna förfrågan.

Hämta nycklar för en individuell kassaapparat

För att en kassaapparat ska kunna kommunicera med Kvittars API måste varje anrop innehålla en unik nyckel och en signatur. Dessa nycklar erhålls genom att anropa:

POST /authentication

med följande parametrar:

Beteckning Exempel Beskrivning
X-Kvittar-Token e0e32074248acb1be4b5979eb73a5e4a Tillverkarens unika API-nyckel.
X-Kvittar-Signature 7efa3179939a0773a403 Beräknad signatur.
machine_id 8SX3JmpxwVLjwHk Kassaapparatens unika

kontrollnummer.

timestamp 1303723393 Aktuellt tid uttryckt i antalet sekunder

sedan 1970-01-01 00:00:00 UTC


Signaturen (X-Kvittar-Signature) beräknas enligt den metod som beskrivs i “Beräkna signaturen X-Kvittar-Signature” och tillämpar HMAC-SHA1. Metoder för att beräkna HMAC-SHA1-signaturer återfinns i de vanligaste programmeringsspråken.

Parametrarna X-Kvittar-Token och X-Kvittar-Signature skickas som HTTP-headers, medan machine_id och timestamp skickas i HTTP-body som antingen XML eller JSON:

<xml version="1.0" encoding="UTF-8">
<authentication>
<machine_id>8SX3JmpxwVLjwHk</machine_id>
<timestamp>1303723393</timestamp>
</authentication>


{
        "authentication": {
                "machine_id": "8SX3JmpxwVLjwHk",
                "timestamp": "1303723393"
        }
}

När Kvittars system har verfierat förfrågan om nya nyckelpar fås svar i form utav tre parametrar:

Beteckning Exempel Beskrivning
kvittar_token 8b004246379f6a45fee0995e8ad5a7 Tillfällig unik nyckel för kassaapparaten
kvittar_token_secret 8e70d526d13e20 Tillfällig privat nyckel för kassaapparaten
expires 1303724293 Tid då nyckelparet blir ogiltigt uttryckt i antalet sekunder sedan 1970-01-01 00:00:00 UTC

Autentisering och signering vid anrop till Kvittar

Efter att de tillfälliga nycklarna har hämtats ut kan kassasystemet kommunicera med Kvittar enligt de specifikationer som återfinns i det här dokumentet. Varje förfrågan ska då innehålla följande parametrar som HTTP-headers.

Beteckning Exempel Beskrivning
X-Kvittar-Token 8b004246379f6a45fee0995e8ad5a7 Tillfällig unik nyckel för kassaapparaten
X-Kvittar-Signature 8e70d526d13e20 Signatur enligt metoden angiven i 0.1.2

När de tillfälliga nycklarna slutar gälla åligger det klienten (kassaapparaten) att begära ut nya nyckelpar enligt förfarandet i som beskrivs i “Hämta nycklar för en individuell kassaapparat”.

Beräkna signaturen X-Kvittar-Signature

Genom att bilda följande sträng (pseudo-kod):

signatureBase =
<HTTP-metod>&
<URL>&
<Content-type>&
<Accept>&
<MD5-summa av HTTP-body>
Beteckning Exempel Beskrivning
HTTP-metod POST Typ av HTTP-metod som används i förfrågan.
URL http://api.commerce.kvittar.se/authentication Fullständig sökväg till API-anropet (URL).
Content-type application/json Aktuell Content-type
Accept application/json Aktuell Accept
MD5-summa av HTTP-body d41d8cd98f00b204e9800998ecf8427e MD5-hash av innehållet som skickas i HTTP-body

och sedan beräkna HMAC-SHA1 med hjälp utav den privata nyckeln.

X-Kvittar-Signature = hmac-sha1(signatureBase, secret)

Om anropet är till /authentication ska kvittar_shared_secret användas. Övriga anrop ska signeras med den aktuella kvittar_token_secret.

För exempeldatan med JSON (MD5 1f5381c91f6d3eb31fa0e0a8306425) och ett anrop till http://api.commerce.kvittar.se/authentication via POST blir strängen att signera:

POST&http://api.commerce.kvittar.se/authentication&application/json&application/json&1f5381c91f6d3eb31fa0e0a8306425

och med den privata nyckeln 7efa3179939a0773 blir signaturen d0856fd16099ed9e495deb95e8d9439a3c.

Kontrollera om ett konto kan ta emot digitalt kvitto

Varje konto har en unik ID. Till exempel KVITTAR1005000005. Kontrollera status genom att anropa:

GET /account/KVITTAR1005000005

Svar i form utav HTTP Status Code: 200 OK eller 404 Not Found och även i innehållet som returneras:

<account ID="KVITTAR1">
<exists>false</exists>
</account>
{
        "account":"KVITTAR1",
        "exists":"false"
}

Minska datamängden med HEAD

För att minska mängden data vid varje kontroll kan man istället använda HEAD för att enbart undersöka vilken HTTP Status Code som returnerades:

HEAD /account/ID

Svar i form utav HTTP Status Code:

200 OK eller 404 Not Found

Skicka meta-data för digital kvitto

Skicka meta-data:

POST /receipt/add

Meta-datan skickas i body:

<?xml version="1.0" encoding="UTF-8"?>
<receipt>
<id>kassa5-lina</id>
<original>true</original>
<total_sum>120.0</total_sum>
<currency>SEK</currency>
<account>KVITTAR1005000005</account>
<time>2011-02-03 15:00:12</time>
<articles>
<article id="tulpan-20">
<name>Tulpaner</name>
<quantity>5.0</quantity>
<sum>120.0</sum>
<vat>20.0</vat>
</article>
</articles>
</receipt>


{
        "id":"kassa5-lina",
        "original":"true",
        "total_sum":"120.00",
        "currency":"SEK",
        "account":"KVITTAR1005000005",
        "time":"2011-02-03 15:00:12",
        "articles":{
                "article":{
                        "id":"rosor-14",
                        "name":"Tulpaner",
                        "quantity":"5.0",
                        "sum":"120.0",
                        "vat":"20.0"
                }
        }
}

Dataformat för digitalt kvitto

Generella fält som avser hela kvittot

Fält Beskrivning
id Valfri ID för kvittot.
original Huruvida kvittot är ett original eller inte.
total_sum Total summa inklusive moms.
currenc Valutaformat på kvittot.t
account Kontot hos Kvittar som kvittot avser.
time Tidpunkt då köpet ägde rum.

Specifika fält för varje artikel

Fält Beskrivning
id Valfri ID för artikeln.
name Varans benämning.
quantity Kvantitet/antal.
sum Pris inklusive moms för artiklarna. Ej styckpris.
vat Hela momsbeloppet för artiklarna. Ej per styck.

Svar då meta-data skickas till Kvittar

Svaret innehåller en referens-ID till det skapade kvittot. Denna referens används sedan för att hänvisa till det kvitto som ett originalkvitto avser vid uppladdning:

<receipt>
<ID>9</ID>
<created>true</created>
</receipt>


{
        "receipt": {
                "ID":9,
                "created":true
        }
}

Skicka originalkvitto som bilaga

Skicka originalkvitto som bilaga till ett digitalt kvitto med känd referens-ID:

POST /attachment/add/ID

eller

PUT /attachment/add/ID

Sjävla originalkvittot skickas i body som binär data. Tillåtna filtyper är PDF och TIF.

Svar då originalkvitto skickas till Kvittar (POST)

Om inga fel påträffas returneras en SHA1-summa för den bifogade filen:

<attachment>
<receipt>9</receipt>
<hash>9e8092ba9241b03fb9edf802d0272e62da8</hash>
</attachment>


{
        "attachment":{
                "receipt":14,
                "hash":"9e8092ba9241b03fb9edf802d0272e62da8"
        }
}

Svar då originalkvitto skickas till Kvittar (PUT)

Vid PUT återfinns SHA1-summan i HTTP-headern:

X-SHA1: 9e8092ba9241b03fb9edf802d0272e62da8

Felkoder och dess innebörd

För att underlätta implementation på klientsidan används standardiserade HTTP-svar (HTTP Status Code)  i den mån det är möjligt.

Kod Innebörd
200: Success Anropet lyckades
201: Created Lyckades skapa ny resurs
400: Resource Invalid Ogiltig formatering
401: Unauthorized Åtkomst nekas (autentisering)
404: Resource Not Found Försök att nå icke-existerande resurs eller metod)
405: Method Not Allowed Fel HTTP-metod, t.ex. GET mot en resurs som enbart stödjer POST
406: Not Acceptable T.ex. Ogiltig Content-type
500: Application Error Generellt fel