REALT-8982: Dokumentasjon av Drosjetjenester m2m API #29
+272
−1
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,269 @@ | ||
| --- | ||
| 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 | ||
| --- | ||
|
|
||
| <Summary>Tjeneste for innrapportering av tredjepartsopplysninger for drosjetjenester (RF-1301)</Summary> | ||
|
|
||
| <Tabs underline={true}> | ||
| <TabItem headerText="Om tjenesten" itemKey="itemKey-1" default> | ||
|
|
||
| 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](drosjetjenester?tab=Feilkoder) for | ||
| relaterte feilmeldinger. | ||
|
|
||
| Se også [eksempler](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. | ||
|
|
||
| </TabItem> | ||
| <TabItem headerText="Eksempler" itemKey="itemKey-2"> | ||
|
|
||
| ## 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 | ||
| } | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| <TabItem headerText="Feilkoder" itemKey="itemKey-3"> | ||
|
|
||
| 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 autentisesring | | ||
| | 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 | | | ||
|
|
||
| </TabItem> | ||
| <TabItem headerText="Informasjonsmodell" itemKey="itemKey-4"> | ||
|
|
||
|  | ||
|
|
||
| | Eier | Element | Dokumentasjon | | ||
| |---------------------------|---------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | Melding | leveranse | Selve leveransen. Merk at det kun er tillatt med en leveranse pr Melding | | ||
| | Leveranse | inntektsaar | Inntektsåret leveransen gjelder | | ||
| | Leveranse | kildesystem | System brukt for å levere oppgaven | | ||
| | Leveranse | leveransetype | Type av leveranse som angir om leveransen inneholder ordinære oppgaver eller om oppgavegiver angir at det ikke er noen oppgaver å innrapportere | | ||
| | Leveranse | oppgave | Oppgave som leveres | | ||
| | Leveranse | oppgavegiver | Tredjepart som rapporterer opplysning til Skatteetaten | | ||
| | Leveranse | oppgavegiversLeveranseReferanse | Frivillig referanse på innsendingen til bruk mot egne interne systemer og evt. support mot skattetaten | | ||
| | Leveranse | oppgaveoppsummering | Oppsummering med totalsummer for innleverte oppgaver | | ||
| | OppgaveDrosje | kilometerBesatt | Besatte kilometer. Verdien oppgis i hele kilometer | | ||
| | OppgaveDrosje | kilometerKjørt | Kjørte kilometer. Verdien oppgis i hele kilometer | | ||
| | OppgaveDrosje | kontantomsetningEksMva | Kontantomsetning eksklusive mva. Beløpet oppgis i hele kroner | | ||
| | OppgaveDrosje | kredittomsetningEksMva | Kredittomsetning eksklusive mva. Beløpet oppgis i hele kroner | | ||
| | OppgaveDrosje | løyvenummer | Drosjeløyve | | ||
| | Oppgaveeier | organisasjonsnummer | Oppgaveeiers organisasjonsnummer | | ||
| | Oppgaveeier | navn | Navn på oppgaveeier | | ||
| | Oppgavegiver | kontaktinformasjon | Kontaktinformasjon for oppgavegiver | | ||
| | Oppgavegiver | organisasjonsnummer | Organisasjonsnummer på oppgavegiver | | ||
| | OppgaveoppsummeringDrosje | antallOppgaver | Totalt antall oppgaver i leveransens oppgaver | | ||
| | OppgaveoppsummeringDrosje | sumKilometerBesatt | Sum av alle kilometerBesatt-verdiene i oppgavene til en leveranse | | ||
| | OppgaveoppsummeringDrosje | sumKilometerKjørt | Sum av alle kilometerKjørt-verdiene i oppgavene til en leveranse | | ||
| | OppgaveoppsummeringDrosje | sumKontantomsetningEksMva | Sum av alle kontantomsetningEksMva-verdiene i oppgavene til en leveranse | | ||
| | OppgaveoppsummeringDrosje | sumKredittomsetningEksMva | Sum av alle kredittomsetningEksMva-verdiene i oppgavene til en leveranse | | ||
|
There was a problem hiding this comment. Tenker det går fint å fjerne hele tabellen, men legg kanskje inn "Informasjonsmodell" som overskrift over bildet There was a problem hiding this comment. Tenker vi at tabellen er unødvendig? |
||
| </TabItem> | ||
|
|
||
| <TabItem headerText="Test" itemKey="itemKey-5"> | ||
|
|
||
| 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-skattefrie-utbetalinger-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 | ||
|
There was a problem hiding this comment. Syns denne setningen kan være litt misvisende. Kan tolkes som at man ikke får testet tjenesten, men det betyr jo bare at det ikke er ferdig generert noe testdata her. Lurer også på om man burde nevnt at oppgavegiver må eksistere i oppgaveregisteret for at innsendingene ikke skal bli avvist. There was a problem hiding this comment. @thomasaasen Noen tanker rundt det siste punktet jeg skrev. Burde vi evt hatt noe felles om testdata ett sted som beskriver dette? |
||
| tilgjengelig. | ||
|
|
||
| </TabItem> | ||
| <TabItem headerText="Kontakt oss" itemKey="itemKey-6"> | ||
|
|
||
| Har du spørsmål til Skatteetaten om Skattefrie utbetalinger fra offentlige myndigheter 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. | ||
|
|
||
| </TabItem> | ||
| </Tabs> | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
There was a problem hiding this comment. Det er skrivefeil i figuren (*EkslMva), men det finnes ikke oppdatert figur PT. |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
en ekstra s som har sneket seg inn her i autentisesring