# Melima Public API v1

Extern integration mot Melima. Stabil kontraktsyta för fastighetssystem, ekonomisystem, BI-verktyg och egna appar.

## Grundprinciper

- **Base URL:** `https://melima.se/api/public/v1`
- **Format:** JSON. UTF-8. Datum i ISO 8601. Enheter i SI (m², kWh, kg CO2e).
- **Version:** `/v1` — bakåtkompatibel inom versionen. Brytande ändringar → `/v2`.
- **Autentisering:** `Authorization: Bearer <api_key>` per organisation.
- **Nycklar:** Skapas i Melima under Inställningar → API. Visas i klartext exakt en gång.

## Externa ID:n (`external_ref`)

Varje domänobjekt (`clients`, `properties`, `maintenance_plans`, `maintenance_actions`) har ett valfritt `external_ref` (unikt per organisation). Externa system använder detta för att mappa sina egna nycklar mot Melima utan att behöva känna till våra UUID:er.

## Endpoints

### `GET /properties`

Listar fastigheter för den organisation nyckeln tillhör. Kräver scope `read:properties`.

**Query params:**
- `limit` (1–200, default 50)
- `cursor` — `created_at`-värde från föregående sida

**Svar:**
```json
{
  "data": [ /* Property[] enligt docs/schema/v1/property.json */ ],
  "next_cursor": "2026-01-01T00:00:00Z",
  "has_more": true
}
```

## Scopes

- `read:properties`
- `read:plans`
- `read:actions`
- `read:sustainability`
- Skriv-scopes (`write:*`) reserverade för framtida endpoints.

## Fel

Standard HTTP-statuskoder. Felkropp:
```json
{ "error": "invalid_api_key" }
```

Vanliga koder:
- `401 invalid_api_key`
- `403 insufficient_scope`
- `500 query_failed`

## Schemadefinitioner

- [`property.json`](./property.json)
- [`maintenance-action.json`](./maintenance-action.json)