Stöd och information

Rapportera till avfallsregistret via API

Farligt avfall i tunnor
Granskad: ‎den ‎4‎ ‎september‎ ‎2024

Verksamheter kan lämna uppgifter till avfallsregistret med hjälp av API. Här hittar du stöd kring avtal och certifikat, teknisk guide samt kodtabeller.

En verksamhet kan lämna uppgifter till Naturvårdsverkets avfallsregister med hjälp av API. API är en webbtjänst som möjliggör att två olika system kan utbyta information med varandra.

Sidan vänder sig till

Du som tar emot farligt avfall i insamlingsverksamhet och verksamhetsutvecklare samt tjänste- och mjukvaruleverantörer som levererar till verksamheter som producerar, transporterar, mäklar, handlar eller behandlar farligt avfall och annat avfall.

Bra att veta

Denna sida omfattar enbart stöd för verksamheter som ska lämna uppgifter via API. Tillsynsmyndigheter som ska hämta uppgifter via API hittar stöd här:

Avfallsregistret för tillsynsmyndigheter

Att lämna uppgifter via API

Så här sker informationsutbytet:

  • Det avsändande systemet anropar avfallsregistrets API genom att skicka uppgifterna i anteckningen om avfallet.
  • Avfallsregistrets API kontrollerar att uppgifterna är korrekta, accepterar och returnerar ett OK-svar tillbaka tillsammans med ett avfalls-id.
  • Om uppgifterna i anteckningen inte kan tas emot returnerar avfallsregistrets API ett felmeddelande.

Avfalls-id är ett slags löpnummer som systemen kan använda för att ”länka ihop” en och samma avfallsmängd i efterföljande anteckningar. I det egna verksamhetsstödsystemet är denna uppgift frivillig att använda.

Checklista inför anslutning till avfallsregistrets API

Delar av innehållet i checklistan utvecklas mer ingående längre ned på sidan.

Anslutning till API-tjänst

Verksamhetsutövare som är anteckningsskyldiga enligt avfallsförordningen och ska lämna uppgifter digitalt till avfallsregistret. Även tjänsteleverantörer och mjukvaruleverantörer har möjlighet att ansluta till avfallsregistrets API för att möjliggöra för sina kunder att lämna uppgifter till Naturvårdsverket.

Det finns två miljöer att ansluta sig till, en test- och en produktionsmiljö. Den som utvecklar ett system kan begära åtkomst till testanslutning för att testa sin integration och få systemet godkänt för produktionsanslutning. Den som har ett godkänt system upprättar sedan ett avtal för produktionsanslutning för att ansluta systemet till produktionsmiljön.

Läs mer under avsnittet Avtal och certifikat för avfallsregistret.

Om du ska utveckla ett IT-system:

  1. Skaffa ett klientcertifikat från EU:s lista med QWAC-leverantörer eller Expisoft.

    Expisoft – beställningstjänst för e-legitimationer och certifikat (expisoft.se)
  2. Ansök om anslutning till API:ets testmiljö.
  3. Hämta anslutningsuppgifterna (URL, key, secret, token).
  4. Implementera klientcertifikat, URL, key, secret och token.
    1. Klientcertifikatet och token ska skickas med i varje anrop, token ska förnyas med key/secret vid behov. Giltighetstiden är normalt 1 timme. Förnyelse görs lämpligen först om ett anrop ger statuskod 401 tillbaka varpå token förnyas och cachas i 1 timme.
    2. Se till att API:ets servercertifikat verifieras mot en lokal kopia eller mot betrodda utgivare (rot-certifikat).

Om du ska ansluta ett IT-system som du förfogar över själv (utvecklat, köpt, hyrt) till en produktionsmiljö och ska rapportera själv:

  1. Se till att det är testat (se ovan).
  2. Ansök om anslutning till API:ets produktionsmiljö.
  3. Hämta anslutningsuppgifterna (URL, key, secret, token).
    1. Uppdatera IT-systemet med anslutningsuppgifterna.

Om du ska ansluta ett IT-system (typ kommersiell tjänst/molntjänst) som du äger till en produktionsmiljö som en eller flera andra företag ska rapportera i:

  1. Se till att det är testat (se ovan).
  2. Hämta URL för API:ets produktionsmiljö.
  3. Se till att de andra företagen (kunderna) ansöker om en anslutning och egna unika anslutningsuppgifter (key, secret och token),
  4. Lägg in deras anslutningsuppgifter (key, secret, token) så att de kopplas till respektive företag och används i anropen till API:et.

Om du ska använda någon annans IT-system (tjänst) att rapportera i:

  1. Ansök om anslutning till API:ets produktionsmiljö.
  2. Hämta anslutningsuppgifterna (URL, key, secret, token).
  3. Meddela leverantören på ett säkert sätt dina anslutningsuppgifter (key, secret, token), Använd krypterat meddelande.

Observera att token och framför allt key och secret är en värdehandling som kan missbrukas om den kommer i fel händer. Förvara dem i ett krypterat format, vid överlämning använd krypterade meddelandetjänster i stället för vanlig e-post.

Teknisk anslutning

Ansök om anslutning via E-tjänsten ”API -anslutning”. Läs mer om hur det går till där som passar din situation.

API-anslutning

Ansök om anslutning via E-tjänsten ”API -anslutning”. Läs mer om hur det går till där som passar din situation.

API-anslutning

Service style

REST

Datautbytesformat

JSON

Transport security

Tvåvägsautentisering (mTLS) används varför det krävs ett klientcertifikat från en godkänd utfärdare.

Autentisering

OAuth2 Bearer används och i samband med anslutning får verksamhetsutövaren en access token med en ettårsgräns.

URL:er
  • Produktionsmiljö
    https://api.naturvardsverket.se/btfa/anteckning/v1/[resource name]...
  • Testmiljö
    https://api-test.naturvardsverket.se/btfa/anteckning/v1/[resource name]...
  • Sandbox finns ej tillgängligt i dagsläget.
Språk

De flesta datafält är namngivna på svenska. 

Request headers

NV-Client-System-ID (obligatoriskt) ska innehålla namn och version avseende det anslutande systemet.

NV-Client-Tracking-ID (frivilligt) returneras alltid i svaret och kan användas för att spåra förfrågan med ett valfritt id. Om man inte gör något val så kommer ett slumpmässigt UUID (Universal unique identifier, unik identifierare) att inkluderas i svaret.

Swagger-fil, uppdaterad 2021-10-25 (zip 9 kB)

Observera att Swagger-filen innehåller allt ni kan tänkas behöva under hela implementationsarbetet, så som design och dokumentation till implementation och test. Mer information om hur du använder Swagger kan du hitta på https://swagger.io/about/

 

Metoder Resurs Beskrivning
GET /anteckningar Anrop för egenkontroll under test av integration. Kan filtreras på datum från och till och ger tillbaka de anteckningar det anropande organisationsnumret har rapporterat.
GET /anteckningar/:avfallid Anrop för egenkontroll under test av integration. Avfallsidet får man tillbaka när man skapar en anteckning och här anges det som Path Variable.
DELETE /anteckningar Anrop för makulering av ett specifikt avfallsid.
GET /anteckningstyper Värdelista över avfallsid.
GET /atervinningsresultattyper Värdelista över typer av återvinningsresultat vid behandling av spillolja.
GET /avfallstyper Värdelista över avfallstyper.
GET /behandlingsmetoder Värdelista över behandlingsmetoder.
GET /transportsatt Värdelista över transporttyper.
PUT, POST /transportplaneringar Anteckningstyp för avfallsproducentens transportplanering.
PUT, POST /transporter Anteckningstyp för transportör vid upphämtning av farligt avfall.
PUT, POST /insamlingar Anteckningstyp för insamlare, i anslutning till att avfallet tas emot.
PUT, POST /insamlingstransport Anteckningstyp för insamlare, i anslutning till att avfallet transporteras vidare.
PUT, POST /handel Anteckningstyp för handlare och mäklare.
PUT, POST /behandlingsmottaganden Anteckningstyp för behandlare, i anslutning till att avfallet tas emot.
PUT, POST /behandlingsresultat Anteckningstyp för behandlare, när avfallet har behandlats (kvartalsredovisning).
PUT, POST /behandlingsoverlamningar Anteckningstyp för behandlare, i anslutning till att avfallet transporteras vidare till en ny innehavare.

Tabellen nedan beskriver respektive metod i API:et och motsvarande paragraf i avfallsförordningens (2020:614) sjätte kapitel.

Paragraf Metod Aktör
§5-1 /behandlingsmottaganden Behandlare av farligt avfall
§5-3 /behandlingsoverlamningar Behandlare av farligt avfall
§5-2 /behandlingsresultat Behandlare av farligt avfall
§4 /handel Mäklare av farligt avfall
§3-1 /insamlingar Insamlare av farligt avfall
§3-2 /insamlingstransport Insamlare av farligt avfall
§2 /transporter Transportör av farligt avfall
§1 /transportplaneringar Producent av farligt avfall
Exempel GET

GET https://api-test.naturvardsverket.se/btfa/anteckning/v1/avfallstyper
Authorization : Bearer xxXx0x0x0x0xxXXX000xx . . .
NV-Client-System-ID : My-system-version-1.1
NV-Client-Tracking-ID: 3.1415297

Exempel POST

POST https://api-test.naturvardsverket.se/btfa/anteckning/v1/behandlingsmottaganden
Content-Length: 342
Content-Type: application/json; charset=UTF-8
Authorization: Bearer xxXx0x0x0x0xxXXX000xx . . .
NV-Client-System-ID: My-system-version-1.1
NV-Client-Tracking-ID: 3.1415927 


{
"tidpunktForAnteckningen": "2019-11-25T10:07:19",
"datumForAvfalletsMottagande": "2019-11-25",
"ombud": "1212121212",
"verksamhetsutovare": "2021001975",
"referens": "876182763",
"avfall": {
"kod": "010305",
"mangd": 1000.00,
"foregaendeAvfallId": "0d2e3ec4-c84a-40fc-8711-a00b5cd4c6cd"
},
"tidigareInnehavare": "2021001975"
}

Response

För samtliga POST- eller PUT-operationer innehåller varje response body fältet AvfallsID  som är ett unikt id för respektive skapade eller uppdaterade uppgift. Detta värde bör användas när man rapporterar efterföljande händelser, för att på så sätt länka samman olika anteckningar och förbättra spårbarheten för respektive avfallsmängd.

Exempel:

HTTP/1.1 201 Created
Date: 2020-09-04 18:34:04
Connection: Keep-Alive
Content-Type: application/json; charset=UTF-8
Content-Length: 63
NV-Client-Tracking-ID: 3.1415927 
 
{
"AvfallsId": "072f294c-9e70-4cf6-b6a3-139922067ddc"
}

{
    "Title": "InputValidationException",
    "StatusCode": 400,
    "Message": "Ett eller flera valideringsfel har inträffat.",
    "TraceId": "80010652-0001-fc00-b63f-84710c7967bb",
    "Errors": [
        {
            "Message": "Ogiltig JSON payload",
            "Code": 10000
        }
    ]
}

  • Nånting är fel med din Requestbody, det kanske saknas ett kommatecken eller nåt fält kanske innehåller bokstäver när det bara får vara siffror. Många verktyg, ex Postman eller Notepad++ visar med rött vad som är fel med requestbodyn.

<ams:fault xmlns:ams="http://wso2.org/apimanager/security">
    <ams:code>900901</ams:code>
    <ams:message>Invalid Credentials</ams:message>
    <ams:description>Access failure for API: /btfa/anteckning/v1, version: v1 status: (900901) - Invalid Credentials. Make sure you have provided the correct security credentials</ams:description>
</ams:fault>

  • Dubbelkolla om du angivit rätt Token.

<head>
<title>502 Bad Gateway</title> 
</head> 
<body> 
  <center> 
   <h1>502 Bad Gateway</h1> 
  </center> 
   <hr> 
   <center>Microsoft-Azure-Application-Gateway/v2</center> 
</body>

  • Ditt certifikat har troligtvis gått ut. Dubbelkolla certifikatets giltighetstid och om det behöver förnyas.

Kod- och kopplingstabeller för avfallsregistret

Kodtabeller används tillsammans med informations- och kopplingstabeller för att möjliggöra fördefinierade listor och undvika fritextfält. Detta ger en mer kontrollerad vokabulär och bidrar till bättre datakvalitet. Detta är särskilt viktigt att ha koll på om man väljer att ansluta till avfallsregistret via API. Nedan beskrivs de tabeller som används i avfallsregistret.

Avfallstyper och relaterade avfallskoder återfinns i avfallsförordningens (2020:614) bilaga 3:

Avfallsförordning (2020:614)

Senaste uppdatering

Tabellerna är uppdaterade 2020-04-16.

Kod Betydelse
R Vägtransport
T Järnvägstransport
S Sjötransport
A Flygtransport
W Inlandssjöfart
P Rörledning

Enligt bilaga 1 och 2 till avfallsförordningen anges behandlingsmetod enligt så kallade R- och D-koder. För statistikändamål innehåller dock dessa koder inte tillräcklig information för att kunna klassificera avfallsbehandling i enlighet med de krav som finns. Varje R- eller D-kod behöver en underkategori där man väljer den mest lämpliga behandlingstypen för varje avfallsslag.

Till varje R- eller D-kod finns en till åtta underkoder med bokstavsbeteckning A-O, se tabell 2. Hur underkoder relaterar till resp. R- och D-kod finns beskrivet i tabell 3.

Underkod

Beskrivning underkod

A

Konventionell materialåtervinning

B

Biologisk behandling kompostering

C

Biologisk behandling rötning

D

Förbränning med energiåtervinning

E

Återvinning som konstruktionsmaterial

F

Annan återvinning

G

Återfyllning

H

Markspridning

I

Förbehandling och sortering

J

Lagring före återvinning

K

Lagring före bortskaffande

L

Omförpackning

M

Förbränning utan energiåtervinning

N

Deponering

O

Annan bortskaffning

 

Behandlingskod

Underkod

R1

D

R2

A

R3

A, B, C, E, F, G

R4

A, F

R5

A, E, F, G

R6

A

R7

A, F

R8

A, F

R9

A, F

R10

H

R11

A, B, C, D, E, F, G, H

R12

I

R13

J

D1

N

D2

O

D3

O

D4

O

D5

N

D6

O

D7

O

D8

I

D9

I

D10

M

D12

N

D13

I

D14

L
D15 K

 

 

12 01 06*

13 01 09*

13 02 08*

13 04 03*

12 01 07*

13 01 10*

13 03 01*

13 05 06*

12 01 08*

13 01 11*

13 03 06*

13 07 01*

12 01 09*

13 01 12*

13 03 07*

13 07 03*

12 01 10*

13 01 13*

13 03 08*

13 08 02*

12 01 19*

13 02 04*

13 03 09*

13 08 99*

13 01 01*

13 02 05*

13 03 10*

19 02 07*

13 01 04*

13 02 06*

13 04 01*

19 08 10*

13 01 05*

13 02 07*

13 04 02*

20 01 26

 

Kod

Typ av resultat av återvinning 

01

Regenererad basolja – grupp I

02

Regenererad basolja – grupp II

03

Regenererad basolja – grupp III

04

Regenererad basolja – grupp IV

05

Materialåtervunna produkter (specificera) 

06

Bränsleprodukter för extern energiåtervinning – lätt eldningsolja 

07

Bränsleprodukter för extern energiåtervinning - eldningsoljedestillat 

08

Bränsleprodukter för extern energiåtervinning -tjock eldningsolja 

09

Bränsleprodukter för extern energiåtervinning – återvunnen eldningsolja 

10

Bränsleprodukter för extern energiåtervinning – bearbetad eldningsolja 

11

Energiåtervinning på plats

12

Annat (specificera i fritext)

Frågor och svar om API

Här hittar svar på vanliga frågor om avfallsregistrets API.

Hur du väljer att rapportera bör framförallt utgå från mängden transaktioner, då det ofta är enklare att skicka informationen via API än att mata in uppgifter manuellt via en e-tjänst. Därför kan en API-lösning vara aktuell för både små och stora organisationer, beroende på hur den dagliga verksamheten ser ut. En API-lösning förutsätter dock att ni har möjlighet att anpassa ert system.

Nej, ingen måste ansluta sig, utan alla ska kunna använda registrets e-tjänst. Däremot finns möjligheten att ansluta sitt verksamhetssystem till registret via en API- lösning. En API-lösning skulle kunna innebära att verksamheten enbart behöver lämna uppgifterna en gång i sitt eget system.

Ett företag med ett eget verksamhetsstödssystem för hantering av farligt avfall och som lämpar sig för att vidareutvecklas med en koppling till Avfallsregistrets API.

De krav som måste uppfyllas är att:

  • Det finns en anslutning till testmiljön och när allt fungerar i den till produktionsmiljön. Det görs i E-tjänsten ”API Onboarding” (länk till info-sida).
  • Den information som skickas är både tekniskt och innehållsmässigt korrekt. Se ”Teknisk guide”

 

Det beror på hur verksamhetsstödsystemet är utformat. En koncern kan skaffa en anslutning och lämna uppgifter för andra juridiska personer, som ombud. Detta bör då regleras genom avtal eller överenskommelser. Koncernen tar därmed ansvar för att de uppgifter som lämnas är korrekta.

Om systemet är utformat så att varje enskilt AB själva gör sin rapportering så ska de ha en egen anslutning, vilket ger de en unik identitet i rapporteringen, som systemet då hanterar. Koncernen står då endast för den tekniska kopplingen till API:et om det är ett gemensamt system utan ansvar för att uppgifterna är korrekta.

Verksamhetsutövare som är anteckningsskyldiga enligt avfallsförordningen ska lämna uppgifter digitalt till avfallsregistret, och har möjlighet att ansluta till API:et. Även ombud kan lämna uppgifter via API.

Det går inte att blockera att uppgifter lämnas från till exempel vissa organisationsnummer i e-tjänsten.

För att ansluta till API:et krävs att man har ett så kallat klientcertifikat för att identifiera sin organisation. E-legitimation krävs endast för att logga in till e-tjänsten.

Du som verksamhetsutövare har inte tillgång till de uppgifter som lämnats till avfallsregistret. Uppgifter som rapporteras in bör därför göras tillgängliga för er på annat sätt, till exempel genom att de sparas i ert ombuds IT-system.

Ja, så länge du har ditt avfalls-id kan du ersätta tidigare inlämnade uppgifter, antingen via e-tjänst eller API.

I princip fungerar API:et med alla typer av system, förutsatt att systemet innehåller den information som behövs och att det går att utveckla en integration. Ett anropande system kan till exempel vara ett ordersystem.

När ni anropar avfallsregistrets API för att lämna uppgifter får ni ett svar som bekräftar att uppgifterna har tagits emot, samt returnerar ett avfalls-id. Om uppgifterna ej har tagits emot returneras ett felmeddelande.

Detta skiljer sig mot e-tjänsten där man får en bekräftelse via en pdf som går att ladda ner.

Naturvårdsverket tar inte ut någon avgift för att ansluta till API:et eller för att handlägga avtal.

Det är kostnadsfritt att ansluta till API:et, men kostnaden för respektive organisation att anpassa sina system är svår för Naturvårdsverket att uppskatta då det skiljer sig mycket åt.

Det krävs endast en anslutning per organisation.

Det finns ingen koppling mellan CFAR-nummer och auktorisering i API:et. CFAR-nummer är en uppgift som ska lämnas i samband med att avfall uppkommer, det vill säga för respektive avfallsproducent.

Om man lämnar in uppgifter via API får man en bekräftelse som bland annat innehåller avfalls-id. Det är upp till mottagande system att lagra dessa uppgifter och eventuellt skapa en pdf. Naturvårdsverket sammanställer ingen pdf för uppgifter inlämnade via API.

Ja, det går bra om man vill utveckla och testa en integration.

Det finns en checklista för vad som behöver finnas på plats för att ansluta till API:et. Om man inte kan bedriva utveckling själv, kan det vara bra att till exempel prata med sin systemleverantör eller andra aktörer som utvecklar it-system.

Checklista inför anslutning till avfallsregistrets API

1 timme, därefter behöver den förnyas. Denna funktion behöver byggas in i integrationen.

API-nyckeln är inte personlig utan ställs ut per organisation.

I dagsläget finns kodtabellerna inte på fil, men går lätt att kopiera från hemsidan. Avfallskoderna återfinns i avfallsförordningens bilaga 3.

Klientcertifikatet ska ligga på företagets server, så flera datorer kan använda samma certifikat.

Det kan se lite olika ut, men en tumregel är att om verksamhetsutövaren köper affärssystemet som en tjänst är det systemleverantörens ansvar. Om verksamhetsutövaren däremot köper tjänsteutveckling för att ta fram ett eget system, så är det verksamhetsutövarens ansvar att skaffa ett klientcertifikat.

Ja, dock kan man komma ganska långt genom att använda swagger-filen för att bygga en lokal tjänst som imiterar det riktiga API:et. Det finns flera verktyg som mer eller mindre automatiskt genererar en sådan tjänst.

Teknisk anslutning

Ja.

Ja, man kan skicka å, ä, ö i alla textfält, till exempel i adress eller organisationsnamn.

Det finns möjlighet att använda certifikatet Steria AB EID CA v2 med 2 års giltighet utfärdat av Expisoft. Se information om certifikat på sidan för AEAO.

Expisoft (expisoft.se)

API-anslutning

Företagets namn och organisationsnummer samt kontaktuppgifter enligt den standard som gäller för certifikatet. Certifikatet måste kunna användas för ”client authentication”. För QWAC behövs ej PSD2.

REST (Representational State Transfer) beskriver hur tjänster för maskin-till-maskin-kommunikation sätts upp. JSON (JavaScript Object Notation) är ett kompakt, textbaserat format som används för att utbyta data.