1 Metodens formål
2 Detaljert dokumentasjon av metoden
- 2.1 Autentisering og autorisering
- 2.2 HTTP-verb
- 2.3 Request
  - 2.3.1 GetTidsperioder
    - 2.3.1.1 Request
    - 2.3.1.2 Respone
  - 2.3.2 SaveTidsperiode
    - 2.3.2.1 Request
    - 2.3.2.2 Response
  - 2.3.3 DeleteTidsperiode
    - 2.3.3.1 Request
- 2.4 Swagger
- 2.5 Miljøer
3 Feilmeldinger

API-navn	Fravaersregistrering
Metode/funksjon	Tidsperiode
Endepunkt	https://{BaseUrl)/helsetilbud_externalapi/api/v1/Tidsperiode
Funksjonelt område
API-versjon og dato publisert	v1 Sep 11, 2024
Status	I DRIFT
API-dokumentasjon og sist endret	Nov 13, 2024
Teknologi	REST

Metodens formål

Metoden kan brukes av eksterne aktører for å registrere, se og slette fraværsperioder for fastlegetjenester. Fraværet registreres på tjenestenivå og innslagene inneholder tjeneste-id, fraogmed/tilogmed-dato og liste over tjenester.

Detaljert dokumentasjon av metoden

Autentisering og autorisering

HelseId sin autoriseringstjeneste for maskin-til-maskin skal benyttes
1. Velg Helsenorge Ekstern API i HelseId sin selvbetjeningsløsning
2. Velg deretter scope “fravaersregistrering”
3. Når tilgangen er godkjent av Helsenorge, kan aksesstoken hentes ut fra HelseId, dette kan så benyttes i tjenestekallet mot API’et

HTTP-verb

Alltid anvend https og HTTP-verbet som metode krever (GET, POST, DELETE). AksessToken fra HelseId STS skal være med i Authorization header i alle kall. Se her: 02 - Kall til Helsenorge og PVK API'er og bruk av AccessToken

Request

GetTidsperioder

Hent ut tidsperioder som tilhører organisasjonen som utfører kallet. I requesten kan man via HerId velge om man vil hente ut på organisasjonsnivå eller tjenestenivå. Det er mulig å anvende verdiene KunAktive eller InkluderHistoriske for endre datofiltreringen.

Request

Plassering	Navn	Type	Beskrivelse

Plassering	Navn	Type	Beskrivelse
Header	Authorization: bearer {access-token}	string	Aksess token fra HelseId sikkerhetstjeneste, etter å ha autentisert/autorisert seg mot denne.
URL	HerId	int	HerId til tjenesten (fastlegen) eller virksomheten, som må tilhøre organisasjonen som utfører kallet. Returnerer lagrede fravær-innslag for tjenesten eller virksomheten.
URL	KunAktive	bool	Hvis ja så ekskluderes følgende fra responsen: tidsperioder der tidperioden fraogmed/tilogmed ikke inneholder dagens dato.
	InkludereHistoriske	bool	Hvis ja så inkluderes følgende fra responsen: tidsperioder der tilogmed er tidligere enn dagens dato (historiske tidsperioder). KunAktive true vil overstyre denne verdien.

Respone

{
  "tidsperioder": [
    {
      "id": 4,
      "type": "Fravaer",
      "organisasjonsnummer": "999944454",
      "herId1": 8091456,
      "herId2": 8093236,
      "fraOgMedDato": "2024-06-01",
      "tilOgMedDato": "2024-06-05",
      "tjenestetyper": [
        "ekontakt"
      ]
    },
    {
      "id": 6,
      "type": "Fravaer",
      "organisasjonsnummer": "999944454",
      "herId1": 8091456,
      "herId2": 8093236,
      "fraOgMedDato": "2024-06-20",
      "tilOgMedDato": "2024-06-14",
      "tjenestetyper": [
        "timebestilling", "reseptfornyelse"
      ]
    },
    {
      "id": 7,
      "type": "Fravaer",
      "organisasjonsnummer": "999944454",
      "herId1": 8091456,
      "herId2": 8093236,
      "fraOgMedDato": "2024-08-15",
      "tilOgMedDato": "2024-11-14",
      "tjenestetyper": [
        "ekonsultasjon"
      ]
    }
  ]
}

SaveTidsperiode

Lagre ny tidsperiode for en tjeneste som tilhører organisasjonen som utfører kallet. Tjenesten må eksistere i Adresseregsteret og tilhøre organisasjonen, tjenestetypen må ikke ha overlapp på tidsperioden (ikke duplikate innslag), tidsperioden må starte på dagens dato eller senere og ikke slutte før startdato.

Request

Plassering	Navn		Type	Beskrivelse

Plassering	Navn		Type	Beskrivelse
Header	Authorization: bearer {access-token}		string	Aksess token fra HelseId sikkerhetstjeneste, etter å ha autentisert/autorisert seg mot denne.
Header	Content-Type		application/json	JSON-format
Body	Oppsett	Type	enum	Type tidsperiode som skal registreres. Per nå støtes kun fravaer
		HerId	int	HerId til tjenesten (fastlegen). Tjenesten må tilhøre organisasjonen som utfører kallet.
		FraOgMedDato	date	Datoen på formatet YYYY-mm-dd, angir dagen som fraværsperioden starter (fraværet inkluderer denne datoen)
		TilOgMedDato	date	Datoen på formatet YYYY-mm-dd, angir dagen som fraværsperioden slutter (fraværet inkluderer denne datoen)
		Tjenestetyper	enum	Hvilke tjeneste(r) som fraværet skal registreres for. Verdier per 15.05.2024: ekontakt ekonsultasjon timebestilling reseptfornyelse

Response

{
  "lagretTidsperiode": {
    "id": 123,
    "type": "Fravaer",
    "organisasjonsnummer": "12345678910",
    "herId1": 8044455,
    "herId2": 8044499,
    "fraOgMedDato": "2024-05-15",
    "tilOgMedDato": "2024-05-15",
    "tjenestetyper": [
      "ekontakt"
    ]
  }
}

DeleteTidsperiode

Slette tidsperiode som tilhører organisasjonen som utfører kallet.

Request

Plassering	Navn	Type	Beskrivelse

Plassering	Navn	Type	Beskrivelse
Header	Authorization: bearer {access-token}	string	Aksess token fra HelseId sikkerhetstjeneste, etter å ha autentisert/autorisert seg mot denne.
Header	Content-Type	application/json	JSON-format
URL/Body	Id	int	Identifikatoren til innslaget som skal slettes. Denne settes/returneres ved opprettelse (SaveTidsperiode) og kan også leses fra uthenting av tidsperioder (GetTidsperioder).
	HerId	int	HerId til tjenesten (fastlegen). Tjenesten må tilhøre organisasjonen som utfører kallet.

Swagger

Swagger UI

Miljøer

URL for å nå endepunktet (forskjellig pr miljø): https://<miljø>/fravaersregistrering/v1

Oversikt over tilgjengelige miljøer finnes her: Testmiljøer og endepunkter

Feilmeldinger

Følgende responskoder kan forventes fra Helsenorge:

Kode	Beskrivelse

Kode	Beskrivelse
200	Alt OK
400	Validering av request feiler
401	Autorisasjon er feil eller mangler
403	Tilganger mangler
500	Midlertidig feil, prøv igjen senere

Ved HTTP-statuskoder som tilsier at det har oppstått en feil returneres også en respons med feilkode og feilmelding.

Eksempler:

{ "Code": "EHSEC-110000", "Message": "Token is expired or invalid : Fault code: EHSEC-110002", "ErrorCategory": 2 } //Alle endepunktene
{ "Code": "HT-000100", "Message": "Det har skjedd en teknisk feil. Du kan prøve igjen litt senere : Fault code: HT-000100" } //Alle endepunktene
{ "Code": "HT-000114", "Message": "Feil i responsinnhold : Fault code: HT-000114", "ErrorCategory": 3 } //GetTidsperiode
{ "Code": "HT-000115", "Message": "Feil dato i request : Fault code: HT-000115", "ErrorCategory": 2 } //SaveTidsperiode
{ "Code": "HT-000116", "Message": "Overlappende tidsperiode i request: Fault code: HT-000116", "ErrorCategory": 2 } //SaveTidsperiode
{ "Code": "HT-000117", "Message": "Tidsperiode med id 1234 finnes ikke : Fault code: HT-000117", "ErrorCategory": 2 } //DeleteTidsperiode
{ "Code": "HT-000118", "Message": "HerId 1234567 er ikke gyldig, beskrivelse-av-hvorfor : Fault code: HT-000118", "ErrorCategory": 2 } //Alle endepunktene
// ErrorCategory: 2=ClientValidation og 3=ServerValidationError
// HT-000118 eksempler på beskrivelse-av-hvorfor:
//   "HerId representerer ikke en tjeneste", "HerId-innslaget er hverken preson, tjeneste eller virksomhet", "HerId har ikke en kommunikasjonspart",
//   "HerId i request matcher ikke", "organisasjonsummeret til virksomheten matcher ikke tokenet", "organisasjonen har ikke riktig organisasjonstype"

Fravaersregistrering

Metodens formål

Detaljert dokumentasjon av metoden

Autentisering og autorisering

HTTP-verb

Request

GetTidsperioder

Request

Respone

SaveTidsperiode

Request

Response

DeleteTidsperiode

Request

Swagger

Miljøer

Feilmeldinger