Sammendrag

Fellestjenester ID (FtID) er en overordnet ID som kan legges til et byggeprosjekt for å knytte sammen data for byggesaken. Fellestjenester Plan og Bygg legger til rette for at innsendte søknader, vedtak og andre saksbehandlingsdata kan merkes med FtID slik at det finnes en felles identifikasjon på data som tilhører samme byggesak.

FtID kan også brukes i fremtidige tjenester, både internt i FtPB eller for tjenester eksternt til tjenesteplattformen. Et eksempel for tenkt bruk er ved sporing av levert bygningsavfall. Vi forventer å forbedre API-ene ved behov og etter nye bruksområder.

Tallserien

Tallserien følger ID standardisering fra gs1.no og DiBK har fått tildelt et foretaksprefiks for tallserien. Foretaksprefikset er 7073387, der 70 identifiserer Norge og 73387 identifiserer Direktoratet for Byggkvalitet.

Tallserien er videre bygd opp som følger:

Vi bruker syv siffer for byggesaksnummeret i første runde. Tallserien kan utvides med tre høyere gjeldende siffer om nødvending. IDen avsluttes med et kontrollsiffer som beregnes basert på resten av tallet. FtPB regner ut kontrollsiferet som del av tildelingen av FtID. Kontrollsifferet er ikke avhengig av lengden av IDen, slik at det ikke forandrer seg om byggesaksnummeret utvides.

FtIDen blir dermed slik:

7073387 000 1234567 K (totalt 18 siffer)

På testsystemene bruker vi 7099999 for foretaksprefikset. Denne tallserien er bare for testbruk.

Forutsetninger for bruk

• Kun godkjente søknadssystemer på FtPB kan reservere en FtID. Autentisering foregår på samme måte som resten av API-ene på FtPB.

• Søknadssystemene er ansvarlige for å hente og sende gyldige FtID-er i tråd med kravene til hvert API (under).

• Søknadssystemene er ansvarlige for at de ikke genererer nye ID-er uten at det er behov for det.

• En FtID skal i hovedsak knyttes til en hovedsøknad, men én FtID kan også deles mellom flere hovedsøknader der det er ønskelig. Vi forutsetter at én FtID tilsvarer én sluttrapport der avfallsdata skal leveres.

• FtID tildeles bare digitale søknader, ikke søknader som er sendt kommunene på annen måte.

• Vi har ikke API for å rette opp feilregistreringer. For å rette opp feil, må søknadssystemet hente en ny FtID, eller åpne en sak i service desk for å få den rettet.

API-er for bruk av FtID

Tre APIer er lagt til rette for bruk av FtID:

1. Hente en ny FtID​

2. Knytte en FtID opp mot en AR-kode​

3. Se hva som er lagret på en FtID​

Swagger-dokumentasjon er tilgjengelig her:

• TEST: https://admbygg.ft-test.dibk.no/swagger/ui/index#/FtId

1. API for å hente en ny FtID​

API for å hente/reservere en FtID for et prosjekt:

Open

Eksempel på kall med retur av FtID

Beskrivelse av datafelt

• Kommunenummer - Kommunenummer for byggeprosjektet. Obligatorisk.

• Gårdsnummer - Gårdsnummer for byggeprosjektet. Obligatorisk.

• Bruksnummer - Bruksnummer for byggeprosjektet. Obligatorisk.

• Prosjektnavn - Ansvarlig søkers prosjektnavn. Obligatorisk.

• Prosjektnr - Ansvarlig søkers prosjektnummer. Frivillig.

• System - Navn på søknadssystemet som henter ID-en. Obligatorisk.

Regler for bruk

• Kommunenummer må være gyldig

• Kombinasjonen Kommunenummer, Gårdsnummer, Bruksnummer, Prosjektnavn og System må være unik

  • Hvis man prøver å hente ut flere FtID-er med samme kombinasjon, vil API-et returnere den opprinnelige ID-en som ble lagret for denne kombinasjonen, og ikke en ny.

  • Hvis man prøver å hente ut flere FtID-er med samme kombinasjon, men med et Prosjektnr som ennå ikke er lagt til , vil FtPB-databasen bli oppdatert med prosjektnummeret. Dette er bare tilgjengelig én gang. Sender man et annet prosjektnummer etter dette, blir det ikke oppdatert.

• Dersom søker ønsker å rette opp i opplysninger gitt for en ID, kan søknadssystemet hente en ny FtID. Søknadssystemet må oppdatere eventuelle innsendinger/søknader med den nye ID-en (eget API).

• API-et har begrensninger for hvor mange ID-er som kan hentes per minutt.

2. API for å knytte en FtID til en innsending

API-et gir mulighet til å knytte innsendinger og søknader som allerede har funnet sted til en ny FtID.

Se også “Bruk av metadata for registrering av FtID” (under).

Open

Eksempel på kobling av en FtId til en AR-referanse

Beskrivelse av datafelt

• FtID - FtID-en som innsendingen skal kobles til.

• ArchiveReference - Referansen for innsendingen, f.eks. AR-referanse til en tidligere innsendt rammesøknad.

Regler for bruk

• FtID må være gyldig

• ArchiveReference må være gyldig og fra en innsending som allerede er registrert i FtPB-databasen

• API-et skal kun brukes der det er tidligere innsendinger som er sendt uten FtID i metadatafeltet, eventuelt dersom søknadssystemet har hentet en ny FtID og ønsker å overskrive den gamle ID-en.

• API-et dekker kun sendinger fra søknadssystem til FtPB, og ikke f.eks. saksbehandlingsdata sendt fra eByggesak.

3. API for å hente data som er registrert på en FtID

Bruk dette APIet for å se hvilke innsendinger er registrert på en FtID.

Beskrivelse av datafelt

• ArchiveReference - Referanse til innsendingen, f.eks. en AR-referanse.

• FormType - Type innsending/søknad.

Bruk av metadata for registrering av FtID

En del datamodeller for innsendinger i FtPB inneholder et metadataobjekt med et ftbID-felt. Hvis en gyldig FtID blir lagt inn i ftbId ved innsending, vil tjenesten logge FtID med AR-referansen automatisk. Det blir med andre ord ikke behov for å bruke attach-APIet.

Regler for bruk

• FtbId må tilsvare en gyldig FtID. Hvis en ugyldig FtID blir sendt, blir den sett bort fra uten at behandling av innsendingen stopper opp. På sikt vil vi vurdere å innføre strengere validering av feltet ved innsending av søknader.

• I første omgang gjør vi kun denne koblingen for innsendte hovedskjema fra søknadssystemene:

  • Underskjema som gjennomføringsplan og avfallsplan blir ikke koblet.

  • Dialogtjenester som svar på nabovarsel, tiltakshavers samtykke og signeringstjenesten for ansvarlige foretak blir ikke koblet.

  • Data fra kommunen via saksbehandlings-APIene blir ikke koblet.