Utvecklarmanual KRAV API
Utvecklarmanual KRAV API
Utvecklarmanual KRAV API
Introduktion och villkor Allmänna villkor
Översikt och API-dokumentation Inloggning / autentisering
Klientanvändare (ny) Endpoints för autentisering Klient-access
Hantera kunder Lista era kunder
Ange avtal med kund Godkänna flytt av kund Avsluta avtal
Hämta information om kund
Ta över kund från annat certifieringsorgan (ny) Uppdatera kunduppgifter
Skapa kund Användare och kontakter
Lista kontakter för en kund Uppdatera kontakt
Skapa kontakt Ta bort kontakt
Produktionsdata
Hämta produktionsdata Skapa produktionsdata Uppdatera produktionsdata
Kontroller
Sammanfattad produktionsdata Artiklar
Hämta artiklar Skapa artikel Uppdatera artikel
Registrera försäljningsvärde Hämta försäljningsvärde
KC-nr
Begär KC-nr Hämta KC-nr
KC-nr för kedjecertifierade enheter KC-nr för produktionsplatser
Dra tillbaka KC-nr
Kedjecertifiering och produktionsplatser
Ange kedjecertifiering och produktionsplatser Skapa produktionsplatser och/eller kedjeenhet
Introduktion och villkor
KRAV lanserar ett öppet API för att integrera mot KRAVs tjänster. Denna dokumentation är tänkt som en start för dig att komma igång. Notera att du behöver ha ett avtal med KRAV för att integrera mot API:t, och att du även behöver ha ett klientkonto.
Allmänna villkor
För att använda API:t behöver du ett avtal med KRAV. Kontakta oss direkt på xxxx.xx. En ansvarig utvecklare skall anges för integrationen.
Användarkonton hos KRAV är personliga. Det är inte tillåtet att skapa systemkonton hos KRAV.
Anrop mot API:t som kräver användarautentisering skall motsvara den person som använder klienten.
Utveckling av klienter mot KRAV API sker mot KRAVs stagingmijö.
Innan en integration får driftsättas mot skarp produktion skall den godkännas av KRAV.
Översikt och API-dokumentation
API:t går att nå via xxxxx://xxx-xxxx.xxxx.xx
Alla tjänster nedan, med undantag av oauth-provider, tillhandahåller ett API för data-access, och i vissa fall för att sätta igång processer (affärslogik-flöden).
För varje tjänst nedan (ej oauth-provider) finns en online-dokumentation och en playground för att testa anrop. För att nå dessa, klicka på servicenamn i tabellen nedan.
Service | Jsondoc-url |
oauth- provider | Sköter klient- och användarautentisering. |
user-service | Lagrar användardata (e-postadress för inloggning, lösenord). |
event-service | Sköter notifiering för händelser i systemet, och meddelar berörda parter via e-post. Har även ett API för att hämta alla händelser som rör en specifik användare. |
organisation- service | Lagrar information om organisationer (kunder) och är ansvarig för rättighetsstyrning mellan användare och objekt som organisationer äger. Hanterar även logik rörande byte av certiferingsorgan (CO) för kund och CO. |
revision- service | Sköter affärslogiken för kontroller av produktionsdata av revisorer/certifieringsorgan. Äger även produktionsdata för kunder. |
document- service | Lagrar dokument och filer åt andra tjänster, till exempel bilder för artiklar och organisationer. Har även en "filarea" för varje användare. |
article- service | Har hand om artiklar (produkter) för organisationer och försäljningsvärden för dessa. |
Inloggning / autentisering
Gemensamt för alla tjänster är att de kräver autentisering innan de kan nås. Vi använder oss av OAuth 2.0 för autentisering och auktorisering, specifikt även tillsammans med JWT ( JSON Web Tokens). OAuth 2.0 använder sig av kortlivade tokens som skickas med i Authorization- headern
I våra API:er används två former av autentisering:
Klient Autentisering på klientnivå ger access på API-nivå, och bestämmer vilka typer av anrop din klient kan göra.
Användare - Autentisering på användare ger access på data-nivå, och bestämmer vilken typ av data användare har rätt att läsa och skriva.
Vissa anrop kräver ej användarautentisering (hämta publik data, t.ex. publika artiklar). För alla syften för certifieringsorgan kommer dock användarautentisering att göras. Här är det önskvärt att autentisering sker direkt hos KRAV ur säkerhetssynpunkt, med access code grant.
Oauth provider
Service
Klient
Användare
Oauth provider
Service
Klient
Användare
Anrop
Redirect, logga in
Anrop 401 (logga in)
Anv.namn och lösenord (+Client credentials)
Access Code Hämta token Token
Anrop (token) Resultat
Resultat
KRAV tillåter även autentisering via lagrade användare, så kallad password grant. Detta rekommenderas att användas främst för de användare som man har direkt kontroll över (anställda). För kunder rekommenderas access code grant enligt ovan alternativt en klientanvändare, se nedan.
Klientanvändare (ny)
KRAV tillåter i vissa fall en klientanvändare. En sådan användare har samma rättigheter som en revisor att arbeta med en kunds data, men har inte rättigheter att agera revisor i systemet (godkänna kontroll, hämta KC-nr).
Logga in
Logga in
Anrop
Anrop
KRAV API
Klient
Kund
kundens användare
klientanvändare
KRAV API
Klient
Kund
Endpoints för autentisering
authorization uri: xxxxx://xxxxxxxxxxxx-xxxxxxx.xx-xx.xxxxxxxxx.xxx/xxxxx- provider/oauth/authorize
token uri: xxxxx://xxxxxxxxxxxx-xxxxxxx.xx-xx.xxxxxxxxx.xxx/xxxxx-xxxxxxxx/xxxxx/xxxxx
Användar-info kan sedan hämtas genom: xxxxx://xxxxxxxxxxxx-xxxxxxx.xx- xx.xxxxxxxxx.xxx/xxxx-xxxxxxx/xxxx/xx
Klient-access
För vissa funktioner behövs anonym autentisering från en tjänst, t.ex. för att hämta offentliga kontakter / artiklar. För detta ändamål skall klienten autentisera sig genom ett så
kallat client_credentials-flöde, t.ex.
1 curl -u 'client-id:clent-secret' -X POST - d'grant_type=client_credentials''xxxxx://xxx-xxxx.xxxx.xx/xxxxx- provider/oauth/token'
Detta returnerar en bearer-token som kan användas för att hämta dessa resurser.
Hantera kunder
organisationer
Kunder (och certifieringsorgan) lagras som hos KRAV. En organisation har ett
KIP-ID
unikt system-id som kallas . Vid de flesta operationer på en organisation behöver du
KIP-ID
KIP-ID
har hämta
som nyckel. Du kan söka på kund med organisationsnummer eller KRAV-nr och från resultatet.
Lista era kunder
Som certifieringsorgan kan du även hämta era samtliga kunder genom att fråga efter
KIP-ID
organisationer utifrån ert , se exempel nedan.
GET organisation
[KravOrganisation]
org.service
Klient
?has_co = ert KIP-ID ger alla era kunder.
org.service
Klient
Ange avtal med kund
För att ett certifieringsorgan ska få tillgång till data för en kund, behöver systemet ha ett giltigt avtal som är godkänt av kund. För att kunna ange avtal för en kund behöver kunden finnas registrerad hos KRAV.
Ange avtal görs enligt följande:
Fråga efter kund kundinfo
Ange avtal (kundid etc) resultat
org.service
Klient
org.service
Klient
Godkänna flytt av kund
Om ett annat certifieringsorgan anger avtal för en kund där ni har ett aktivt avtal, behöver ni som nuvarande certifieringsorgan godkänna den avtalsförfrågan. När ni gör det innebär det att ni inte längre har access till kunden i systemet.
Hämta förfrågningar [approvalrequest]
Godkänn resultat
org.service
Klient
org.service
Klient
approvalrequest
changerequest
Notera skillnaden på väntar på svar)
Avsluta avtal
(där ni behöver agera) och
(där ni
Om ni avslutar ett avtal med kund kan ni ange detta till KRAV. När detta sker har ni inte längre access till kunden.
Observera att vi byte av CO skall istället ett godkännande av flytt av kund göras, se ovan. Detta skall bara användas för kunder som inte längre ska vara KRAV-certifierade.
ChangeRequest
org.service
Klient
newCoId=null för att avsluta avtal
org.service
Klient
Hämta information om kund
Ni har möjlighet att hämta uppgifter för alla de kunder ni har aktiva avtal med.
Hämta organisationsdata KravOrganisation
org.service
Klient
org.service
Klient
Klassen KravOrganisation innehåller uppgifter om kunden såsom kontaktuppgifter, fakturauppgifter, KRAV-nr, etc.
KIP-ID
Ni kan hämta organisationsuppgifter utifrån KRAV-nr, och organisationsnr. Observera
att flera kunder kan ha samma organisationsnr, så resultatet där blir en lista av KravOrganisation.
1
2
3
4
5
6
7
8
// Hämta på KIP-ID returnerar KravOrganisation
/organisation/{id}
// Hämta på organisationsnr returnerar [KravOrganisation]
/organisation?org_nr=
// Hämta på KRAV-nr
/organisation?krav_nr=
Ta över kund från annat certifieringsorgan (ny)
Om ni tar över en redan certifierad kund från ett annat certifieringsorgan bör ni börja med att hämta informationen om den kunden från KRAV, för att undvika att kunden behöver ange denna information igen, se instruktioner ovan.
Information om en potentiell kund kan hämtas via
1 GET /organisation/{id}
Denna grundläggande information innehåller
KRAV-nummer (Företags-)namn Populärnamn Org-nummer
Stad (under ett adress-objekt)
När den refererade organisationen ansluts till er som kund kommer samma anrop returnera resterande information.
Uppdatera kunduppgifter
Som certifieringsorgan har ni möjlighet att uppdatera uppgifter för en kund.
Observera att ni kan uppdatera all information, men inte ta bort en organisation.
PUT KravOrganisation KravOrganisation
org.service
Klient
org.service
Klient
I anropet skickar ni med ett objekt av typen KravOrganisation, och får det uppdatera objektet tillbaka.
Skapa kund
I dagsläget är det inte tillåtet att skapa en kund via API:t. Där hänvisar vi till Mitt KRAV.
Användare och kontakter
En kontakt är precis som det låter; en kontaktperson hos en organisation som har namn och kontaktuppgifter såsom telefonnr, e-post, etc. En organisation ska alltid ha minst en KRAV- kontakt.
En användare är en användare till KRAVs system och har inloggningsuppgifter för att komma åt sin information.
En kontakt är knuten till en organisation, medan en användare kan tillhöra flera organisationer. Eller mera korrekt flera kontakter.
Kund 1 | ||||
kontakt_1 | användare | |||
Kund 2
kontakt2
Kund 3
kontakt
Lista kontakter för en kund
Ni kan lista alla kontakter för en kund.
GET contact [KravContact]
org.service
Klient
org.service
Klient
page
GET contact?page=0&organisation=XXX
Observera att parametern D.v.s.
delar upp resultatet i 25 kontakter åt gången, och börjar på 0. ger de 25 första kontakterna för organisation xxx,
page=1
26-50 etc. Om page ej är angivet får du alla kontakter returnerade.
Uppdatera kontakt
För att uppdatera en kontakt hämtar du kontaktobjektet, modifierar det och skickar tillbaka det i sin helhet.
GET contact [KravContact]
Uppdatera kontaktuppgifter
PUT contact
KravContact
org.service
Klient
org.service
Klient
OBS: För närvarande finns ett problem med att uppdatera e-post på en kontakt. Om detta är önskvärt, kontakta KRAV innan.
Skapa kontakt
OBS: I dagsläget är det ett problem med att skapa kontakter. Om det är önskvärt, kontakta KRAV innan.
För att skapa en kontakt skickar du in ett kontaktobjekt.
Klient
org.service
Skapa kontaktobjekt
POST contact
KravContact
org.service
Klient
Ta bort kontakt
OBS: I dagsläget är det ett problem med att ta bort kontakter, vilket gör att vi avråder från att använda det tillsvidare. Behöver ni det var vänlig kontakta KRAV.
Produktionsdata
Hämta produktionsdata
Ni kan hämta produktionsdata för en kund.
Observera att artiklar och dess försäljningsvärde ligger utanför detta (i article-service). Det aggregerade försäljningsvärdet finns även i produktionsdatat.
GET revisionData KravRevisionData
rev.service
Klient
rev.service
Klient
Skapa produktionsdata
Ni har möjlighet att skapa och uppdatera produktionsdata direkt från er klient. Till exempel kan en kund ange produktionsdata i er tjänst som sedan uppdateras i KRAVs system.
Observera att det är kundens ansvar att informationen hos KRAV är korrekt. En rekommendation är därför att kunden är medveten om att informationen uppdateras hos KRAV.
POST KravRevisionData KravRevisionData
rev.service
Klient
rev.service
Klient
Uppdatera produktionsdata
Vid uppdatering av produktionsdata hämtar ni först objektet, och uppdaterar sedan aktuella fält. Sedan skicka ni över hela objektet.
GET revisionData KravRevisionData
Uppdatera produktionsdata
PUT KravRevisionData
KravRevisionData
rev.service
Klient
rev.service
Klient
Kontroller
Det åligger kunden att hålla sin produktionsdata uppdaterad. Vid en kontroll skall revisorn kontrollera att de uppgifter som ligger i KRAVs system är korrekta.
KravRevision
För att göra en kontroll skapar man först ett kontrollobjekt ( ). Efter det hämtar ni
produktionsdata och organisation enligt exempel ovan. Sedan kontrollerar ni att kundens uppgifter i KRAVs system är korrekta.
När en kontroll är klar och uppgifterna är korrekta, anger ni detta till revision-service.
Observera: Fram till dess att ni godkänner en revision så kan kund fortfarande uppdatera information via en annan klient (t.ex. Mitt KRAV). Det är därför viktigt att detta görs inom ett kort tidsintervall.
Om uppgifter hämtats ut tidigare, till exempel inför ett kundbesök, så bör det göras innan kontrollen, och att kontrollen följer detta flöde och uppgifterna hämtas på nytt.
Klient rev.service org.service
POST revision/spec KravRevision
GET revisionData KravRevisionData
GET KravOrganisation KravOrganisation
Kontrollera produktionsdata och kontaktuppgifter
PUT KravRevision (state=APPROVED) KravRevision
Klient
rev.service
org.service
Sammanfattad produktionsdata
Du kan hämta samtliga kontrolluppgifter inom flera regelområden genom att anropa
/revision-service/aggregateData
med parametrarna krav_nr satt till KRAV-numret på den
rule_areas
organisation som önskas (inklusive K), samt satt till en komma-separerad lista över
de numeriska regelområdena (de som syns i KravOrganisation-objektet)
rule_areas
Observera att vissa delar av svaret kan vara null, beroende på vilka regelområden som skickas in i
revision-service
aggregate-
För mer information, se API-dokumentationen för , underrubrik
revision-info-controller
OBS! Om du tänker använda endpoint för aggregateData vill vi att du observerar att den är under utveckling.
Artiklar
Artiklar hanteras i article-service. En artikel har ett antal fält kopplade till sig, se API- dokumentationen. En artikel har även ett försäljningsvärde.
Observera att du kan jobba med artiklar för en kund även om kunden inte har ett regelområde (godkänt eller ansökt) som innefattar artiklar.
Hämta artiklar
Ni kan hämta artiklar för en kund som ni har avtal med.
GET articles [KravArticle]
art.service
Klient
art.service
Klient
Skapa artikel
För att skapa en artikel skapar du ett artikelobjekt och skriver detta till article-services för aktuellt kund. Observera att du behöver skapa varje artikel för sig med ett separat anrop.
Skapa KravArticle
POST article
KravArticle
art.service
Klient
art.service
Klient
Uppdatera artikel
Uppdatera artikel följer samma struktur som tidigare. Du behöver uppdatera en artikel åt gången.
GET articles [KravArticle]
Uppdatera artikeldata
PUT article
KravArticle
art.service
Klient
art.service
Klient
Registrera försäljningsvärde
Du kan registrera försäljningsvärde för en artikel på en av era kunder. Du behöver artikelid på den artikel du vill registrera försäljningsvärde på. Du skickar in artikelid, år och summa i SEK med heltal.
När alla värden är angivna för alla artiklar, behöver dessa låsas för att slutföra registrering av försäljningsvärde.
GET articles
[KravArticle]
PUT sale/lock
[ för alla artiklar ]
POST sale KravArticleSales
loop
art.service
Klient
Sedan låser du försäljningsvärdena
art.service
Klient
Observera att när försäljningsvärdena för året är låste, går det inte att skicka in nya värden. Behöver det göras bör kunden kontakta KRAV.
Hämta försäljningsvärde
Man kan hämta försäljningsvärde på organisation och år (ackumulerat försäljningsvärde) eller på artikel och år. Nedan för ackumulerat värde.
GET sale/sum
bigdecimal
GET sale
KravArticleSales
art.service
Klient
Alternativt för en produkt
Hämta ackumulerat försäljningsvärde
art.service
Klient
KC-nr
Varje KRAV-certifikat som ställs ut från och med 2017-01-01 skall ha ett av KRAV levererat KC-nr. Ni kan begära KC-nr inför utställande av certifikat, hämta KC-nr för befintliga kunder och dra tillbaka KC-nr om ett certifikat skulle dras tillbaka eller ändras.
Begär KC-nr
Du ska hämta ett KC-nr när ni har fattat beslut om att ställa ut ett certifikat för KRAV-certifierad
KIP-ID
verksamhet. I anropet anger du regelområden, för organisationen, fråndatum (när
KRAV-certifieringen börjar gälla) och tilldatum (certifikatets giltighetstid).
POST kc/request KravKcNumber
rev.service
Klient
isMigration = false.
rev.service
Klient
isMigration
Parametern används ej och skall alltid anges till false.
Man kan ange ett eller flera regelområden per KC-nr.
En godkänd kontroll för alla aktuella regelområden krävs för att hämta ut ett KC-nr.
Ett KC-nr går inte att förlänga; om giltighetstid eller regelområden ändras, behöver man begära ett nytt KC-nr.
Observera: Om ett KC-nr begärs ut för ett regelområde där det redan finns ett giltigt KC-nr, kommer det gamla KC-nr att bli ogiltigt. Observera att det kan finnas flera regelområden på det gamla KC-nr, som i så fall behöver få nya KC-nr om de ska fortsätta vara giltiga.
Observera: Ett certifikat blir också inaktivt när giltighetstiden har gått ut, så ett nytt KC-nr behöver begäras ut innan det gamla går ut om kunden ska ha ett giltigt KC-nr.
Hämta KC-nr
Man kan hämta KC-nr per kund/organisation.
GET kc [KravKcNumber]
rev.service
Klient
'state' filtrerar resultaten
rev.service
Klient
Observera att du by default hämtar alla KC-nr, d.v.s. aktiva, inaktiva och ersatta. Du kan
state
använda parametern för att få styra detta.
KC-nr för kedjecertifierade enheter
För kedjecertifierade enheter gäller samma anrop som ovan, men då frågan görs på
[KravKcNumber]
moderbolaget returneras en lista enhet har alltså ett eget KC-nr.
KC-nr för produktionsplatser
för moderbolaget + alla enheter under. Varje
För företag som är godkända för att ha produktionsplatser skall ett KC-nr hämtas per bolag,
d.v.s. även för varje produktionsplats.
Dra tillbaka KC-nr
När du drar tillbaka ett KC-nr blir det inaktivt, och du får ett avslutsdatum. Detta skall göras när ett certifikat blir indraget.
GET kc/{id}/revoke Ok
rev.service
Klient
rev.service
Klient
Observera: Detta gäller för alla regelområden som innefattas av KC-numret. Om certifikatet blir indraget för att en kund inte uppfyller ett regelområde men är fortsatt godkänd för andra regelområden på samma KC-nr, behöver det hämtas ut ett (eller flera) KC-nr för de kvarvarande regelområdena som fortfarande är godkända.
Kedjecertifiering och produktionsplatser
...
Ett företag kan vara kedjecertifierat eller vara godkänt för att ha produktionsplatser. För att kunna ha produktionsplatser eller enheter behöver detta vara godkänt på kunden, som då blir ett moderbolag. KRAV och certifieringsorgan har rättighet att godkänna ett bolag för produktionsplatser eller enheter.
Produktionsplats/enhet_2
Moderbolag
Produktionsplats/enhet
Varje produktionsplats och enhet motsvarar ett eget bolag i Mitt KRAV. I dagsläget finns ingen begränsning i antal nivåer, rent strukturellt, d.v.s. en enhet kan i sig vara enhetscertifierad.
Denna struktur finns för framtida utökningar av strukturen (där till exempel flera kunder kan tillhöra en huvudorganisation även om denna i sig inte har ett certifikat). En sådan struktur har idag dock inget stöd i varken regler eller i kundportalen Mitt KRAV, så det är önskvärt att inte lägga in fler än en nivå via API:t tillsvidare.
En användare tillhör en (eller flera) organisationer. En användare har alltid rättigheter att se alla bolag nedåt, men inte uppåt. Det betyder att en användare på ett moderbolag har rättigheter till alla dotterbolag (och enheter), men en användare på en dotterenhet har access bara till sitt bolag (enheten/produktionsplatsen), och har alltså inte rättigheter att se något på moderbolaget eller syskonbolag.
I stort hanteras alltså produktionsplatser och enheter på samma sätt, förutom när det gäller KC-nr (se avsnittet om KC-nr ovan).
Ange kedjecertifiering och produktionsplatser
Du kan ange att ett företag är godkänt för kedjecertifiering eller att det är godkänt att ha produktionsplatser. Detta görs i organisation-service
GET organisation/{id} KravOrganisation
Sätt kedjecert eller prod.platser
PUT organisation/{id} (KravOrganisation)
KravOrganisation
org.service
Klient
org.service
Klient
groupCertifiable=true
chainCertifiable=true
För att godkänna produktionsplatser sätter ni kedjecertifierad sätter ni .
, och för att vara
För att dra tillbaka kedje-certifikat eller möjligheten till produktionsplatser sätter man
false
motsvarande flagga till .
Skapa produktionsplatser och/eller kedjeenhet
I dagsläget är det inte tillåtet att skapa ett bolag (och därmed produktionsplats och/eller kedjeenhet) via API:t. Där hänvisar vi till Mitt KRAV.
[]: