REST API

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

Data

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:
oidstring (id)Objekt-id för ärende
tobstring (date)Tidpunkt då versionen sparades
statusstringStatus (se MatterStatus i statiska listor)
otherStatusstringRaderat ("deleted"), annulerat ("cancelled") eller null
typestringTyp (se ApplicationType och ApplicationTypeShort i statiska listor)
annotationstringNotering
namestringNamn på installatör
addressstringAnläggningsadress
siteNoarrayNoll eller flera anläggnings-id (string) kopplade till ärendet
messstringPreview av olästa meddelanden, annars null
attsnumber (integer)Antal bilagor
geobooleantrue 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:
idstringIdentitet för texten
textstringText 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:
_idstring (id)Versions-id för ärende
tobstring (date)Tidpunkt när versionen sparades
Item.statusstringStatus (se MatterStatus i statiska listor)
Item.statusAnnotationstringNotering
Item.namestringVem som sparat versionen
Item.emailstringMejladress

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:
idstring (id)Identitet på bilaga
tobstring (date)Tidpunkt då bilaga laddades upp
namestringFilnamn
sizenumber (integer)Storlek i bytes
userstringVem som laddat upp bilagan
companystringFö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 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:

oidstring (id)Objekt-id för meddelande
tobstring (date)Tidpunkt då meddelande skickades
textstringMeddelande
AttachmentsarrayBilagor, se nedan
rolestringFörfattarroll, "Distributor" eller "Licensee"
authorstringNamn på författare

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:

oidstring (id)Objekt-id för meddelande
tobstring (date)Tidpunkt då meddelande skickades
textstringMeddelande
AttachmentsarrayBilagor, se nedan
rolestringFörfattarroll, "Distributor" eller "Licensee"
authorstringNamn 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
mainHuvudblankettens båda sidor
prodBilaga för produktionsanläggning
apartmentsBilaga för färdiganmälan av lägenheter
privateBilaga med privata noteringar
messagesBilaga med meddelanden
tempsiteBilaga 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:
idstring (id)Identitet på privat notering
tobstring (date)Tidpunkt då notering senast redigerades
authorstringNamn på den som senast redigerade noteringen
textstringNoteringstext

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.

_idstring (id)Version på ärendet
oidstring (id)Objekt-id för ärende
typestringAlltid Matter
tobstring (date)Tidpunkt då versionen sparades
Matter.versionnumberObjektversion:
<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
Matter.statusstringStatus (se MatterStatus i statiska listor)
Matter.statusAnnotationstringNotering
Matter.gdprConsentLicenseebooleanInstallatör har intygat att personuppgifter får behandlas
Matter.gdprConsentDistributorbooleanNätägare har intygat att personuppgifter får behandlas
Matter.LicenseeobjektUppgifter om installatör
Matter.DistributorobjektUppgifter om nätägare
Matter.Application.annotationstring (date)Notering
Matter.Application.typestringFöranmälan: typ (se ApplicationType och ApplicationTypeShort i statiska listor)
Matter.Application.typeDescriptionstringFöranmälan: informationstext när type=="other"
Matter.Application.SiteobjektFöranmälan: anläggningsuppgifter.
Property type enligt SiteType i statiska listor.
Property Geo ska vara GeoJSON FeatureCollection.
Matter.Application.MeterobjektFöranmälan: mätaruppgifter
Property location enligt MeterLocation i statiska listor.
Matter.Application.CustomerobjektFöranmälan: kunduppgifter
Matter.Application.ServiceLineobjektFöranmälan: servisuppgifter
Matter.Application.RealEstateOwnerobjektFöranmälan: fastighetsägare
Matter.Application.SubscriptionobjektFöranmälan: abonnemangsuppgifter
Matter.Application.ConnectionFeeLiablestringFöranmälan: anslutningsavgift ("customer" eller "owner")
Matter.Application.connectDateEstimatedstring (date)Föranmälan: tillkopplingsdatum
Matter.MicroProductionobjektBilaga för småskalig produktion
Property Site.powerSource enligt PowerSource i statiska listor.
Property Site.connection enligt Phase i statiska listor.
Matter.ProdTypeAobjektBilaga 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.validFromDatestring (date)Inst.medg: giltighet
Matter.Approval.contactNamestringInst.medg: kontaktperson
Matter.Approval.contactPhonestringInst.medg: telefonnummer
Matter.Approval.contactEmailstringInst.medg: mejladress
Matter.Approval.siteNostringInst.medg: anläggnings-id
Matter.Approval.natIdstringInst.medg: nätområde
Matter.Approval.estimatedEnergynumber (integer)Inst.medg: uppskattad förbrukning
Matter.Approval.consumerTypestringInst.medg: typ av förbrukning
Matter.Approval.ServiceLineobjektInst.medg: servis
Matter.Approval.MeterobjektInst.medg: mätare
Property location enligt MeterLocation i statiska listor.
Matter.Approval.connectionPointstringInst.medg: anslutningspunkt
Matter.Approval.connectionDatestring (date)Inst.medg: datum
Matter.Approval.annotationstringInst.medg: notering
Matter.ConfirmationobjektFärdiganmälan
Matter.ApartmentsarrayBilaga för färdiganmälan av lägenheter
Matter.AttachmentsarrayBilagor, se nedan

En bilaga

Objekt i array Attachments i ärende eller meddelande.

idstring (id)Identitet på bilaga
annotationstringNoteringstext (används endast för bilagor i ärenden)