REST API för föranmälan.nu

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

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

Ladda upp 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

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 tillsammans med en beskrivande feltext. 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.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.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)