Översikt

Alla API-svar returneras som JSON. API:t är skyddat med API-nyckel via HTTP-header. Rekommenderad användning är att klienten hämtar marknadsräntor (rates-endpoints) separat från individuella beräkningar (calculate).

Autentisering

Ange API-nyckeln i headern x-api-key. Om nyckeln saknas eller är felaktig returneras 401 Unauthorized.

curl -X GET "/api/rates/list" \
  -H "x-api-key: DIN_API_KEY"

Felhantering

API:t returnerar fel som JSON med error-fält (och ibland extra detaljer). Klienten bör hantera 4xx som användar-/inputfel och 5xx som tillfälliga serverfel.

{
  "error": "Unauthorized"
}

GET /api/form/questions

Returnerar konfigurerade formulärfrågor (t.ex. rabatter) som kan användas i UI för att bygga dynamiska val. Resultatet används främst för att bygga selected_discounts till /api/calculate.

curl -X GET "/api/form/questions" \
  -H "x-api-key: DIN_API_KEY"

{
  "questions": [
    {
      "id": 1,
      "key": "IKEA_Family",
      "label": "IKEA Family medlem?",
      "type": "checkbox",
      "group": "discounts",
      "options": null,
      "active": true,
      "sortOrder": 3
    },
    {
      "id": 2,
      "key": "TCO_Saco_HSB_SPP",
      "label": "Välj ett alternativ (Saco/TCO, HSB Bospar, SPP)",
      "type": "select",
      "group": "discounts",
      "options": ["TCO", "Saco", "HSB", "SPP"],
      "active": true,
      "sortOrder": 10
    }
  ]
}

{
  "selected_discounts": ["IKEA_Family", "TCO"],
  "monthly_spend": 3000
}

POST /api/calculate

Beräknar fram räntan man kan få för en specifik förfrågan baserat på lånebeloppets storlek, belåningsgrad, bindningstid, övriga rabatter och bankregler. Responsen sorterar alltid lägsta ränta överst och banker med rule_deviation längst ner.

{
  "loan_amount": 2700000,
  "property_value": 4500000,
  "property_type": "Bostadsratt",
  "term": "ThreeMonth",
  "current_rate": 0,
  "selected_discounts": ["IKEA_Family"],
  "monthly_spend": 0,
  "energy_class": "Vet ej"
}

curl -X POST "/api/calculate" \
  -H "Content-Type: application/json" \
  -H "x-api-key: DIN_API_KEY" \
  -d '{
    "loan_amount": 2700000,
    "property_value": 4500000,
    "property_type": "Bostadsratt",
    "term": "ThreeMonth",
    "current_rate": 0,
    "selected_discounts": ["IKEA_Family"],
    "monthly_spend": 0,
    "energy_class": "Vet ej"
  }'

{
  "results": [
    {
      "bankId": 1,
      "bankName": "Exempelbank",
      "logo": "...",
      "utm_link_move": "https://...",

      "fixed_rate": 3.95,
      "average_rate": 3.80,
      "personal_rate": 3.65,
      "total_discount": -0.30,
      "effective_rate": 3.72,

      "monthly_interest_cost": 8200,
      "monthly_amortization": 4500,
      "amortization_percentage": 1,

      "total_monthly_cost_before_tax": 12700,
      "monthly_tax_deduction": 2050,
      "total_monthly_cost_after_tax_deduction": 10650,

      "loan_amount": 2700000,
      "property_value": 4500000,
      "ltv": 60,
      "down_payment": 1800000,

      "current_rate": null,
      "monthly_savings_before_tax": null,
      "monthly_savings_after_tax": null,

      "green_mortgage": false,
      "rule_deviation": null,

      "open_price_model": true,
      "agreement": "..."
    }
  ]
}

GET /api/rates/list

Returnerar listräntor (Fixed) per bank, grupperat per bindningstid (term). Banker sorteras med lägsta listränta först inom varje term.

curl -X GET "/api/rates/list" \
  -H "x-api-key: DIN_API_KEY"

{
  "terms": {
    "ThreeMonth": [
      { "bankId": 2, "bankName": "Bank A", "fixed_rate": 3.95 },
      { "bankId": 7, "bankName": "Bank B", "fixed_rate": 4.05 }
    ],
    "OneYear": [
      { "bankId": 7, "bankName": "Bank B", "fixed_rate": 3.85 }
    ]
  }
}

GET /api/rates/average

Returnerar snittränta per term (aggregerat över banker som har giltig Average-ränta för termen). Detta är en marknadsindikator – ingen banklista i denna endpoint.

curl -X GET "/api/rates/average" \
  -H "x-api-key: DIN_API_KEY"

{
  "terms": {
    "ThreeMonth": { "average_rate": 2.65, "banks": 13 },
    "OneYear":    { "average_rate": 2.80, "banks": 13 },
    "FiveYear":   { "average_rate": 2.20, "banks": 13 }
  }
}

GET /api/rates/average-per-bank

Returnerar snittränta (Average) per bank och term, grupperat per bindningstid. Banker sorteras med lägsta snittränta först inom varje term.

curl -X GET "/api/rates/average-per-bank" \
  -H "x-api-key: DIN_API_KEY"

{
  "terms": {
    "ThreeMonth": [
      { "bankId": 2, "bankName": "Bank A", "average_rate": 2.35 },
      { "bankId": 7, "bankName": "Bank B", "average_rate": 2.55 }
    ],
    "OneYear": [
      { "bankId": 7, "bankName": "Bank B", "average_rate": 2.75 }
    ]
  }
}

rule_deviation

rule_deviation används när en bank inte kan ge ett korrekt prissatt erbjudande för indata (t.ex. otillåten bostadstyp, belåningsgrad utanför regelverk, eller bank kräver manuell kontakt). När rule_deviation finns ska klienten visa meddelandet och inte visa räntedata för banken.

Sortering

Calculate-resultat sorteras av API:t: banker utan rule_deviation först, sedan lägsta ränta (personal → average → fixed). Banker med rule_deviation returneras sist.

Rates-endpoints: inom varje term sorteras banklistor stigande på respektive ränta (lägst först).

Affärsregler (urval)

Nedan regler påverkar datat: