Hoppa till huvudinnehåll

ERP-integration: Skapa, signera och skicka eCoC i ett anrop (`erp-ecoc`)

Låt ERP-systemet validera, signera och skicka eCoC till RDW samt skapa eReKo-registreringen genom ett idempotent API-anrop.

Skrivet av Anton Hjalmarsson

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.

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 ger 409 idempotency_conflict. Använd en ny nyckel för en ny beställning.

Minsta innehåll beror på valt inmatningsläge. Anropet behöver VIN, extern referens och antingen ivi_xml eller en konfigurerad mall. Objektet registration innehåller bland annat fordonsägare, fordonstyp, fabrikatskod, typgodkännande, skyltformat och tillståndshavare.

Kedjan är:

  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.

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.

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

curl https://mzzkzmrhnkhmowrlypmy.supabase.co/functions/v1/erp-ecoc/v1/template-fields \
  -H "x-api-key: cd_test_xxxxxxxxxxxxxxxx"

Exempelanrop

Ett komplett anrop i läget Endast VIN där fyra värden ändras jämfört med mallen:

curl -X POST https://mzzkzmrhnkhmowrlypmy.supabase.co/functions/v1/erp-ecoc/v1/ecoc-registrations \
  -H "x-api-key: cd_test_xxxxxxxxxxxxxxxx" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: ORDER-12345" \
  -d '{
    "vin": "YSSA075N0TBK00089",
    "external_reference": "ORDER-12345",
    "ecoc_fields": {
      "DateManufactureVehicle": "2026-10-27",
      "MassInRunningOrder": 185,
      "ActualMass": 185,
      "AxleGroup[1]/TyreAxleGroup[1]/TyreSize": "155/80R13"
    },
    "registration": {
      "vehicle_owner": "5561234567",
      "vehicle_type": "O1",
      "make_code": "<fabrikatskod>",
      "type_approval_number": "e5*2007/46*0011*07",
      "rear_plate_format": "<skyltformat>",
      "commissioner_block": false,
      "issue_registration_certificate": true,
      "holder_type": "professionalManufacturer"
    }
  }'

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

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). Har kedjan stoppat 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

ereko_submitted

Ansökan är mottagen av Transportstyrelsen

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.

  • 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. 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?