Merge pull request #38 from Skatteetaten/FIGO-555-oppdater-beskrivels…

…e-av-tjenester

Figo 555 oppdater beskrivelse av tjenester

docs/innkrevingsoppdrag/anbefalinger-for-bruk.md

@@ -1,12 +1,16 @@
 # Anbefalinger for bruk
 
-Denne siden gir anbefalinger for bruk av Skatteetatens (SKE) tjenester for oppdragsinnkreving. For å sikre effektiv
+Denne siden gir anbefalinger for bruk av Skatteetatens (SKE) tjenester for oppdragsinnkreving.
+
+## Etablere datalager for data som overføres til Skatteetaten
+
+For å sikre effektiv
 håndtering og etterlevelse av Reglement for økonomistyring i staten, anbefales det å etablere et datalager for alle data
 som overføres til Skatteetaten. Dette datalageret bør inkludere:
 
 - Skatteetatens kravidentifikator, som mottas i retur
   ved [opprettelse av et innkrevingsoppdrag](beskrivelse-av-tjenester.md#opprett-et-innkrevingsoppdrag) hos SKE.
-- Mottaksstatus, i henhold til [flyt for mottaksbekreftelse](mottaksbekreftelse.md).
+- Mottaksstatus, i henhold til [flyt for mottaksbekreftelse](beskrivelse-av-tjenester.md#hent-mottaksbekreftelse).
 - Kravgrunnlaget, eller en referanse til dette.
 - [Avstemmingsinformasjon](beskrivelse-av-tjenester.md#avstemming-av-et-innkrevingsoppdrag).
 
@@ -15,3 +19,13 @@ Skatteetaten tar vare på kravidentifikatoren de mottar i retur. Denne identifik
 transaksjonskontrollen, bidrar til å sikre sporbarheten til kravet. Ved å ta vare på kravidentifikatoren, kan
 oppdragsgiveren effektivt følge opp og verifisere statusen på det aktuelle kravet.
 
+## Fyll ut feltet `oppdragsgiversKravidentifikator` i `OpprettInnkrevingsoppdragRequest`
+
+I tillegg vil vi anbefale å fylle ut feltet `oppdragsgiversKravidentifikator` i `OpprettInnkrevingsoppdragRequest`
+-objektet ved [opprettelse av innkrevingsoppdrag](beskrivelse-av-tjenester.md#opprett-et-innkrevingsoppdrag) med en unik
+identifikator. Dette muliggjør å følge mønsteret
+for [feilhåndtering ved opprettelse av krav](beskrivelse-av-tjenester.md#feilhåndtering), ettersom løsningen sikrer
+unikhet på feltet `oppdragsgiversKravidentifikator`. Dersom man ikke har en unik identifikator her, kan man for eksempel
+bruke en identifikator fra overføringstabellen sin.
+
+

docs/innkrevingsoppdrag/beskrivelse-av-tjenester.md

@@ -1,76 +1,149 @@
 # Beskrivelse av tjenester
 
-Lenke til API-dokumentasjonen finnes i menyen til venstre.
-Under følger en beskrivelse av hvordan de ulike tjenestene brukes, og eventuelle hensyn som må tas.
+Lenke til API-dokumentasjonen finnes i menyen til venstre. Under følger en beskrivelse av hvordan de ulike tjenestene
+brukes, og eventuelle hensyn som må tas.
+
+*Seksjonen vil utvides etter hvert som flere oppdragsgivere og typer krav støttes.*
 
 ## Innholdsfortegnelse
 
-- [Opprett et innkrevingsoppdrag](#opprett-et-innkrevingsoppdrag)
-    - [Validering](#validering)
-    - [Feilhåndtering](#feilhåndtering)
-- [Endre et innkrevingsoppdrag](#endre-et-innkrevingsoppdrag)
-    - [Validering](#validering-1)
-    - [Feilhåndtering](#feilhåndtering-1)
-- [Avskriv et innkrevingsoppdrag](#avskriv-et-innkrevingsoppdrag)
-    - [Validering](#validering-2)
-    - [Feilhåndtering](#feilhåndtering-2)
-- [Hent valideringsfeil for et innkrevingsoppdrag](#hent-valideringsfeil-for-et-innkrevingsoppdrag)
-- [Avstemming av et innkrevingsoppdrag](#avstemming-av-et-innkrevingsoppdrag)
+<!-- TOC -->
+
+* [Beskrivelse av tjenester](#beskrivelse-av-tjenester)
+    * [Innholdsfortegnelse](#innholdsfortegnelse)
+    * [Opprett et innkrevingsoppdrag](#opprett-et-innkrevingsoppdrag)
+        * [Synkron validering ved mottak](#synkron-validering-ved-mottak)
+        * [Asynkron validering](#asynkron-validering)
+        * [Hent mottaksbekreftelse](#hent-mottaksbekreftelse)
+        * [Hent valideringsfeil](#hent-valideringsfeil)
+        * [Feilhåndtering](#feilhåndtering)
+    * [Endre et innkrevingsoppdrag](#endre-et-innkrevingsoppdrag)
+        * [Synkron validering ved mottak](#synkron-validering-ved-mottak-1)
+        * [Asynkron validering](#asynkron-validering-1)
+        * [Feilhåndtering](#feilhåndtering-1)
+    * [Avskriv et innkrevingsoppdrag](#avskriv-et-innkrevingsoppdrag)
+        * [Synkron validering ved mottak](#synkron-validering-ved-mottak-2)
+        * [Asynkron validering](#asynkron-validering-2)
+        * [Feilhåndtering](#feilhåndtering-2)
+    * [Avstemming av et innkrevingsoppdrag](#avstemming-av-et-innkrevingsoppdrag)
+
+<!-- TOC -->
 
 ## Opprett et innkrevingsoppdrag
 
 Et innkrevingsoppdrag opprettes i Skatteetatens innkrevingssystemer ved et POST-kall
-til `/api/innkreving/innkrevingsoppdrag/v1/innkrevingsoppdrag`. Et vellykket kall returnerer en 201-statuskode sammen
-med en *kravidentifikator*, som er Skatteetatens referanse til innkrevingsoppdraget.
-
-Denne kravidentifikatoren bør oppdragsgiver ta vare på for sporbarhet.
-
-Se deretter [mottaksbekreftelse](./mottaksbekreftelse).
+til  `/api/innkreving/innkrevingsoppdrag/v1/innkrevingsoppdrag`. Før innkrevingsoppdraget blir reskontroført og
+Skatteetaten overtar ansvaret for innkrevingen gjøres det en validering. Valideringen skjer i to omganger; synkront og
+asynkront, beskrevet under.
 
-### Validering
+### Synkron validering ved mottak
 
 Tjenesten gjør validering av `OpprettInnkrevingsoppdragRequest`-objektet som er meldingskroppen i POST-kallet. Denne
 valideringen sikrer at alle nødvendige felter er korrekt utfylt og at dataene stemmer overens med tjenestens
-API-spesifikasjon. Ved valideringsfeil returneres HTTP statuskode 422 samt informasjon om valideringsfeilen.
-Oppdragsgiver må deretter korrigere innkrevingsoppdraget og sende det inn på nytt. *Merk: Etter korreksjon kan det
-oppstå ytterligere valideringsfeil fra påfølgende valideringsregler ettersom valideringsreglene utføres sekvensielt.*
+API-spesifikasjon.
+
+Et vellykket kall returnerer kvittering med en 201-statuskode sammen med en _kravidentifikator_, som er Skatteetatens
+referanse til innkrevingsoppdraget. Denne _kravidentifikatoren_ bør oppdragsgiver ta vare på for sporbarhet, og for
+senere å kunne referere til kravet.
+
+**HTTP statuskode 201 bekrefter at Skatteetaten har *mottatt* innkrevingsoppdraget. Skatteetaten har enda ikke tatt over
+ansvaret for innkrevingen - Se [asynkron validering](#asynkron-validering).**
+
+Ved valideringsfeil returneres HTTP statuskode 422 samt informasjon om valideringsfeilen. Oppdragsgiver må deretter
+korrigere innkrevingsoppdraget og sende det inn på nytt. *Merk: Etter korreksjon kan det oppstå ytterligere
+valideringsfeil fra påfølgende valideringsregler ettersom valideringsreglene utføres sekvensielt.*
+
+### Asynkron validering
+
+Etter vellykket synkron validering (HTTP statuskode 201), foretas en *ekstra* asynkron validering. Her gjøres det en mer
+funksjonell sjekk på at innholdet i innkrevingsoppdraget er mulig for Skatteetaten å kreve inn. Se [hent
+mottaksbekreftelse](#hent-mottaksbekreftelse).
+
+**Når mottaksstatus er `RESKONTROFOERT` er mottaket vellykket, og ansvaret for videre oppfølging (innkreving) ligger hos
+Skatteetaten.**
 
-Etter at kallet er prosessert, foretas en ekstra asynkron validering. Her sjekkes det om innholdet i
-innkrevingsoppdraget gjør det mulig for Skatteetaten å kreve inn. **Det betyr at en HTTP 201-statuskode fra
-`/api/innkreving/innkrevingsoppdrag/v1/innkrevingsoppdrag` bekrefter mottak av et innkrevingsoppdrag, men gir ikke
-bekreftelse på at Skatteetaten har tatt over ansvaret og kan kreve det inn.**
+Ved valideringsfeil vil mottaksstatus settes til `VALIDERINGSFEIL`. Da må feilene rettes av oppdragsgiver, og oppdatert
+innkrevingsoppdrag må sendes inn på nytt. Ansvaret for oppfølging ligger da hos oppdragsgiver.
+Se [hent valideringsfeil](#hent-valideringsfeil).
 
-    Seksjonen vil utvides med anbefalt arbeidsflyt for å håndtere dette.
+*Seksjonen vil utvides med dokumentasjon som beskriver valideringsreglene pr kravtype.*
 
-Per nå er eneste valideringsregel for NAVs tilbakekrevingskrav at det gjøres et oppslag mot Folkeregisteret for å
-sikre at skyldneren både er en reell person og at vedkommende fortsatt er i live.
+### Hent mottaksbekreftelse
 
-    Seksjonen vil utvides etterhvert som flere oppdragsgivere og typer krav støttes.
+1. Opprett nytt innkrevingsoppdrag med POST-kall til `/api/innkreving/innkrevingsoppdrag/v1/innkrevingsoppdrag` (Se
+   "Opprett et innkrevingsoppdrag"
+   i [SwaggerHub](https://app.swaggerhub.com/apis-docs/skatteetaten/oppdragsinnkreving-api/)).
+    * Kallet er vellykket og får en kvittering (201-statuskode) med en kravidentifikator.
+
+2. Etter noen sekunder kan mottaksstatus hentes ved å gjøre GET-kall med kravidentifikatoren
+   til `/api/innkreving/innkrevingsoppdrag/v1/innkrevingsoppdrag/{kravidentifikator}/mottaksstatus` (se
+   "Hent mottaksstatus for et innkrevingsoppdrag"
+   i [SwaggerHub](https://app.swaggerhub.com/apis-docs/skatteetaten/oppdragsinnkreving-api/)).
+
+    * Hvis mottaksstatus er `MOTTATT_UNDER_BEHANDLING`, behandler Skatteetaten det fortsatt.
+        * Ansvaret for oppfølging ligger hos Skatteetaten.
+    * Hvis mottaksstatus er `VALIDERINGSFEIL`, må valideringsfeil hentes ved GET-kall
+      til `/api/innkreving/innkrevingsoppdrag/v1/innkrevingsoppdrag/{kravidentifikator}/valideringsfeil` (se
+      "Hent valideringsfeil for et innkrevingsoppdrag"
+      i [SwaggerHub](https://app.swaggerhub.com/apis-docs/skatteetaten/oppdragsinnkreving-api/)). Deretter må
+      feilene rettes, og oppdatert innkrevingsoppdrag må sendes inn på nytt.
+        * NB! Ansvaret for oppfølging ligger hos oppdragsgiver.
+
+    * Hvis mottaksstatus er `RESKONTROFOERT` er mottaket vellykket.
+        * Ansvaret for oppfølging ligger hos Skatteetaten.
+
+### Hent valideringsfeil
+
+Eventuelle valideringsfeil
+fra [den asynkrone valideringen ved opprettelse av et innkrevingsoppdrag](#asynkron-validering) kan hentes ut ved et
+GET-kall til endepunktet `/api/innkreving/innkrevingsoppdrag/v1/innkrevingsoppdrag/{kravidentifikator}/valideringsfeil`.
+
+Dersom den asynkrone valideringen ikke har resultert i noen valideringsfeil, returneres en tom liste.
 
 ### Feilhåndtering
 
-I tilfeller hvor klienten opplever nettverksfeil eller andre usikkerheter ved opprettelse av nye innkrevingsoppdrag, og
-er usikker på om kravet faktisk har blitt opprettet hos Skatteetaten, anbefales det å sende kravet på nytt. Tjenesten
-vår sikrer unikhet på `oppdragsgiversKravidentifikator`. Dersom kravet allerede finnes i vårt system, vil det returneres
+Tjenesten for opprettelse av nye krav sikrer unikhet på `oppdragsgiversKravidentifikator`. Dersom man følger
+[anbefalinger for bruk av tjenestene våre](anbefalinger-for-bruk.md#fyll-ut-feltet-oppdragsgiverskravidentifikator-i-opprettinnkrevingsoppdragrequest)
+og fyller ut dette feltet, kan man sende oppdraget på nytt hvis man av ulike grunner er usikker på om kravet faktisk har
+blitt opprettet hos Skatteetaten. Dersom kravet allerede finnes i vårt system, vil det returneres
 en HTTP 422-statuskode med en beskrivende feilmelding. Hvis det ikke finnes, vil innkrevingsoppdraget bli opprettet og
-prosessert.
+prosessert. *Dette mønsteret for feilhåndtering kan kun benyttes om `oppdragsgiversKravidentifikator` er utfylt.*
 
 ## Endre et innkrevingsoppdrag
 
-Innkrevingsoppdrag kan endres ved et PUT-kall til endepunktet
-`/api/innkreving/innkrevingsoppdrag/v1/innkrevingsoppdrag/endring`. Endrings-tjenesten brukes til å gjøre korreksjoner
-på et innkrevingsoppdrag, f.eks. der skyldner har betalt deler av beløpet til oppdragsgiver. Hvis et nytt vedtak fattes
-hos oppdragsgiver, slik at det i praksis er snakk om et nytt krav, bør det opprinnelige innkrevingsoppdraget
-antageligvis [avskrives](#avskriv-et-innkrevingsoppdrag), før det [opprettes et nytt](#opprett-et-innkrevingsoppdrag).
+Innkrevingsoppdrag kan endres ved et PUT-kall til følgende endepunkter:
+
+* `/api/innkreving/innkrevingsoppdrag/v1/innkrevingsoppdrag/{kravidentifikator}/hovedstol`
+* `/api/innkreving/innkrevingsoppdrag/v1/innkrevingsoppdrag/{kravidentifikator}/renter`
+* `/api/innkreving/innkrevingsoppdrag/v1/innkrevingsoppdrag/{kravidentifikator}/oppdragsgiversreferanse`
+
+Endrings-tjenestene brukes til å gjøre korreksjoner på et innkrevingsoppdrag, f.eks. der skyldner har betalt deler av
+beløpet til oppdragsgiver og det er behov for å nedjustere hovedstolen.
 
-Merk at et innkrevingsoppdrag ikke kan endres umiddelbart etter opprettelse; det kan først endres etter at Skatteetaten
-har reskontroført det. Ved normal oppførsel skjer dette tilnærmet øyeblikkelig.
+Merk at et innkrevingsoppdrag ikke kan endres umiddelbart etter opprettelse; det kan først endres etter at
+Skatteetaten har reskontroført det. Ved normal drift vil dette skje tilnærmet øyeblikkelig.
 
-### Validering
+### Synkron validering ved mottak
+
+Tjenesten foretar en synkron validering av at det innkommende forespørsels-objektet for endring er iht.
+OpenAPI-spesifikasjonen.
+
+Et vellykket kall returnerer kvittering med en 200-statuskode sammen med en _transaksjonsid_ som er Skatteetatens
+referanse til endringen. Denne _transaksjonsiden_ bør oppdragsgiver ta vare på for sporbarhet, og for senere å kunne
+referere til endringen.
+
+**HTTP 200-statuskode bekrefter at Skatteetaten har _mottatt og tatt ansvaret for_ endringen.**
 
-Tjenesten foretar en synkron validering av at det innkommende `EndringRequest`-objektet er iht. Openapi-spesifikasjonen.
 Ved valideringsfeil vil endepunktet returnere en HTTP 422-statuskode med en beskrivende feilmelding.
 
+### Asynkron validering
+
+Det gjøres per nå ingen asynkron validering på noen av endepunktene for endring.
+
+Det gis per nå ingen mottaksstatus på endringer, f.eks. om en endring er reskontroført. Dersom det oppstår feil utover
+synkron validering, og oppdragsgiver må foreta seg noe, vil varsling skje manuelt. Automatisk varsling vil kunne
+etableres sammen med nye innkrevingsløsninger.
+
 ### Feilhåndtering
 
 I tilfeller hvor klienten opplever nettverksfeil eller andre usikkerheter ved endring av et innkrevingsoppdrag, og er
@@ -80,31 +153,40 @@ sendes inn på nytt, vil det fremdeles returneres en HTTP 200-statuskode.
 
 ## Avskriv et innkrevingsoppdrag
 
-Innkrevingsoppdrag kan avskrives ved et POST-kall til endepunktet
-`/api/innkreving/innkrevingsoppdrag/v1/innkrevingsoppdrag/avskriving`. Endepunktet benyttes når oppdragsgiver mener at
-kravet ikke lenger skal innkreves.
+Innkrevingsoppdrag kan avskrives ved et POST-kall til
+endepunktet `/api/innkreving/innkrevingsoppdrag/v1/innkrevingsoppdrag/avskriving`. Endepunktet benyttes når
+oppdragsgiver mener at kravet ikke lenger skal innkreves, eller det ikke er noe mer å kreve inn.
 
-### Validering
+Merk at et innkrevingsoppdrag ikke kan avskrives umiddelbart etter opprettelse; det kan først avskrives etter at
+Skatteetaten har reskontroført det. Ved normal drift vil dette skje tilnærmet øyeblikkelig.
+
+### Synkron validering ved mottak
 
 Tjenesten foretar en synkron validering av at det innkommende `AvskrivingRequest`-objektet er iht.
-Openapi-spesifikasjonen. Ved valideringsfeil vil endepunktet returnere en HTTP 422-statuskode med en beskrivende
-feilmelding.
+OpenAPI-spesifikasjonen.
 
-### Feilhåndtering
+Et vellykket kall returnerer kvittering med en 200-statuskode sammen med en _transaksjonsid_ som er Skatteetatens
+referanse til avskrivingen. Denne _transaksjonsiden_ bør oppdragsgiver ta vare på for sporbarhet, og for senere å kunne
+referere til avskrivingen.
 
-I tilfeller hvor klienten opplever nettverksfeil eller andre usikkerheter ved avskriving av innkrevingsoppdrag, og
-er usikker på om kravet faktisk ble avskrevet hos Skatteetaten, anbefales det å sende forespørselen på nytt.
+**HTTP 200-statuskode bekrefter at Skatteetaten har mottatt og tatt ansvaret for avskrivingen.**
 
-Et innkrevingsoppdrag som allerede er avskrevet, kan ikke avskrives på nytt. I slike tilfeller returneres en HTTP
-409-statuskode med en feilmelding.
+Ved valideringsfeil vil endepunktet returnere en HTTP 422-statuskode med en beskrivende feilmelding.
+
+### Asynkron validering
 
-## Hent valideringsfeil for et innkrevingsoppdrag
+Det gjøres per nå ingen asynkron validering ved avskriving.
 
-Eventuelle valideringsfeil fra [den asynkrone valideringen ved opprettelse av et innkrevingsoppdrag](#validering) kan
-hentes ut ved et GET-kall til endepunktet
-`/api/innkreving/innkrevingsoppdrag/v1/innkrevingsoppdrag/{kravidentifikator}/valideringsfeil`.
+Det gis per nå ingen mottaksstatus på avskrivinger. F.eks. om avskrivningen er reskontroført. Dersom det oppstår feil
+utover synkron validering, og oppdragsgiver må foreta seg noe, vil varsling skje manuelt. Automatisk varsling vil kunne
+etableres sammen med nye innkrevingsløsninger.
 
-Dersom den asynkrone valideringen ikke resulterte i noen valideringsfeil, returneres en tom liste.
+### Feilhåndtering
+
+I tilfeller hvor klienten opplever nettverksfeil eller andre usikkerheter ved avskriving av innkrevingsoppdrag, og er
+usikker på om kravet faktisk ble avskrevet hos Skatteetaten, anbefales det å sende forespørselen på nytt.
+Et innkrevingsoppdrag som allerede er avskrevet, kan ikke avskrives på nytt. I slike tilfeller returneres en HTTP
+409-statuskode med en feilmelding.
 
 ## Avstemming av et innkrevingsoppdrag
 
@@ -118,6 +200,6 @@ Tjenesten returnerer for en gitt kravidentifikator:
 - Oppdragsgivers kravidentifikator (dersom den ble oversendt i det opprinnelige innkrevingsoppdraget)
 - De forespørslene som oppdragsgiver har sendt, i samme format som de ble sendt, med tidspunkt for mottak:
     - Det opprinnelige kravet
-    - Eventuelle endringer på kravet
-    - Eventuell avskriving av kravet
+    - Eventuelle endringer på kravet, med transaksjonsid
+    - Eventuell avskriving av kravet, med transaksjonsid
 

docs/innkrevingsoppdrag/teknisk-dokumentasjon.md

@@ -19,4 +19,4 @@ Tjenestene ligger i Skatteetatens testmiljø for ekstern testing: https://api-te
 Helt konkret under denne baseurlen: https://api-test.sits.no/api/innkreving/innkrevingsoppdrag/v1/
 
 Dvs. at en POST mot https://api-test.sits.no/api/innkreving/innkrevingsoppdrag/v1/innkrevingsoppdrag med tilhørende
-token fra maskinporten vil opprette et nytt innkrevingsoppdrag.
+token fra Maskinporten vil opprette et nytt innkrevingsoppdrag.

sidebars.js

@@ -28,7 +28,6 @@ const sidebars = {
         'innkrevingsoppdrag/teknisk-dokumentasjon',
         'innkrevingsoppdrag/anbefalinger-for-bruk',
         'innkrevingsoppdrag/beskrivelse-av-tjenester',
-        'innkrevingsoppdrag/mottaksbekreftelse'
       ]
     },