Hoppa till huvudinnehåll

ERP-integration: Skapa, signera och skicka eCoC i ett anrop

Låt ERP-systemet publicera eCoC till RDW, ansöka om registrering hos Transportstyrelsen (eReKo), eller båda, genom ett idempotent API-anrop.

Skrivet av Anton Hjalmarsson

Välj arbetsflöde

Hur eCoC:n kommer in (färdig fil eller endast VIN med mall) och vad som görs hos myndigheterna väljs var för sig. Varje anrop anger workflow:

workflow

Vad händer

Klart när

nap_only

eCoC skapas eller läses, signeras och skickas till RDW. Ingen registrering görs.

RDW har godkänt filen (nap_accepted)

ereko_only

Bara registreringsansökan skickas till Transportstyrelsen, som själva hämtar eCoC:n från EUCARIS.

Test: ansökan mottagen. Produktion: registrerad

nap_then_ereko

Båda stegen. Ansökan skickas först när RDW godkänt exakt den eCoC-filen.

Test: ansökan mottagen. Produktion: registrerad

Skickas inget workflow används nap_then_ereko.

  • Med nap_only skickar ERP inte vehicle_owner eller registration. Gör det ändå nekas anropet, så att ingen tror att en registrering gjorts.

  • Med ereko_only skapar, signerar eller skickar CertiDrive ingen eCoC, och eCoC:n behöver inte ha publicerats via CertiDrive. Skicka inte ivi_xml eller ecoc_fields. Typgodkännandenumret, fabrikatskoden, fordonsslaget och skyltformatet måste finnas i profilen eller i registration. Saknas eCoC:n hos EUCARIS visas Transportstyrelsens svar som ereko_rejected.

  • Vill ERP göra stegen vid olika tillfällen används två nycklar för samma order, till exempel ORDER-12345/NAP och ORDER-12345/EREKO, med samma external_reference.

  • Varje svar visar workflow, terminal (jobbet är klart) och completed_at. Vänta på "terminal": true.

Konfigurera CertiDrive

  1. Kontrollera certifikat, RDW, eReKo och företagets organisationsuppgifter.

  2. Öppna Företag → API-nyckel och skapa en testnyckel med ecoc:write och ecoc:read.

  3. Öppna Företag → Integrationer → ERP-integration.

  4. Aktivera integrationen.

  5. Välj vad ERP skickar:

    • Färdig eCoC-fil (IVI XML), eller

    • Endast VIN – CertiDrive använder mall och välj ett sparat IVI-meddelande.

  6. Välj om ERP ska fråga efter status eller ta emot webhook.

  7. Välj Spara.

  8. Lägg till en registreringsprofil för varje fordonstyp under Registreringsprofiler (se nedan).

  9. Kör GET /v1/readiness?workflow=nap_then_ereko (eller nap_only / ereko_only) med testnyckeln. Bara det arbetsflödet behöver visas. Åtgärda varje kontroll som har "ok": false och "required": true.

Registreringsprofiler

En registreringsprofil sparar de uppgifter till Transportstyrelsen som är lika för en fordonstyp: fordonsslag, fabrikatskod, typgodkännandenummer, typ av tillverkare och organisationsnummer, skyltformat, färg, gruppnummer, kommissionärsspärr och registreringsbevis. I läget Endast VIN kan profilen också ha en egen mall.

  1. Välj Ny profil under Registreringsprofiler i ERP-integrationskortet.

  2. Ange ett Profil-id, till exempel slap-750. Det är värdet ERP skickar i profile_id.

  3. Fyll i de uppgifter som är lika för alla fordon av typen. Lämna resten som Inte angivet.

  4. Välj Spara.

Varje uppgift tas i den här ordningen: från anropets registration, från profilen, från eCoC-filen (bara typgodkännandenumret, när filen har exakt ett, och inte med ereko_only) och från företaget (organisationsnumret för tillverkaren). Fordonsslaget gissas aldrig utifrån eCoC-filens fordonskategori, utan måste komma från profilen eller anropet. Svaret visar varifrån varje uppgift kom i registration_sources.

Uppgifterna kontrolleras mot Transportstyrelsens regler innan något skickas. Fordonsslaget är personbil, lastbil, buss eller slapvagn, och skyltformatet enradig, enradigLiten eller (bara bakre skylt) tvaradig. Ett otillåtet värde ger 422 validation_error med fältet och var värdet kom ifrån.

Testa ett anrop innan det skickas

Skicka samma innehåll, inklusive workflow, till POST /v1/ecoc-registrations/validate. Inget sparas, signeras eller skickas och ingen Idempotency-Key behövs. Bara det arbetsflödet använder kontrolleras. Svaret innehåller:

  • valid – true när anropet kan skickas,

  • errors – ett meddelande per fält som behöver rättas,

  • ecoc.xsd – kontrollen av eCoC-filen mot IVI 2.0-XSD:n,

  • ecoc.planned – versionsnumret som skulle användas, eller att RDW redan har godkänt exakt de uppgifterna (ecoc är tomt med ereko_only),

  • registration – de uppgifter som skulle skickas till Transportstyrelsen och varifrån de kom (tomt med nap_only).

Skapa ett jobb

Skicka POST /v1/ecoc-registrations med x-api-key, JSON och headern Idempotency-Key med ett unikt värde per ERP-order, till exempel ordernumret. Utan nyckel svarar API:t 400 idempotency_key_required.

  • Samma nyckel och samma innehåll ger tillbaka det befintliga jobbet med idempotent_replay: true. Ett omförsök skapar aldrig en dubblett.

  • Samma nyckel med annat innehåll, även ett annat workflow, ger 409 idempotency_conflict. Använd en ny nyckel för en ny beställning.

Minsta innehåll beror på arbetsflöde och inmatningsläge. Med nap_only behövs VIN och antingen ivi_xml eller en konfigurerad mall. Med ereko_only behövs VIN och fordonsägare (vehicle_owner). Med nap_then_ereko behövs alla tre. Med en registreringsprofil räcker profile_id; utan profil skickas uppgifterna till Transportstyrelsen i objektet registration.

Kedjan för nap_then_ereko är (med nap_only slutar den efter steg 3, med ereko_only görs bara steg 1, 5 och 6):

  1. validering av indata och konfiguration,

  2. signering med rätt versionsnummer och referens,

  3. sändning till RDW via National Access Point,

  4. kontroll att RDW godkänt exakt den filen,

  5. ansökan till Transportstyrelsen (eReKo),

  6. väntan på registreringsnummer (bara i produktion).

Versionsnumret följer fordonet per miljö på samma sätt som i CertiDrive. Ett fordon som aldrig skickats får version 1. Har RDW redan godkänt exakt samma uppgifter skickas filen inte igen och kedjan går direkt vidare till eReKo. Ändrade uppgifter får nästa version och ny referens. Acceptance-tester påverkar aldrig versionsnumren i Production.

I läget Färdig eCoC-fil sätter ERP själv versionsnummer och referens. Stämmer de inte med fordonets historik stoppas jobbet med ivi_version_conflict eller ivi_reference_conflict och det förväntade värdet, innan något skickas till RDW.

Ändra värden i mallen med ecoc_fields

I läget Endast VIN kan ERP skicka med de värden som skiljer sig från mallen för just det fordonet, till exempel tillverkningsdatum, vikter eller däck, i objektet ecoc_fields. Ett fält som skickas med ersätter mallens värde. Fält som inte skickas behåller mallens värde.

  • Nyckeln är det officiella elementnamnet i IVI 2.0, till exempel DateManufactureVehicle, MassInRunningOrder eller Remark.

  • Upprepade grupper som axlar, däck och kopplingar numreras från 1, till exempel AxleGroup[2]/TechnicallyPermissibleMassAxle eller AxleGroup[1]/TyreAxleGroup[1]/TyreSize.

  • Värdet är text eller ett tal. Decimaler skrivs med punkt, till exempel 14.1.

  • Bara värden som finns i mallen kan ersättas. Saknas ett avsnitt lägger du först till det i mallen i CertiDrive.

  • VIN skickas i vin. Versionsnummer, referens och tidpunkt sätts alltid av CertiDrive.

  • Är ett fält fel ersätts inget och svaret blir 422 validation_error med ett meddelande per fält, till exempel vilka numrerade axlar som finns.

  • Svaret innehåller ecoc_fields_applied med varje ersatt värde, tidigare värde och nytt värde.

  • GET /v1/template-fields visar för varje värde typen enligt IVI-XSD:n under xsd, till exempel längd, antal decimaler, min- och maxvärde eller tillåtna koder.

Hämta mallens nycklar och nuvarande värden med GET /v1/template-fields:

curl https://api.certidrive.se/v1/template-fields \
  -H "x-api-key: cd_test_xxxxxxxxxxxxxxxx"

Exempelanrop

Ett komplett anrop (nap_then_ereko) i läget Endast VIN med registreringsprofilen slap-750, där fyra värden ändras jämfört med mallen:

curl -X POST https://api.certidrive.se/v1/ecoc-registrations \
  -H "x-api-key: cd_test_xxxxxxxxxxxxxxxx" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: ORDER-12345" \
  -d '{
    "vin": "YSSA075N0TBK00089",
    "vehicle_owner": "5561234567",
    "external_reference": "ORDER-12345",
    "profile_id": "slap-750",
    "ecoc_fields": {
      "DateManufactureVehicle": "2026-10-27",
      "MassInRunningOrder": 185,
      "ActualMass": 185,
      "AxleGroup[1]/TyreAxleGroup[1]/TyreSize": "155/80R13"
    }
  }'

Utan profil skickas uppgifterna i registration, till exempel "registration": { "vehicle_type": "slapvagn", "make_code": "<fabrikatskod>", "rear_plate_format": "enradig" }. Uppgifter i registration gäller före profilens.

I läget Färdig eCoC-fil skickas hela filen i ivi_xml i stället för ecoc_fields.

Bara registreringsansökan, när eCoC:n redan finns hos EUCARIS:

curl -X POST https://api.certidrive.se/v1/ecoc-registrations \
  -H "x-api-key: cd_test_xxxxxxxxxxxxxxxx" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: ORDER-12345/EREKO" \
  -d '{
    "workflow": "ereko_only",
    "vin": "YSSA075N0TBK00089",
    "external_reference": "ORDER-12345",
    "profile_id": "slap-750",
    "vehicle_owner": "5561234567"
  }'

Bara publicering till RDW: skicka "workflow": "nap_only", VIN och ecoc_fields eller ivi_xml, men inte vehicle_owner eller registration.

Tolka svaret

POST svarar direkt med HTTP 202, headern Location med jobbets adress och Retry-After: 5. Vill ERP vänta på svaret skickar det Prefer: wait=20 (högst 25 sekunder). Är jobbet klart inom den tiden blir svaret HTTP 200. GET svarar alltid HTTP 200 med status i svaret. Fel i själva anropet, till exempel saknade fält, ger fortfarande HTTP 422 direkt och skapar inget jobb.

Status

Betydelse

accepted

Jobbet är skapat

ecoc_validating

Konfiguration kontrolleras

ecoc_signed

eCoC-filen är signerad och sparad

nap_submitting

Filen skickas till RDW

nap_accepted

RDW har godkänt filen. Slutstatus för nap_only

ereko_submitted

Ansökan är mottagen av Transportstyrelsen. Slutstatus i testmiljön

awaiting_registration

Transportstyrelsen handlägger, registreringsnummer kommer senare

registered

reg_number finns

action_required

En person behöver agera, se error

rejected

Uppgifterna avvisades. Rätta och skicka ett nytt anrop med ny nyckel

technical_failure

Tekniskt fel. Se retryable

Varje svar innehåller retryable. Är det true är ett nytt försök säkert. Svaret innehåller också job_id, steg, versionsnummer, referens och eventuellt fel. När RDW har godkänt filen finns länken ecoc_download_url. Hämta den godkända XML-filen med GET /v1/ecoc-registrations/{job_id}/ecoc, eller lägg till ?include=ecoc_xml i statusfrågan för att få filen direkt i svaret.

Status och återförsök

Hämta status med GET /v1/ecoc-registrations/{job_id} eller sök med GET /v1/ecoc-registrations?external_reference=ORDER-12345. Ett stoppat jobb återupptas med POST .../{job_id}/retry.

  • Den signerade filen sparas innan den skickas till RDW. Ett nytt försök skickar exakt samma fil med samma version och referens, aldrig en nysignerad.

  • Har RDW redan godkänt filen skickas den inte igen.

  • Bara ett återförsök körs åt gången. Skickas två samtidigt får det ena svaret 409 retry_in_progress.

  • Uteblir svaret från Transportstyrelsen vet ingen om ansökan kom fram. Jobbet får då action_required med felkoden ereko_outcome_unknown och skickas inte om automatiskt. Under error.details finns ts_caseid och ts_messageid, som sparas innan ansökan skickas. Använd dem för att kontrollera ansökan i eReKo eller hos Transportstyrelsen.

  • Registrera sedan resultatet med POST .../{job_id}/resolve:

    • { "resolution": "received", "case_reference_id": "<ärendets id>" } om ansökan kom fram. Jobbet kopplas till ärendet och inget skickas igen.

    • { "resolution": "not_received_and_may_resend" } om den inte kom fram. Skicka därefter POST .../{job_id}/retry, så skickas ansökan en gång till (med samma signerade eCoC när arbetsflödet publicerar en).

  • Ett jobb med status rejected kan inte återupptas. Rätta uppgifterna och skicka ett nytt anrop med en ny Idempotency-Key.

Viktigt att veta

ERP-flödet använder samma signerings-, RDW- och eReKo-implementation som användargränssnittet. Arbetsytan måste ha en owner/admin som kan agera för serverflödet och all underliggande konfiguration måste vara komplett.

Testa hela kedjan med cd_test_ innan en cd_prod_-nyckel används.

Status och registreringsnummer hämtas från Transportstyrelsen var 5:e minut, bara för ansökningar i produktion. Testansökningar frågas aldrig om status: ett testjobb är klart när Transportstyrelsen har tagit emot ansökan. Det kan därför ta upp till cirka 5 minuter innan ett nytt registreringsnummer syns i statusfrågan eller kommer via webhook.

Felsökning

Öppna ERP-anropslogg under integrationskortet. Där visas de senaste anropen med metod, adress, HTTP-status, felkod, steg och tid. XML-innehåll förkortas i loggen.

Relaterade artiklar
Fick du svar på din fråga?