Information

Här beskrivs det API som kan användas för att integrera föranmälan.nu med andra system på nätbolaget, t.ex. ärendehanteringssystem. Nätbolaget behöver en separat API-licens för att kunna använda API-funktionerna.

API:et kan komma att förändras i framtiden men vi kommer då eftersträva bakåtkompatibilitet så att existerande integrationer fortsätter att fungera utan störningar.

På vår testsida kan man testa de olika anropen.

Allmänt om anrop

• Bas-URL för anropen är https://foranmalan.nu/
• HTTP-verben GET, POST, PUT och DELETE används för att hämta, skapa, uppdatera och radera objekt.
• Alla anrop ska autentiseras med en Http Request Header Basic Access Authentication eller en cookie Authorization. Vi rekommenderar att Http Request Header används. Användarnamn och lösenord ska vara en användare som lagts upp under nätbolagets konto med en mejladress. Denna mejladress får inte vara kopplad flera konton, dvs den får inte vara kopplad till både ett nätägarkonto och ett installatörskonto.
• Query-parametrar i URL ska kodas enligt standard (EncodeURIComponent)
• Returkoder enligt HTTP standard, se nedan.

Data

• Objekt identifieras med oid. Ett objekt har en eller flera versioner där varje version identifieras med _id.
• När ett objekt uppdaterats får den nya versionen ett nytt _id.
• Endast senaste versionen av ett objekt kan uppdateras. Ärenden är låsta för uppdatering när de har vissa status.
• Data (body) som returneras från servern och som skickas till servern följer JSON-standard. Undantaget är bilagor och pdf-dokument som hanteras som binära data med MIME-kodning.
• Datum anges i UTC som ISO-sträng, t.ex. "2019-05-27T13:33:55.236Z"
• null används när värde saknas
• Identiteter anges som strängar med 24 hexadecimala tecken

Hämta ärendelista

GET /api/matters?since={UTC-tidpunkt}

Returnerar en lista med alla ärenden som antingen ändrats sedan en viss UTC-tidpunkt eller där meddelanden skickats efter en viss UTC-tidpunkt. since kan utelämnas om alla ärenden ska hämtas.

Svar

{
  "Matters": [ {objekt}, {objekt}, ... ]
} Matters innehåller objekt med följande utseende:

oid	string (id)	Objekt-id för ärende
tob	string (date)	Tidpunkt då versionen sparades
status	string	Status (se MatterStatus i statiska listor)
otherStatus	string	Raderat ("deleted"), Annullerat ("cancelled") eller null
type	string	Typ (se ApplicationType och ApplicationTypeShort i statiska listor)
annotation	string	Notering
name	string	Namn på installatör (eller nätägare när installatör gör API-anropet)
address	string	Anläggningsadress
siteNo	array	Noll eller flera anläggnings-id (string) kopplade till ärendet
mess	string	Preview av olästa meddelanden, annars null
atts	number (integer)	Antal bilagor
geo	boolean	true om kartskiss finns

Hämta statiska listor

GET /api/lists

Svar

{
  "ApplicationType": [{objekt}, {objekt}, ...],
  "ApplicationTypeShort": [{objekt}, {objekt}, ...],
  "MatterStatus": [{objekt}, {objekt}, ...],
  "MeterLocation": [{objekt}, {objekt}, ...],
  "Phase": [{objekt}, {objekt}, ...],
  "PowerSource": [{objekt}, {objekt}, ...],
  "SiteType": [{objekt}, {objekt}, ...]
} Varje array innehåller objekt med följande utseende:

id	string	Identitet för texten
text	string	Text i klartext

Hämta ett ärende

GET /api/matter?oid={objekt-id för ärende}&_id={versions-id för ärende}

_id kan utelämnas om senaste ärendeversion ska hämtas.

Svar

Ett ärende, se objekt.

Vem sparade ärendet?

GET /api/who?oid={objekt-id för ärende}&_id={versions-id för ärende}

_id kan utelämnas om senaste ärendeversion avses.

Svar

{
  "name": "xxxx",
  "email": "xxxx@xx.xx"
}

Hämta historik för ett ärende

GET /api/history?oid={objekt-id för ärende}

Svar

{
  "History": [ {objekt}, {objekt}, ... ]
} History innehåller objekt med följande utseende:

_id	string (id)	Versions-id för ärende
tob	string (date)	Tidpunkt när versionen sparades
Item.status	string	Status (se MatterStatus i statiska listor)
Item.statusAnnotation	string	Notering
Item.name	string	Vem som sparat versionen
Item.email	string	Mejladress

Hämta bilagelista för ett ärende eller ett meddelande

GET /api/attachments?oid={objekt-id för ärende/meddelande}&_id={versions-id för ärende}

_id kan utelämnas om senaste ärendeversion avses.

Svar

{
  "Attachments": [ {objekt}, {objekt}, ... ]
} Attachments innehåller objekt med följande utseende:

id	string (id)	Identitet på bilaga
tob	string (date)	Tidpunkt då bilaga laddades upp
name	string	Filnamn
size	number (integer)	Storlek i bytes
user	string	Vem som laddat upp bilagan
company	string	Företagsnamn

Hämta en bilaga

GET /api/attachment?oid={objekt-id för ärende/meddelande}&_id={versions-id för ärende}&id={bilage-id}

_id kan utelämnas om senaste ärendeversion avses.

Svar

MIME-kodade binärdata.

Hämta en kartskiss som zippade shape-filer

GET /api/mapshape?oid={objekt-id för ärende}&_id={versions-id för ärende}

_id kan utelämnas om senaste ärendeversion ska hämtas.

Zip-filen innehåller en uppsättning filer för respektive geometrityp som finns i kartskissen. Geometrityper kan kan vara linjer, punkter, ytor och varje uppsättning består av filtyperna cpg, dbf, prj, shp, shx. Om ärendet inte innehåller någon kartskiss fås 404 Not Found som svar.

Svar

Binärdata för en zip med MIME-kodning=application/zip.

Hämta meddelanden för ett ärende

GET /api/messages?oid={objekt-id för ärende}

Svar

{
  "Messages": [{objekt}, {objekt}, ...]
}

Messages innehåller objekt med följande utseende:

oid	string (id)	Objekt-id för meddelande
tob	string (date)	Tidpunkt då meddelande skickades
text	string	Meddelande
Attachments	array	Bilagor, se nedan
role	string	Författarroll, "Distributor" eller "Licensee"
author	string	Namn på författare

Hämta ett ärende som pdf

GET /api/matterPdf?oid={objekt-id för ärende}&_id={versions-id för ärende}&main=1

_id kan utelämnas om senaste ärendeversion ska hämtas.

Man kan välja vilka sidor som ska ingå i rapporten genom att lägga till query-parametrar med värdet 1. Om inga parametrar läggs till inkluderas samtliga sidor i rapporten Följande parametrar kan anges:

parameter
main	Huvudblankettens båda sidor
prod	Bilaga för produktionsanläggning
apartments	Bilaga för färdiganmälan av lägenheter
private	Bilaga med privata noteringar
messages	Bilaga med meddelanden
tempsite	Bilaga för avtal om tillfällig anläggning (gäller vissa nätbolag)

Svar

Binärdata för en pdf med MIME-kodning=application/pdf.

Hämta underskriven bilaga "Produktion typ A" som pdf

GET /api/prodSignedPdf?oid={objekt-id för ärende}

Svar

Binärdata för en pdf med MIME-kodning=application/pdf.

Ladda upp en bilaga

POST /api/attachment
Body: binärdata med content-type/filename

Svar

{
  "id": {"bilage-id"}
}

Identiteten ska sparas i Attachments[] i ärendet eller meddelandet och detta behöver senare sparas för att bilagan ska kunna hämtas.

Skicka ett meddelande

POST /api/message
Body: {
  "oid": "objekt-id för ärende",
  "text": "meddelandetext",
  "Attachments": [{"id":"bilage-id"}, {"id":"bilage-id"}, ...]
}

Svar

Inga data i svar

Uppdatera ett ärende

PUT /api/matter
Body: ett ärende, se objekt

Svar

Inga data i svar

Radera ett ärende

DELETE /api/matter
Body: ett ärende, se objekt

Svar

Inga data i svar

Hämta privata noteringar för ett ärende

GET /api/privateNotes?oid={objekt-id för ärende}

Svar

{
  "PrivateNotes": [{objekt}, {objekt}, ...]
} PrivateNotes innehåller objekt med följande utseende:

id	string (id)	Identitet på privat notering
tob	string (date)	Tidpunkt då notering senast redigerades
author	string	Namn på den som senast redigerade noteringen
text	string	Noteringstext

Skapa en privat notering

POST /api/privateNote
Body: {
  "oid": "objekt-id för ärende",
  "text": "noteringstext"
}

Svar

{
  "id": {"id för privat notering"}
}

Uppdatera en privat notering

PUT /api/privateNote
Body: {
  "id": "id för privat notering",
  "text": "noteringstext"
}

Svar

Inga data i svar

Radera en privat notering

DELETE /api/privateNote
Body: {
  "id": "id för privat notering"
}

Svar

Inga data i svar

Returkoder

Vid lyckat anrop returneras HTTP status 200 (OK) tillsammans med ett eventuellt svar (JSON eller binärdata). Vid fel returneras istället en standardiserad HTTP-kod och statustext samt en beskrivande feltext (sträng) i svarets body. Nedan listas exempel på returkoder och vad som kan orsaka dem.

200 - OK
400 - Bad Request (fel i data som skickats)
401 - Unauthorized (felaktiga eller saknade inloggningsuppgifter)
403 - Forbidden (rättighet saknas, t.ex. att ärende är låst)
404 - Not Found (efterfrågat dokument finns ej)
409 - Conflict (dokumentet som försökte sparas har ändrats av någon annan)
413 - Payload Too Large (för stor bilaga)
415 - Unsupported Media Type (otillåten typ av bilaga)
500 - Internal Server Error

Objekt

Ett ärende

Nedanstående visar flertalet properties som finns i ett ärende. Det finns ytterligare properties i ett ärende som används internt av föranmälan.nu.

_id	string (id)	Version på ärendet
oid	string (id)	Objekt-id för ärende
type	string	Alltid Matter
tob	string (date)	Tidpunkt då versionen sparades
Matter.version	number	Objektversion: <3 - äldre variant där ärende skrevs under personligt (behörighetsnummer), före 2019 3 - elinstallationsfirman ansvarig, infördes 2019 4 - bilaga Mikroproduktion ersatt av Produktion typ A, infördes 2020 5 - förändringar i produktionsbilaga samt info om Rikta Rätt, infördes mars 2021 6 - fler fält i produktionsbilaga, infördes februari 2024
Matter.status	string	Status (se MatterStatus i statiska listor)
Matter.statusAnnotation	string	Notering
Matter.gdprConsentLicensee	boolean	Installatör har intygat att personuppgifter får behandlas
Matter.gdprConsentDistributor	boolean	Nätägare har intygat att personuppgifter får behandlas
Matter.Licensee	objekt	Uppgifter om installatör
Matter.Distributor	objekt	Uppgifter om nätägare
Matter.Application.annotation	string (date)	Notering
Matter.Application.type	string	Föranmälan: typ (se ApplicationType och ApplicationTypeShort i statiska listor)
Matter.Application.typeDescription	string	Föranmälan: informationstext när type=="other"
Matter.Application.Site	objekt	Föranmälan: anläggningsuppgifter. Property type enligt SiteType i statiska listor. Property Geo ska vara GeoJSON FeatureCollection.
Matter.Application.Meter	objekt	Föranmälan: mätaruppgifter Property location enligt MeterLocation i statiska listor.
Matter.Application.Customer	objekt	Föranmälan: kunduppgifter
Matter.Application.ServiceLine	objekt	Föranmälan: servisuppgifter
Matter.Application.RealEstateOwner	objekt	Föranmälan: fastighetsägare
Matter.Application.Subscription	objekt	Föranmälan: abonnemangsuppgifter
Matter.Application.ConnectionFeeLiable	string	Föranmälan: anslutningsavgift ("customer" eller "owner")
Matter.Application.connectDateEstimated	string (date)	Föranmälan: tillkopplingsdatum
Matter.MicroProduction	objekt	Bilaga för småskalig produktion Property Site.powerSource enligt PowerSource i statiska listor. Property Site.connection enligt Phase i statiska listor.
Matter.ProdTypeA	objekt	Bilaga för Produktion Typ A (fr.o.m. 2020) Property Site.powerSourceA enligt PowerSourceA i statiska listor. Property Site.connection enligt PhaseA i statiska listor.
Matter.Approval.validFromDate	string (date)	Inst.medg: giltighet
Matter.Approval.contactName	string	Inst.medg: kontaktperson
Matter.Approval.contactPhone	string	Inst.medg: telefonnummer
Matter.Approval.contactEmail	string	Inst.medg: mejladress
Matter.Approval.siteNo	string	Inst.medg: anläggnings-id
Matter.Approval.natId	string	Inst.medg: nätområde
Matter.Approval.estimatedEnergy	number (integer)	Inst.medg: uppskattad förbrukning
Matter.Approval.consumerType	string	Inst.medg: typ av förbrukning
Matter.Approval.ServiceLine	objekt	Inst.medg: servis
Matter.Approval.Meter	objekt	Inst.medg: mätare Property location enligt MeterLocation i statiska listor.
Matter.Approval.connectionPoint	string	Inst.medg: anslutningspunkt
Matter.Approval.connectionDate	string (date)	Inst.medg: datum
Matter.Approval.annotation	string	Inst.medg: notering
Matter.Confirmation	objekt	Färdiganmälan
Matter.Apartments	array	Bilaga för färdiganmälan av lägenheter
Matter.Attachments	array	Bilagor, se nedan

En bilaga

Objekt i array Attachments i ärende eller meddelande.

id	string (id)	Identitet på bilaga
annotation	string	Noteringstext (används endast för bilagor i ärenden)