Informasjon om eCoC

Vi kommer til å legge ut informasjon om innføring av ny løsning for innsendelse av samsvarserklæring eCoC på denne siden. Her vil du finne informasjon om hvordan løsningen er utviklet, presentasjoner fra informasjonsmøter og svar på spørsmål vi mottar fra dere som innsendere.

Tjeneste (Ny!)
Melding om preregistrering

Kontaktpersoner:

Presentasjon fra møte mandag 9. november:
Informasjonsmote_Innsendere_av_CoC_november_2020.pdf

Spørsmål og svar:
Sporsmal_og_Svar_fra_Informasjonsmoter.pdf

Nyttige linker:
Version 1.6 IVI Messagebook
Version 1.6 Initial Vehicle Information XSD Scheme
Version 1.6 Initial Vehicle Information Excel Overview
Version 1.6 IVI Release Notes
Version 1.6.1 IVI Content Check Module (ICM) - Functional description

API

Tjeneste "Melding om preregistrering" tilbyr importører muligheten for innsending av eCOC (elektronisk COC) fra fabrikant til Statens Vegvesen.

Tjeneste "Slette tidligere innsendt COC" tilbyr importører muligheten for å slette tidligere innsendt eCOC.

Tilgangsstyring

Tilgangstyring til APIet er basert på bruk av Maskinporten som autentiserings- og autorisasjonstjener for maskin-til-maskin grensesnitt.

Teknisk Dokumentasjon

Tjenesten som tilbys er en REST-tjeneste hvor IVI-dokumentet (XML-format) sendes med i REST-kallet som en tekststreng encoded med base-64.

Dokumentasjon	Lenke	Open API-fil (sist oppdatert 28.01.2021)
REST-API	Innmelding API	Last ned

Opprette melding om preregistrering

Her er et eksempel på POST request ved opprette melding om preregistrering.

POST	https://[env]/ws/no/vegvesen/kjoretoy/felles/innmelding/meldingompreregistrering/v1/opprette

Hvor:

[env] er en miljøspesifikk adresse

Header

Content-Type	application/json
Authorization	Bearer < token >

Hvor:

< token > er en JWT-basert aksess-token. Se info om maskinporten .

Body

[
    {
        "avgiftsklassifisering": {
        "avgiftsKode": "101"
      },
        "ivi": {
            "iviDokument": "IVI dokument base64EncodedXML"
      }
    }
]

Eksempel på respons - suksessmelding

Her er et eksempel på respons opprette melding om preregistrering - suksessmelding med eksempel på advarsel (som ikke stopper opprettelse av coc/kjøretøy).

[
{
    "datoTid": "2021-02-08T21:23:18.812",
    "iviIdentifikator": {
        "kuid": "xxxxxxxxxx",
        "iviReferanse": "3a0f9b22-a855-4933-bf78-959128c2a5d3",
        "understellsnummerMerke": {
            "understellsnummer": "DOKUMENTASJONDEMO",
            "merkekode": 2600
        }
    },
    "melding": {
        "meldingstype": "INFO",
        "meldingskode": "kjoretoy.coc.KJORETOY_OPPRETTET",
        "meldingstekst": "Melding om preregistrering er mottatt og kjøretøy er opprettet"
            {
                "melding": "Er det korrekt at NOx (mg/km) ikke er utfylt?",
                "feltreferanse": "utslippNOxMgPrKm",
                "feltverdi": null,
                "meldingsklasse": "ADVARSEL"
            }
        ]
    }
}
]

Eksempel på respons - feilmelding

Her er et eksempel på respons opprette melding om preregistrering - feilmelding hvor opprettelse coc/kjøretøy ikke ble gjennomført.

[
{
    "datoTid": "2021-02-08T21:36:47.511",
    "iviIdentifikator": {
        "kuid": null,
        "iviReferanse": null,
        "understellsnummerMerke": {
            "understellsnummer": null,
            "merkekode": null
        }
    },
    "melding": {
        "meldingskode": "kjoretoy.coc.KJORETOY_KAN_IKKE_AVGIFTSKLASSIFISERES",
        "meldingstekst": "Ulovlig forespørsel - Fant ingen åpne eller lukkede avgiftsklassifiseringer på typegodkjenning: < TYPEGODKJENNINGSNR. > | < VARIANT > | < VERSJON > tilgjengelig for importør: < xxxxxxxxx > med ønsket avgiftskode: < xxx > .",
        "meldingstype": "FEIL"
    }
}
]

Request for å slette melding om preregistrering

Her er et eksempel på DELETE forespørsel om å slette en tidligere innsendt melding om preregistrering.

DELETE

https://[env]/ws/no/vegvesen/kjoretoy/felles/innmelding/meldingompreregistrering/v1/slette/ivireferanse/{iviReferanse}

Hvor:

[env] er en miljøspesifikk adresse
{iviReferanse} er Ivi-referanse eller Understellsnummer eller Understellsnummer og merkekode. Merkekode er påkrevd i kombinasjon med understellsnummer der understellsnummer ikke gir ett treff

Header

Content-Type	application/json
Authorization	Bearer < token >

Hvor:

< token > er en JWT-basert aksess-token. Se info om maskinporten .

Eksempel på respons - suksessmelding

Her er et eksempel på suksessmelding ved sletting av preregistrering.

{
    "datoTid": "2021-02-08T21:41:33.15",
    "iviIdentifikator": {
        "kuid": "xxxxxxxxxx",
        "iviReferanse": null,
        "understellsnummerMerke": {
            "understellsnummer": "DOKUMENTASJONDEMO",
            "merkekode": null
        }
    },
    "melding": {
        "meldingskode": "kjoretoy.coc.KJORETOY_SLETTET",
        "meldingstekst": "Forespørsel om sletting av COC er mottatt og COC er slettet.",
        "meldingstype": "INFO"
    }
}

Her er et eksempel på feilmelding ved sletting av preregistrering når vi ikke har nok info til å identifisere coc som forespørselen forsøker å slette.

{
    "datoTid": "2021-02-08T21:17:51.385",
    "iviIdentifikator": {
       "kuid": null,
       "iviReferanse": null,
       "understellsnummerMerke": {
           "understellsnummer": "DOKUMENTASJONDEMO",
           "merkekode": null
       }
    },
    "melding": {
       "meldingskode": "kjoretoy.coc.UKJENT_UNR_OG_MERKE",
       "meldingstekst": "COC med angitt understellsnummer/merke er ukjent.",
       "meldingstype": "FEIL"
    }
}

Her er et eksempel på feilmelding ved sletting av preregistrering når kjøretøyet har åpen registreringssak eller er registrert.

{
    "datoTid": "2021-02-08T21:32:43.896",
    "iviIdentifikator": {
       "kuid": null,
       "iviReferanse": null,
       "understellsnummerMerke": {
           "understellsnummer": "DOKUMENTASJONDEMO",
           "merkekode": null
       }
    },
    "melding": {
       "meldingskode": "kjoretoy.coc.KJORETOY_ER_REGISTRERT",
       "meldingstekst": "Kjøretøyet er registrert eller under registrering",
       "meldingstype": "FEIL"
    }
}

Maskinporten

Staten vegvesen benytter Maskinporten for virksomhetsautorisering og tilgangsstyring for flere tjenester, som tilbys via maskin-til-maskin-grensesnitt. Du kan lese mer om Maskinporten på Digdir .

Potensielle brukere av tjenestene som Statens vegvesen tilbyr via Maskinporten er:

Konsument
Konsument, som skal delegere rettighet til en leverandør
Leverandør, som kommuniserer på vegne av en konsument

Det forutsettes at brukere av tjenestene setter seg godt inn i dokumentasjonen for Maskinporten.

Når konsument eller leverandør er et utenlandske foretak

Hvis importør eller leverandør ikke har norsk organisasjonsnummer i Brønnøysundregistrene, må virksomheten først registreres som et norskregistrert utenlandsk foretak (NUF) for å kunne bruke Maskinporten. Når virksomheten er registrert som et NUF, følg vanlig prosedyre for å ta i bruk Maskinporten som konsument, konsument – delegert til leverandør eller leverandør.

Ta i bruk Maskinporten som konsument

Hvis virksomheten skal sende inn eCOC som konsument på vegne av seg selv, følg fremgangsmåten her for å få tilgang.

Ta i bruk Maskinporten

Følg stegene på Digdir ta i bruk Maskinporten som konsument.

Avtale med Statens vegvesen

API-konsumenten må inngå avtale med Statens vegvesen om innsending av eCOC for å få tilgang til å sende inn eCOC via API. Inntil videre inngås avtale manuelt ved å sende forespørsel til brukerstotte@vegvesen.no .

Slik bruker du Maskinporten som API-konsument

Når virksomheten har inngått avtale om innsending av eCOC, gir Statens vegvesen virksomheten tilgang til relevant scope i Maskinporten. Konsumenten må opprette en Maskinporten-integrasjon som har det aktuelle APIet sitt scope registrert.

Etter registrering kan klienten brukes for å be om token og gjennomføre API-kallene.

Be om token

Konsumenten sin klient forespør et access_token fra Maskinporten ved å generere en JWT-basert tokenforespørsel (JWT-bearer authorization grant). Forespørselen må blant annet inneholde:

i. resource: https://www.vegvesen.no/
ii. svv:kjoretoy/ecoc

Maskinporten vil først validere gyldigheten av JWT-tokenet. Deretter vil virksomhetssertifikatet (brukt til signering av JWT-tokenet) valideres og dersom klienten har tilgang til de forespurte ressursene returneres et access_token til klienten.

Sende API-kall med token

Klienten kan nå sende API-kall med det utstedte tokenet.

Tokenet legges ved kallet til Statens vegvesen i Authorization header.
Tokenet legges ved slik:
Authorization: Bearer < token >

Når tokenet er utløpt må det genereres en ny tokenforespørsel til Maskinporten.

Ta i bruk Maskinporten som API-konsument – delegert til leverandør

Det er et par steg du som konsument må gjennomføre før en leverandør kan sende inn eCOC på vegne av deg til Statens vegvesen.

Ta i bruk Maskinporten

Følg stegene på ta i bruk Maskinporten som konsument – delegert til leverandør. Du som konsument må blant annet logge inn i Altinn og delegere tilgang til API-ressursen til leverandøren. Navn på relevant API-ressurs kommer her.

Se Digdirs dokumentasjon for å bruke delegering via Altinn autorisasjon .

Avtale med Statens vegvesen

Hvis virksomheten du representerer skal delegere innsending av eCOC til en annen virksomhet, trenger virksomheten du representerer også å inngå en brukeravtale med Statens vegvesen. Inntil videre inngås avtale manuelt ved å sende forespørsel til brukerstotte@vegvesen.no .

Ta i bruk Maskinporten som leverandør (på vegne av konsument)

Hvis virksomheten skal sende inn eCOC som leverandør på vegne av konsument, følg fremgangsmåten her for å få tilgang.

Ta i bruk Maskinporten

Følg stegene på ta i bruk Maskinporten som leverandør.

Avtale med Statens vegvesen

API-leverandøren må inngå avtale med Statens vegvesen for å få tilgang til å sende inn eCOC via API. Inntil videre inngås avtale manuelt ved å sende forespørsel til brukerstotte@vegvesen.no .

Slik bruker du Maskinporten som API-leverandør

En forutsetning for at du som leverandør skal kunne opprette en integrasjon med Maskinporten, er at konsumenten har delegert relevant API-ressurs i Altinn til deg som leverandør. Leverandør-integrasjoner som skal bruke ekstern delegering, er litt forskjellige fra andre integrasjoner i Maskinporten. Les mer på Digdir om å bruke delegering som leverandør .

Opprett en integrasjon i Maskinporten

Be om token

Konsumenten sin klient forespør et access_token fra Maskinporten ved å generere en JWT-basert tokenforespørsel (JWT-bearer authorization grant). Forespørselen må blant annet inneholde:

i. resource: https://www.vegvesen.no/
ii. scope: svv : kjoretoy/ecoc.delegert
iii. consumer.org : < konsumentens org.nr. >

Sende API-kall med token

Klienten kan nå sende API-kall med det utstedte tokenet .

Tokenet legges ved kallet til Statens vegvesen i Authorization header.
Tokenet legges ved slik:
Authorization: Bearer < token >

Når tokenet er utløpt må det genereres en ny tokenforespørsel til Maskinporten.