Inledning

Momentum Fastighet API är en webbtjänst som aggregerar och levererar information från och till flera bakomliggande system, till exempel Momentum Login, Momentum Fastighet och Momentum Fastighet Marknad.

För att en inloggad användare skall kunna hämta information om egna objekt måste dennes inloggningskonto vara kopplad mot dennes kundkonto i Fastighet. Sådan koppling kan göras med funktionen som beskrivs i avsnittet Anslut kund. Funktionen som beskrivs i avsnittet Hämta kontostatus returnerar information som visar om sådan koppling är gjord.

För att logga in, se kontohantering.

Versionshantering

Vi utvecklar och förbättrar kontinuerligt våra produkter och så även Fastighet API. Ibland behöver vi ändra, utöka och ta bort funktioner. I andra fall ersätts en hel grupp av funktioner med något nytt då vi bygger om eller ersätter underliggande system. Dessa så kallade "breaking changes" meddelas 6 månader i förväg i produktnyheter samt här.

Det är API-användarens ansvar att löpande övervaka denna dokumentation och göra nödvändiga anpassningar i tid så slutanvändaren inte påverkas.

PM API som webbtjänst

Kommunikationen med Fastighet-API-tjänsten är synkron och meddelandeorienterat, vilket särskiljer sig mot RPC-orienterat: anroparen skickar en begäran i form av ett meddelande till tjänsten, vilken i sin tur returnerar ett svarsmeddelande. Anroparens meddelande består av ett antal parametrar som är specifika för den aktuella begäran. Typiskt utgör parametrarna sökkriterier för objekturval. I vissa fall är parametrarna obligatoriska, i andra är de valfria. Svarsmeddelanden kan innehålla information om ett eller flera objekt.

En invariant anropsparameter är den så kallade API-nyckeln som alla meddelanden som skickas till webbtjänsten måste innehålla. Syftet med API-nyckeln är att begränsa tillgången så att endast behöriga aktörer (system) kan hämta information från systemet. Om nyckeln saknas eller är felaktig returnerar tjänsten HTTP-statuskoden 407 - Proxy Authentication Required. Den aktuella nyckeln som skall anges distribueras separat. Se vidare under avsnittet Obligatoriska parametrar.

För vissa anrop krävs det att en användare är inloggad. I dessa fall måste anropen göras med en sessionsparameter. Ett exempel är vid anrop av funktionen som byter användarens lösenord.

Felhantering

Fastighet-API-tjänsten stödjer från och med Momentum PM 5.16 en förändrad och mer enhetlig felhantering. Det nya felhanteringen aktiveras genom att en helt ny API-nyckel utfärdas av Momentum. Används en gammal API-nyckel gäller fortsatt den gamla felhanteringen men detta stöd utgår i framtiden och implementeras inte i nya API-funktioner.

:warning: Utgående: Den gamla felhanteringen slutar fungera 2021-06-01.

I den gamla felhanteringen returnerade vissa anrop resultat med Lyckat = false och ett meddelande och vissa anrop returnerade fel genom att returnera en HTTP-statuskod som 401 Unauthorized tillsammans med ett generellt felobjekt som json.

I den nya felhanteringen är detta konsoliderat, vilket innebär att fel inte längre returneras som Lyckat = false av någon API-funktion - även om det är dokumenterat så. Istället returneras konsekvent vid fel en HTTP-status-kod mellan 400 och 599 och ett generellt felobjekt som ser ut så här:

{
  "error": {
    "code": "HumanErrorException",
    "message": "Fel användarnamn eller lösenord",
    "report": "X-1-123-456-789
  }
}

Meddelande (error.message) visas direkt för användaren.

För att förenkla felsökning ska error.report (felrapportnummer) alltid visas tillsammans med felmeddelande i klienten. Felrapportnummer brukar dock inte visas för fel med felkod HumanErrorException. Det är möjligt för interna användare, som har tillräcklig behörighet, att söka och se felmeddelandet med ytterligare felsökningsinformation på insidan i Momentum PM.

Vissa fel lämnar också extra felsökningsinformation i egenskapen debug:

{
  "error": {
    "code": "InvalidApiKey",
    "message": "Oväntat klientfel",
    "report": "X-1-123-456-789,
    "debug": "API-nyckel felaktig"
  }
}

Innehållet i egenskapen error.debug ska inte visas för användaren men kan loggas till console eller liknande. Innehållet är tänkt att främst användas vid utveckling av klienter.

Följande felkoder returneras av Fastighet API:

HTTP-status	Felkod (Code)	Beskrivning	Version
400 (bad request)	MachineErrorException	Fel som inte beror på användaren, ibland med felsökningsinformation. Meddelande (error.message) kan visas för användaren. Felsökningsinformation (error.debug) ska aldrig visas direkt för användaren. Exempel: anrop med fel parametrar, ogiltigt id, osv.	5.16
400 (bad request)	HumanErrorException	Fel som beror på användaren eller bör visas direkt för användaren av andra skäl. Meddelande (error.message) visas direkt för användaren.Exempel: Felaktigt användarnamn eller lösenord	5.16
400 (bad request)	FieldViolationException	Fel som beror på användaren. Meddelande visas direkt för användaren. Exempel: Fältet förnamn är obligatoriskt (flera fel kan förekomma)	5.16
407 (proxy authentication required)	InvalidApiKey	Felaktig API-nyckel.	5.16
401 (unauthenticated)	NotSignedIn	Användaren är inte inloggad och funktionen kräver inloggning. Meddelande kan visas direkt för användaren men normalt ska klienten visa en inloggningsruta när detta fel inträffar, för att sedan försöka igen.	5.16
403 (forbidden)	AccessDenied	Användaren är inloggad men har inte åtkomst till funktionen. Meddelande visas direkt för användaren. Exempel: Du har inte behörighet att skapa en felanmälan.	5.16
501 (not implemented)	NotImplemented	Funktionen har inte aktiverats, finns inte i denna version av Momentum PM eller har utgått. Meddelande kan visas direkt för användaren. Exempel: Felanmälan är inte aktiverad.	5.16
500 (internal server error)	InternalServerError	Vid oväntade och interna fel. Meddelande visas direkt för användaren. Exempel: Ett internt fel inträffade på servern	5.16

Nya felkoder kan läggas till i framtiden.

När ett fel inträffar returnerar Fastighet API ett svar med Content-Type application/json. Returneras en annan content-type än application/json, kan det bero på ett serverfel, felaktig serveradress, fel i brandvägg/omvänd proxy och liknande och då ska ett generellt felmeddelande visas för användaren som "Det gick inte att kommunicera med underliggande system, felkod {http-status-code}". Svaret som lämnas av servern ska inte visas. Observera att detta även gäller om servern returnerar en lyckad HTTP-status-kod som 200 (och content-type inte är application/json).

Utöver ovan nämnda fel ska klienten som vanligt också hantera nätverksrelaterade fel som "No connection could be made because the target machine actively refused.", dvs då inget svar alls ges från servern, eller om klienten inte är ansluten till internet.

Begränsning: Funktioner under avsnittet Marknadsprofil och Intresseanmälan har inte stöd för den standardiserade felhanteringen.

Loggning av klientfel

Fel som inträffar på klienten ska loggas till Momentum Fastighet för att underlätta felsökning. Fel som returneras från Fastighet API behöver inte loggas.

Glöm ej att ange http-huvudet Authorization om användaren är inloggad. Ange X-Ray-Id för att koppla felet till eventuella relaterade API-anrop inom samma transaktion.

POST /v2/client/error

Returnerar: felrapport-nummer om rapporteringen lyckades. Null kan returneras om t ex felrapportering är avstängd av någon anledning. Returneras fel ska dessa inte visas för användaren, men kan eventuellt loggas.

Parametrar

Benämning	Typ	Exempel	Källa	Version
message	Fritext	Null reference exception.		5.16
source	Fritext	https://abc.domän.se/klient/arende/visa/build.min.js		5.16
stackTrace	Fritext	T ex javascript trace		5.16
lineNumber	Heltal	52		5.16
additionalData	Fritext	Tillstånd eller annan information som kan vara användbar		5.16

Resultat (ErrorReportReference)

Benämning	Typ	Exempel	Källa	Version
code	Fritext	X-123-456-789	PM5 Fastighet	5.16

Loggning av meddelande

Sparar loggmeddelande från klienten.

Glöm ej att ange http-huvudet Authorization om användaren är inloggad. Ange X-Ray-Id för att koppla felet till eventuella relaterade API-anrop inom samma transaktion.

POST /v2/client/log

Parametrar

Benämning	Typ	Exempel	Källa	Version
message	Fritext	Applikation startar.		5.16

HTTP-huvud

Anrop från klient till Fastighet-API-tjänsten stödjer från och med Momentum Fastighet 5.16 följande HTTP-huvud (headers):

Benämning	Typ	Exempel	Källa	Version
Authorization	Fritext	Bearer [sessionsnyckel]		5.16
Cache-Control	Fritext	Ska innehålla direktivet no-store		5.16
X-Api-Key	Fritext	abcdefgh123456789		5.16
X-Forwarded-For	Fritext	123.123.123.123		5.16
X-Device-Id	Fritext	abcd123456789		5.16
X-Ray-Id	Fritext	abcd123456789		5.16
X-Client-Version	Fritext	1.0.3		5.16

Anges Authorization behöver inte Sessionsnyckel anges som parametrar i anrop.

Anges X-Api-Key behöver inte ApiNyckel anges som parametrar i anrop.

HTTP-huvudet X-Forwarded-For måste anges om Fastighet-API anropas via en tjänst som i sin tur tar emot anrop från en annan klient. Anropas Fastighet API direkt från slutanvändaren, som från en webbläsare, mobil-app och liknande, ska detta huvud inte anges.

HTTP-huvudet X-Device-Id är ett slumpmässigt genererat globalt unikt id som genereras och lagras av klienten. X-Device-Id ska lagras permanent och behålla samma värde över tid även om användaren t ex loggar ut och in eller om någon annan användare loggar in, klienten stängs ned, osv. X-Device-Id ska anges i alla anrop som gör från klientapplikationer, men behöver inte anges när anrop görs med tjänstekonton.

HTTP-huvudet X-Ray-Id är ett slumpmässigt genererat globalt unikt id som genereras av klienten vid varje transaktion. Ray-Id måste inte men bör sättas för att koppla ihop rapportering av klientfel med t ex ett eller flera Fastighet API anrop (som kanske inte gick fel). Ett nytt Ray-Id måste genereras vid varje ny transaktion. Med transaktion menas t ex om användaren klickar på en knapp och koden bakom gör som ett eller flera api-anrop. Klickar användaren en gång till på samma knapp ska ett nytt slumpmässigt Ray-Id genereras för just den knapp-tryckningen. Vid större transaktioner kan ett meddelande med fördel först loggas med /client/log som beskriver transaktionen, varefter flera anrop görs med samma Ray-Id.

HTTP-huvudet Cache-Control ska användas och ska innehålla no-store (tillsammans med eventuellt andra direktiv).

Generella datastrukturer och datatyper

Adress

Benämning	Typ	Exempel	Källa	Version
Id	Heltal	108100		5.7
Gatunamn	Fritext	Amiralsgatan		5.7
Gatuadress	Fritext	Amiralsgatan 1		5.7
Postnummer	Fritext	21141		5.7
Postort	Fritext	Malmö		5.7
Land	Fritext	Sverige		5.7

Exempel

{
  "Gatunamn": "Amiralsgatan",
  "Gatuadress": "Amiralsgatan 1",
  "Postnummer": "21141",
  "Postort": "Malmö",
  "Land": "Sverige"
}

Position

Benämning	Typ	Exempel	Källa	Version
Lat	Decimaltal			5.7
Lon	Decimaltal			5.7

Exempel

{"Lat": 55.5901, "Lon": 12.9955}

Attribut

Benämning	Typ	Exempel	Källa	Version
Beteckning	Fritext			5.7
TypSystemnamn	Fritext			5.7

Exempel

{"Beteckning": "Datorkontrollerade kortlås", "TypSytemName": "utokadsakerhet"}

Hyresobjekt

Benämning	Typ	Exempel	Källa	Version
Id	Heltal	34	PM5 Fastighet	5.7
Typ	Fritext	Hyresobjekt	PM5 Fastighet	5.7
Klass	Fritext	Lägenhet	PM5 Fastighet	5.7
Nummer	Fritext	12-123-12	PM5 Fastighet	5.7
Beteckning	Fritext	Hårds väg 2C lgh 1201	PM5 Fastighet	5.7
Adress	Adress	(se Adress)	PM5 Fastighet	5.7
ObjektstatusSystemnamn	Fritext	nyproduktion, avslagen osv	PM5 Fastighet	5.9

Utgående

Obligatoriska parametrar

Benämning	Typ	Exempel	Källa	Version
ApiNyckel	Fritext			5.7 - 5.15

Från och med Momentum Fastighet 5.16 är denna parameter inte obligatorisk om HTTP huvud används.

Felmeddelande

Benämning	Typ	Exempel	Källa	Version
Lyckat	Booleskt värde	True	PM5 Fastighet	5.7 - 5.15
Meddelande	Fritext		PM5 Fastighet	5.7 - 5.15

Från Momentum Fastighet 5.16 returnerar Fastighet API aldrig ett svar med Lyckat = false om standardiserad felhantering har aktiverats, se avsnittet Felhantering för mer information.

Returmeddelande

Benämning	Typ	Exempel	Källa	Version
Lyckat	Booleskt värde	true		5.7 - 5.15
Returkod	Fritext	Intresseanmälan		5.7 - 5.15
Returvärde	Fritext	Du är intresseanmäld på lägenheten.		5.7 - 5.15
Inmatningsfellista	Lista m. inmatningsfel	(Se Inmatningsfel)		5.7 - 5.15

Från och med Momentum Fastighet 5.16 returnerar PM API aldrig ett svar med Lyckat = false om standardiserad felhantering har aktiverats, se avsnittet Felhantering för mer information.

Inmatningsfel

Benämning	Typ	Exempel	Källa	Version
Parameter	Fritext	tooShort	PM5 Fastighet	5.7 - 5.15
Felkod	Fritext	tooShort	PM5 Fastighet	5.7 - 5.15
Felmeddelande	Fritext	Personnumret får inte vara kortare än 12 tecken. Använd följande format: YYYYMMDD[nnnn]	PM5 Fastighet	5.7 - 5.15

Från och med Momentum Fastighet 5.16 returnerar Fastighet API aldrig ett svar ned inmatningsfel om standardiserad felhantering har aktiverats, se avsnittet Felhantering för mer information.