v1 · för utvecklare

Kossorna CDB-API

Ger journalsystem tillgång till nötkreatursdata ur Jordbruksverkets centrala nötkreatursregister (CDB), samt hanterar de medlemmar och samtycken som ger rätten till datan.

Den här sidan förklarar upplägget. Det fullständiga kontraktet - fältnamn, scheman, exakta felkuvert - står i OpenAPI-specen. Vid konflikt är det den filen som gäller.

Kom igång

Stegen låser upp varandra i tur och ordning: utan BusinessUuid går inga medlemsanrop, och utan signerat samtycke svarar djurdatan 401 hur giltig din nyckel än är.

1. 1

   Teckna avtal med Jordbruksverket

   Ett avtal om utlämnande av CDB-uppgifter mellan er och Jordbruksverket är en förutsättning för att få en API-nyckel. Utan det avtalet får uppgifterna inte lämnas ut till er, och ingen nyckel skapas. Avtalets bilaga 1 avgör dessutom VILKA uppgifter ni får se - den styr vilka fält som kommer med i svaren.

2. 2

   Få en API-nyckel av kossorna

   När avtalet är på plats skapar kossorna nyckeln. Den hör till journalsystemet, inte till en enskild verksamhet. Du får den tillsammans med basadressen.

3. 3

   Onboarda verksamheten

   Svaret innehåller ett BusinessUuid. Spara det - det ska med som header i allt som rör medlemmar och djur. Anropet är en upsert, så det går att köra om.

   POST /api/v1/businesses

4. 4

   Lägg till djurhållaren

   Har du redan ett signerat samtycke skickar du med det i anropet. Har du inte det skickar kossorna automatiskt ett SMS till djurhållaren med en signeringslänk. Anropet är idempotent på personnummer - kör det så ofta du vill.

   POST /api/v1/members

5. 5

   Vänta in samtycket

   Innan djurhållaren signerat svarar djurdatan 401 med code no_consent. Det är det enda 401 som löser sig av sig självt. Kossorna pingar din webhook när något ändrats.

   GET /api/v1/members/{ssn}/find_by_ssn

6. 6

   Hämta anläggningarna

   Lätt anrop som ger djurhållarens anläggningar med antal levande djur på varje. Använd det för att bygga en lista att välja i.

   GET /api/v1/cdb/{ssn}/ppns_for_ssn

7. 7

   Hämta djuren

   Samma svar som steg 5 fast med hela djurlistan per anläggning. Tyngre - hämta det när användaren valt anläggning, inte i förväg.

   GET /api/v1/cdb/{ssn}/ppns_with_animals_for_ssn

8. 8

   Håll dig uppdaterad

   Webhookpingen betyder 'hämta om den här medlemmen', inte vad som hänt. Vad som faktiskt förändrats i beståndet läser du ur registerhållnings-endpointsen. Om datan alls är färsk svarar last_file_date på - ett tomt svar från ett dygn då leveransen uteblev är inte samma sak som att inget hänt.

   GET /api/v1/cdb/{ssn}/dead · GET /api/v1/cdb/{ssn}/departed · GET /api/v1/last_file_date

Så hänger det ihop

Fem nivåer. Varje anrop du gör pekar ut var i kedjan du befinner dig.

1. kund - journalsystemet självt, det som håller API-nyckeln
2. verksamhet (business) - veterinärpraktiken eller motsvarande, identifieras av BusinessUuid
3. medlem - djurhållaren, identifieras av person- eller organisationsnummer
4. anläggning - platsen där djuren står
5. djur - det enskilda nötkreaturet

Ord som betyder samma sak, eller nästan

aktuellt_ppn

Anläggningen djuret står på just nu.

anläggning

Anläggning, produktionsplats och PPN är tre ord för samma sak. Fältet heter `plants` i API:t och `produktionsplats` hos Jordbruksverket.

djurets uuid

Djurets stabila nyckel. Den ändras aldrig under djurets liv, till skillnad från öronnumret. Lagra uuid, inte öronnumret - se fallgroparna.

öronnummer / identitet

Djurets läsbara namn, t.ex. SE-900001-0222-2. Kan bytas under djurets liv; ett djur kan ha haft flera.

Autentisering

Token identifierar kunden, BusinessUuid verksamheten, och samtycket avgör vilken medlems data som får läsas. Alla tre måste stämma - en giltig token räcker inte.

Authorization

Kundens API-nyckel. `Bearer <nyckel>` eller bara `<nyckel>` - ledande `Bearer ` strippas serversidan. Identifierar journalsystemet. Nyckeln förutsätter ett avtal om utlämnande av CDB-uppgifter med Jordbruksverket.

BusinessUuid

Vilken verksamhet anropet gäller. Värdet är det uuid som POST /businesses gav. Krävs av alla /members- och /cdb-anrop utöver Authorization. Läses skiftlägesokänsligt.

Bara den här menyn och /healthz. Allt annat svarar 401.

Samtycke

Ingen djurdata utan att djurhållaren gett verksamheten samtycke. Saknas det svarar /cdb 401 med code `no_consent`.

Om inget samtycke skickas med

Skapas en medlem utan något av dem skickar kossorna automatiskt ett SMS till medlemmen med en signeringslänk. Går numret inte att skicka till svarar POST /members 422 - men medlemmen är ändå skapad.

Vem som får signera

Är medlemmen ett företag får vem som helst signera. Är medlemmen privatperson eller enskild firma måste signaturen bära medlemmens eget personnummer - annars sparas ingenting.

Innan det finns

`no_consent` kan lösa sig av sig självt när medlemmen signerar. Det är det enda 401 som är värt att fråga igen på senare.

Var datan kommer ifrån

Ursprung

All djur- och anläggningsdata kommer från Jordbruksverkets centrala nötkreatursregister. Kossorna beställer, hämtar och tolkar filerna; API:t serverar resultatet.

Takt

Beställning skickas kvällen före, filerna hämtas och tolkas morgonen därpå. Datan är alltså upp till ett dygn gammal. Det finns inget sätt att trigga en hämtning via API:t.

Två leveranser per dygn

Varje dygn beställs två filuppsättningar. INKREMENTELL bär förändringarna för de djurhållare som redan fått en fullständig leverans; TOTAL bär hela beståndet för dem som aldrig fått en, plus de äldsta i rotationen. Uppsättningarna överlappar inte.

Hur färsk är datan?

GET /api/v1/last_file_date svarar när filerna senast blev korrekt inlästa. Datumet är BESTÄLLNINGENS dag, alltså vilket läge datan speglar - inte när vi hämtade den. Svaret delas upp i `total` och `incremental` därför att de två leveranserna täcker olika djurhållare: den inkrementella går till i stort sett alla varje dygn, den totala till en roterande delmängd. Ett anrop per dygn räcker gott.

Första leveransen

En nytillagd medlems djurdata finns inte förrän hennes första fullständiga leverans har hämtats - normalt morgonen efter att samtycket kom in. Tomma listor dessförinnan betyder 'ännu inte levererat', inte 'inga djur'.

Eftersläpning

Jordbruksverket kan leverera en händelse långt i efterhand. Därför räknar /dead och /departed sina fönster på när VI bokförde händelsen, inte på när den inträffade.

När något går fel

Gren på `code` i kroppen, inte på statuskoden. 401 är överlagrat och betyder både 'ogiltig token' och 'du saknar rätt till den här medlemmen'.

4xx ska inte retryas - samma anrop ger samma svar. 5xx och nätverkstimeout är den enda rimligt retrybara klassen. Ingen Retry-After skickas.

Manuella fel ger {"error": "..."}, valideringsfel ger {"errors": {"fält": [...]}}, oväntade fel ger {"errors": {"detail": "..."}}. `code` finns på auth-felen och på /cdb, men inte överallt. Läs OpenAPI-filen innan du parsar felkroppar hårt.

Webhook

Kossorna pingar kundens konfigurerade webhook_url när en medlems uppgifter kan ha ändrats. Pingen är en GET utan body - den säger 'hämta om den här medlemmen', inte vad som hänt.

GET {webhook_url}/{VERKSAMHETENS_SSN}/business/{MEDLEMMENS_SSN}/member

Triggas av

medlem skapad eller uppdaterad · samtycke godkänt eller signerat · SMS-status från operatören

Omförsök

Första anropet plus tre omförsök: efter 10 minuter, 2 timmar och 24 timmar.

Ingen signatur

Det finns ingen HMAC eller signatur idag. Behandla pingen som ett tips om att hämta, aldrig som en betrodd uppgift i sig.

Fallgropar

Det här är sådant som inte syns i en fältlista, men som kostar tid att upptäcka själv.