diff --git a/docs/anvendelsesomraader/innrapportering-tredjepartsopplysninger.md b/docs/anvendelsesomraader/innrapportering-tredjepartsopplysninger.md index 37cc055a957..69f88f77956 100644 --- a/docs/anvendelsesomraader/innrapportering-tredjepartsopplysninger.md +++ b/docs/anvendelsesomraader/innrapportering-tredjepartsopplysninger.md @@ -33,4 +33,5 @@ Følgende API-er er tilgjengelige pr. nå: * [Innrapportering innskudd_utlaan_renter API](../api/innrapportering-innskuddutlaanrenter.md) * [Innrapportering tilskudd API](../api/innrapportering-tilskudd.md) * [Innrapportering betalinger_naeringsdrivende API](../api/innrapportering-betalingernaeringsdrivende.md) +* [Innrapportering drosjetjenester API](../api/innrapportering-drosjetjenester.md) diff --git a/docs/api/innrapportering-drosjetjenester.md b/docs/api/innrapportering-drosjetjenester.md new file mode 100644 index 00000000000..db919184e77 --- /dev/null +++ b/docs/api/innrapportering-drosjetjenester.md @@ -0,0 +1,245 @@ +--- +title: Innrapportering Drosjetjenester API +slug: /api/innrapportering-drosjetjenester +folder: api +sidebar: mydoc_sidebar +datatable: true +tags: [ API, drosjetjenester, drosjesentraler] +keywords: [ grunnlagsdata ] +last_updated: Mar 10, 2025 +hide_table_of_contents: true +--- + +Tjeneste for innrapportering av tredjepartsopplysninger for drosjetjenester (RF-1301) + + + + +For generell informasjon om tjenestene se egne sider om: + +* [Bruk av tjenestene](../om/bruk.md) +* [Sikkerhetsmekansimer](../om/sikkerhet.md) +* [Systemtilgang](../om/systemtilgang.md) +* [Feilhåndtering](../om/feil.md) +* [Versjonering](../om/versjoner.md) +* [Teknisk spesifikasjon](../om/tekniskspesifikasjon.md) + +## Scope + +Følgende scope skal benyttes ved autentisering i Maskinporten: `skatteetaten:innrapporteringdrosjetjenester` + +## Delegering + +Tilgang til dette API-et kan delegeres i Altinn, f.eks. dersom leverandør benyttes for den tekniske oppkoblingen. + +## Systemtilgang + +Bruk av API-et krever systemtilgang, som er ny funksjonalitet i Maskinporten levert av Digdir. +Informasjon vedr. dette finnes [her](../om/systemtilgang.md). + +For å kunne benytte dette api-et med systemtilgang må man gi følgende rettighet til systemet ved opprettelse i systemregisteret: +```JSON +"Rights": [ + { + "Resource": [ + { + "value": "ske-innrapportering-drosjetjenester", + "id": "urn:altinn:resource" + } + ] + } + ] +``` + +## Teknisk spesifikasjon + +URL-er til API-et, beskrivelse av parametre, endepunkter og respons ligger i Open API-spesifikasjonen på +[SwaggerHub](https://app.swaggerhub.com/apis/skatteetaten/innrapportering-drosjetjenester-api/0.0.1) + +Nødvendige åpninger i en evt. brannmur er beskrevet [her](../om/sikkerhet.md) + +API-et for innrapportering av tredjepartsopplysninger for drosjetjenester til offentlige myndigheter har to endepunkter: + +* __POST innsending__: Innsending av tredjepartsopplysninger for drosjesentraler til offentlige myndigheter. Et kall mot API-et er en rapportering for en organisasjon gitt av en oppgavegiver og som gjelder et inntektsår. +* __GET uthenting_dokument__: Henter ut et spesifikt dokument knyttet til en transmission (forsendelse) i Dialogporten + +API-et validerer mottatte data mot JSON-schema beskrevet på SwaggerHub. Se [feilkoder](innrapportering-drosjetjenester?tab=Feilkoder) for +relaterte feilmeldinger. + +Se også [eksempler](innrapportering-drosjetjenester?tab=Eksempler) for de ulike endepunktene. + +### Parameter: idempotencyKey + +`idempotencyKey`-parameteren er påkrevet. Innholdet skal være en unik `UUID`. Hvert nye kall til API-et skal ha en +tilsvarende ny idempotencyKey. Flere etterfølgende `POST` kall med samme request-body og samme `idempotencyKey` vil gi den +samme responsen. Kun det første av denne rekken med like API kall vil behandles. `idempotencyKey` muliggjør at man trygt +kan prøve innsendinger på nytt der man av ulike årsaker ikke har fått en tilbakemelding fra API-et. + +## Datakatalog + +Dette API-et er pt. ikke dokumentert i Felles datakatalog. + + + + +## Innsending + +### Eksempel på request-URL + +``` +https://innrapporteringdrosjetjenester.api.{env}.no/v1/{inntektsaar} +``` + +### JSON + +#### Eksempel på innsending + +```json +{ + "leveranse": { + "kildesystem": "Kildesystemet v2.0.5", + "oppgavegiver": { + "organisasjonsnummer": "987654321", + "kontaktinformasjon": { + "navn": "Kari Kontakt", + "telefonnummer": "80080000", + "varselEpostadresse": "kontakt@drosjesentralen.no", + "varselSmsMobilnummer": "80080000" + } + }, + "inntektsaar": 2024, + "oppgavegiversLeveranseReferanse": "REF_2013_1", + "leveransetype": "ordinaer", + "oppgave": [ + { + "oppgaveeier": { + "organisasjonsnummer": "987564231", + "navn": "Thomas Drosjeeier" + }, + "loeyvenummer": "02011234", + "kontantomsetningEksMva": 30000, + "kredittomsetningEksMva": 10000, + "kilometerKjoert": 4000, + "kilometerBesatt": 2000 + }, + { + "oppgaveeier": { + "organisasjonsnummer": "987564231", + "navn": "Unn Drosjeeier" + }, + "loeyvenummer": "020145687", + "kontantomsetningEksMva": 50000, + "kredittomsetningEksMva": 20000, + "kilometerKjoert": 5000, + "kilometerBesatt": 3000 + } + ], + "oppgaveoppsummering": { + "antallOppgaver": 2, + "sumKontantomsetningEksMva": 80000, + "sumKredittomsetningEksMva": 30000, + "sumKilometerKjoert": 9000, + "sumKilometerBesatt": 5000 + } + } +} +``` + +#### Eksempel på respons + +```json +{ + "dialogId": "0193b5cd-cb85-7320-bd8c-6c78c88dc8af", + "forsendelseId": "0193b5cd-cbce-7dbd-b188-1437db673767", + "oppgavegiversLeveranseReferanse": "EksternReferanse_2013_1", + "antallOppgaver": 2 +} +``` + + + + +Se egen side for generell info om [feilhåndtering i tjenestene](../om/feil.md). + +Tabellen under viser en oversikt over hvilke spesifikke feilkoder denne tjenesten kan gi. + +| Feilkode | HTTP Statuskode | Feilområde | +|----------|-----------------|----------------------------------------------| +| GLD_001 | 500 | Uventet feil på tjenesten | +| GLD_004 | 401 | Feil i forbindelse med autentisering | +| GLD_005 | 403 | Feil i forbindelse med autorisering | +| GLD_006 | 400 | Feil i request | +| GLD_008 | 400 | Strukturell feil i tilknyttet dataformat | +| GLD_010 | 400 | Feil i forbindelse med validering av payload | +| GLD_011 | 400 | Feil i metadata | +| GLD_017 | 500 | Uspesifisert systemfeil | +| GLD_019 | 409 | Idempotensnøkkel er benyttet tidligere | +| GLD_021 | 404 | Finner ikke forespurt ressurs | +| GLD_022 | 405 | HTTP-metode ikke støttet | +| GLD_023 | 500 | Uventet feil i et bakenforliggende system | + +Feilresponsene kan også inneholde en feilspesifiseringskode som presiserer feilen ytterligere. +Tabellen under viser hvilke feilspesifiseringskoder tjenesten kan gi. +Dersom det finnes mer detaljert feilinformasjon enn generelt feilområde vil det beskrives i melding, sti og +angitt verdi-feltene. + +| Feilspesifiseringskode | Feilområde | Årsak | +|------------------------|---------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------| +| GLD_1007 | Mangler Token | Det er ikke lagt ved noen Authorization header med token på request | +| GLD_1008 | Ugyldig token | Token oppgitt i Authorization header er ugyldig | +| GLD_1015 | Ikke autorisert for å levere på denne dialogen | Organisasjonen som leverer har ikke rettighet til å levere for denne oppgavegiveren | +| GLD_1022 | Feil i parametre | Diverse feil med parametre i request. Mer detaljert beskrivelse ligger i melding, sti og angitt verdi dersom det er aktuelt | +| GLD_1023 | Finner ingen ressurs for denne URL-en | Det er ikke noe innhold tilgjengelig på denne URL-en | +| GLD_1027 | Inntektsår er ikke støttet | Det er ikke tillatt å levere på oppgitt inntektsår | +| GLD_1028 | Header mangler | Påkrevd header er ikke med i requesten | +| GLD_1030 | Accept-header må være av type application/json | Accept header er feil. API-et har kun støtte for JSON i respons | +| GLD_1050 | Finner ikke et dokument med denne IDen på denne forsendelsen | Det finnes ikke noe dokument med gitt id på angitt forsendelse | +| GLD_1052 | Inntektsår i path og i innsending er ulike | Inntektsår i innsending i JSON body og inntektsår i path må være like | +| GLD_1053 | Uventet feil i et bakenforliggende system, vennligst prøv igjen senere | | +| GLD_1054 | Det finnes ingen dialog for denne kombinasjonen av inntektsår, organisjonsnummer og ordning | | + + + + +![Informasjonsmodell Drosjesentraler](../../static/download/Informasjonsmodell_Drosjesentraler.png) + + + + + +I første omgang er test kun tilgjengelig for et utvalg leverandører som det er inngått avtale med og som skal være +med å pilotere løsningene. + +### Testmiljøer + +For spesifikke URL-er til testmiljø hos Skatteetaten, se [SwaggerHub](https://app.swaggerhub.com/apis/skatteetaten/innrapportering-drosjetjenester-api/0.0.1). + +Digdir benytter TT02 som testmiljø, hvor følgende tilbys: +* DialogPorten +* Autentisering - Maskinporten +* Autorisering - systembruker +* Altinn innboks + +Konsumenter må ha egne testmiljøer som kan kobles mot testmiljøer hos Skatteetaten og Digdir. + +### Tenor testdatasøk + +Det finnes pt. ikke søk i [Tenor](https://github.com/Skatteetaten/api-dokumentasjon/blob/main/docs/test/tenor.md) for +denne tjenesten. Men egenskaper ved enhetene som har testdata kan søkes frem i Tenor. + +### Testdata + +Det skal utelukkende benyttes syntetiske testdata ved test av tjenesten. Tenor testdatasøk tilbyr dette. +Det er ikke tillatt å bruke/sende skarpe data i test pga krav fra GDPR-regelverket. + +Det finnes foreløpig ingen testdata for denne tjenesten. Denne siden oppdateres fortløpende ettersom testdata blir +tilgjengelig. + + + + +Har du spørsmål til Skatteetaten om Innrapportering Drosjetjenester API, kan du sende oss e-post: [altinnreetablering\@skatteetaten.no](mailto:altinnreetablering@skatteetaten.no) +Vær oppmerksom på at epostadressen er midlertidig og gjelder bare i perioden tjenestene er i utvikling og test fra Altinn II til Altinn 3. + + + diff --git a/sidebars.js b/sidebars.js index f27bcdf6f21..e9326a5eb84 100644 --- a/sidebars.js +++ b/sidebars.js @@ -62,8 +62,9 @@ const sidebars = { "api/innrapportering-boligsameie", "api/innrapportering-boligselskap", "api/innrapportering-bsu", - "api/innrapportering-innskuddutlaanrenter", + "api/innrapportering-drosjetjenester", "api/innrapportering-gavertilfrivillige", + "api/innrapportering-innskuddutlaanrenter", "api/innrapportering-passogstell", "api/innrapportering-tilskudd", "api/mvameldinginnsending", diff --git a/static/download/Informasjonsmodell_Drosjesentraler.png b/static/download/Informasjonsmodell_Drosjesentraler.png new file mode 100644 index 00000000000..d03b6744104 Binary files /dev/null and b/static/download/Informasjonsmodell_Drosjesentraler.png differ