Extern API-dokumentation

API-nyckelbaserad integration ger dig åtkomst till Kalender, Projekt, Kunder och Komponenter. Det ger dig flexibilitet att integrera med dina system och automatisera arbetsflöden.

Innehållsförteckning

1. Autentisering
2. Paginering
3. Kalender-API
4. Projekt-API
5. Kund-API
6. Komponent-API
7. Datakonventioner
8. Filterbeteende
9. Behörighetsmodell
10. Felhantering
11. Integrationsmönster
12. Stabilitet och versionshantering

1. Autentisering

Alla förfrågningar måste innehålla en API-nyckel i begärans header.

Authorization: Api-Key <raw_api_key>

Anteckningar: - API-nycklar skapas och hanteras av företagsägare och administratörer. - Varje nyckel är knuten till specifika resursbehörigheter. - Alla förfrågningar begränsas automatiskt till det företag som är kopplat till API-nyckeln.

Autentiseringsfel

2. Paginering

Liständpunkterna för Kalender, Projekt och Kunder använder limit/offset-paginering.

Parametrar

Svarstruktur

{
  "count": 123,
  "next": null,
  "previous": null,
  "results": []
}

När next är null har du nått sista sidan.

3. Kalender-API

Representerar schemalagda händelser som möten, samtal och installationer. Endast läsning.

Ändpunkter

GET https://api-production.easysolar-app.com/integrations/calendar/
GET https://api-production.easysolar-app.com/integrations/calendar/{id}/

Obligatorisk behörighet: calendar_read

Exempel på svar

{
  "id": "7d0f4d55-3b66-4c71-a86d-2b0ef2fca6d5",
  "category": "meeting",
  "subject": "Första platsbesök",
  "description": "Diskutera installationskrav och takinspektion.",
  "client": {
    "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
    "name": "Solenergi AB",
    "address": "Huvudgatan 10, Warszawa",
    "phone": "+48123456789",
    "is_open": true
  },
  "participants": [
    {
      "first_name": "John",
      "last_name": "Smith",
      "email": "john.smith@example.com"
    }
  ],
  "start_at": "2026-06-15T09:00:00Z",
  "end_at": "2026-06-15T10:00:00Z",
  "full_day": false,
  "created_at": "2026-06-01T12:30:45Z"
}

Fältreferens

Kategorivärden

Inbäddade objekt

Kundobjekt:

Deltagarobjekt:

Filter

Exempel:

GET https://api-production.easysolar-app.com/integrations/calendar/?start_at_after=2026-01-01T00:00:00Z&category=meeting&category=call
Authorization: Api-Key <key>

4. Projekt-API

Representerar projektrelaterade poster (t.ex. solcellsanläggningar). Endast läsning.

Ändpunkter

GET https://api-production.easysolar-app.com/integrations/projects/
GET https://api-production.easysolar-app.com/integrations/projects/{id}/

Obligatorisk behörighet: projects_read

Exempel på svar

{
  "id": "d8e22cb9-1d88-4a3d-a3fd-f954d1f23d59",
  "name": "Solcellsinstallation - kontoret i Warszawa",
  "address": "Aleje Jerozolimskie 120, Warszawa",
  "latitude": 52.2297,
  "longitude": 21.0122,
  "client": {
    "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
    "name": "Solenergi AB",
    "address": "Huvudgatan 10, Warszawa",
    "phone": "+48123456789",
    "is_open": true
  },
  "status": {
    "name": "Pågående",
    "order": 2
  },
  "currency": {
    "code": "PLN",
    "name": "Polsk zloty"
  },
  "total_price": "42500.00",
  "payback_period": 8,
  "created": "2026-05-01T09:00:00Z",
  "updated": "2026-06-01T15:30:00Z"
}

Fältreferens

total_price returneras som en decimalsträng för att bevara precisionen. payback_period är null om den ännu inte har beräknats. latitude/longitude är null om ingen plats är angiven.

Inbäddade objekt

Statusobjekt:

Valutaobjekt:

Filter

Exempel:

GET https://api-production.easysolar-app.com/integrations/projects/?client=<id>&name=sol
Authorization: Api-Key <key>

5. Kund-API

Representerar kundposter. Stöder läs- och skrivoperationer.

Ändpunkter

GET    https://api-production.easysolar-app.com/integrations/clients/
POST   https://api-production.easysolar-app.com/integrations/clients/
GET    https://api-production.easysolar-app.com/integrations/clients/{id}/
PATCH  https://api-production.easysolar-app.com/integrations/clients/{id}/

Obligatoriska behörigheter: clients_read (läs), clients_write (skriv)

Exempel på svar

{
  "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
  "name": "Solenergi AB",
  "description": "Kommersiell kund som är intresserad av en takmonterad solcellsanläggning.",
  "address": "Huvudgatan 10, Warszawa",
  "latitude": 52.2297,
  "longitude": 21.0122,
  "phone": "+48123456789",
  "is_open": true,
  "created": "2026-05-01T10:15:00Z",
  "updated": "2026-06-01T08:45:30Z"
}

Fältreferens

Skapa kund

POST https://api-production.easysolar-app.com/integrations/clients/

{
  "name": "Kundnamn",
  "description": "Kommersiell kund",
  "address": "Adress",
  "phone": "+48123456789",
  "latitude": 52.2297,
  "longitude": 21.0122
}

Uppdatera kund

PATCH https://api-production.easysolar-app.com/integrations/clients/{id}/

Ta endast med de fält du vill uppdatera:

{
  "address": "Ny adress 15, Warszawa",
  "phone": "+48987654321"
}

Regler för koordinater

• latitude och longitude måste alltid anges tillsammans.
• Om endast en koordinat anges uppstår ett valideringsfel.
• Om ingen plats är angiven returneras båda fälten som null.

Filter

6. Komponent-API

Skapar komponenter för användning i projekt. Endast skrivning.

Ändpunkt

POST https://api-production.easysolar-app.com/integrations/components/

Obligatorisk behörighet: components_write

Komponenttyper

Tre komponenttyper stöds: panel, inverter och other.

Solpanel

{
  "type": "panel",
  "manufacturer_name": "Longi",
  "name": "LR5-54HPH",
  "net_unit_price": "120.00",
  "nominal_power": "430.000",
  "length": "1.7220",
  "width": "1.1340",
  "weight": "21.500",
  "efficiency": "0.2100000",
  "short_circuit_current": "13.52000",
  "open_circuit_voltage": "37.85000",
  "current_temperature_coefficient": "0.045000",
  "voltage_temperature_coefficient": "-0.280000",
  "power_temperature_coefficient": "-0.350000"
}

Växelriktare

{
  "type": "inverter",
  "manufacturer_name": "SMA",
  "name": "Sunny Tripower 5.0",
  "net_unit_price": "900.00",
  "nominal_power": "5000.000",
  "number_of_dc_inputs": 2
}

Övrigt

{
  "type": "other",
  "name": "Montagesystem",
  "unit": "st",
  "net_unit_price": "50.00"
}

Svar

{
  "id": "uuid",
  "type": "panel | inverter | other",
  "name": "string"
}

Anmärkningar

• Tillverkare skapas automatiskt om de inte finns.
• Tillverkare är unika per företag.
• Alla solpanelspecifika fält valideras före skapande.

7. Datakonventioner

ID:n

Alla resursidentifierare är UUID-strängar, stabila och globalt unika inom ett företag:

"id": "550e8400-e29b-41d4-a716-446655440000"

Tidsstämplar

Alla datetime-fält returneras i ISO 8601-format, alltid i UTC:

"created": "2026-06-09T12:34:56Z"

Geolokalisering

Koordinater gäller för kunder och projekt. De lagras som en geografisk punkt och returneras som separata fält:

"latitude": 52.2297,
"longitude": 21.0122

Hantering av null-värden

Fält som inte är angivna returneras som null — de utelämnas aldrig i svaret.

8. Filterbeteende

Allmänna regler

• Alla filter är valfria om inget annat anges.
• Flera filter kombineras med AND-logik.
• Flervalsfiltervärden (t.ex. category) använder OR-logik internt.
• Ogiltiga filtervärden returnerar tomma resultat eller ett valideringsfel beroende på fälttyp.

Datumintervallfilter

Tillgängliga i alla endpoints:

Textsökfilter

Partiell matchning utan skiftlägeskänslighet på name och phone:

?name=sol

Matchar: "Solenergi AB", "Mitt solcellsprojekt" osv.

9. Behörighetsmodell

API-nyckelbehörigheter konfigureras separat för varje resurs:

10. Felhantering

Felformat

Allmänt fel:

{
  "detail": "Felmeddelande"
}

Valideringsfel på fältnivå:

{
  "field_name": ["Felmeddelande"]
}

Felreferens

Integrationschecklista

Om du stöter på fel, kontrollera:

1. Att API-nyckeln har rätt resursbehörigheter.
2. Att företagskontot är aktivt.
3. Att alla filtervärden (ID:n osv.) tillhör samma företag.

11. Integrationsmönster

Synkstrategi

Det rekommenderade tillvägagångssättet för att synkronisera data:

1. Hämta liständpunkten (med paginering).
2. Spara id:t som extern referens.
3. Använd fältet updated för inkrementell synkronisering.

Hantering av paginering

Gå igenom sidorna genom att öka offset tills next är null:

GET https://api-production.easysolar-app.com/integrations/clients/?limit=100&offset=0
GET https://api-production.easysolar-app.com/integrations/clients/?limit=100&offset=100

Inkrementell synkronisering

Använd datumfilter för att hämta endast poster som ändrats sedan din senaste synkronisering:

GET https://api-production.easysolar-app.com/integrations/projects/?updated_after=2026-01-01T00:00:00Z

Bästa praxis för filtrering

• Föredra ID-baserade filter (client, status) framför textsökning vid synkronisering med stora volymer.
• Kombinera flera filter för att minska resultatmängden.
• Undvik breda textsökningar i stora datamängder.

12. Stabilitet och versionshantering

Stabila garantier

Följande ändras inte utan en versionshanterad migrering:

• Endpoint-URL:er
• Fältnamn
• UUID-format
• Pagineringens struktur
• Autentiseringsmetod

Kan ändras (icke-brytande)

• Valfria filter (nya filter kan läggas till)
• Utökning av svaret (nya fält kan läggas till)

Versionspolicy

Ingen explicit version exponeras för närvarande i URL:en. Brytande ändringar inför ett nytt namnområde för endpoints:

https://api-production.easysolar-app.com/integrations/v2/...

Tilläggsändringar betraktas som icke-brytande och kan driftsättas utan versionshöjning.

Slut på dokumentationen