Extern API-dokumentation

Integrera dina system med EasySolar API

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.

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

Status Orsak
401 Saknad eller ogiltig API-nyckel
401 Felaktigt formaterad auktoriseringsheader
401 Inaktiv API-nyckel
403 Saknad resursbehörighet
402 Företaget är inaktivt

2. Paginering

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

Parametrar

Parameter Beskrivning Standard Max
limit Antal resultat att returnera 100 500
offset Offset för paginering 0 —

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

Fält Typ Beskrivning
id UUID Händelse-ID
category string Händelsekategori (se värden nedan)
subject string Händelsetitel
description string Ytterligare anteckningar om händelsen
client object | null Kopplad kund
participants array Medarbetare tilldelade händelsen
start_at datetime Händelsens starttid (UTC)
end_at datetime Händelsens sluttid (UTC)
full_day boolean Om händelsen pågår hela dagen
created_at datetime Tidpunkt för skapande av händelsen

Kategorivärden

Värde Beskrivning
meeting Möte
call Telefonsamtal
installation Installationsbokning
contract Kontraktssignering
quotation Offertpresentation

Inbäddade objekt

Kundobjekt:

Fält Typ Beskrivning
id UUID Kund-ID
name string Kundnamn
address string Kundadress
phone string Kundens telefonnummer
is_open boolean Om kunden är aktiv

Deltagarobjekt:

Fält Typ Beskrivning
first_name string Medarbetarens förnamn
last_name string Medarbetarens efternamn
email string Medarbetarens e-postadress

Filter

Parameter Typ Beskrivning
start_at_after datetime Filtrera händelser som börjar efter denna tidpunkt
start_at_before datetime Filtrera händelser som börjar före denna tidpunkt
end_at_after datetime Filtrera händelser som slutar efter denna tidpunkt
end_at_before datetime Filtrera händelser som slutar före denna tidpunkt
category string (multi) Filtrera efter kategori; upprepa för flera värden
client UUID Filtrera efter kund-ID

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

Fält Typ Beskrivning
id UUID Projekt-ID
name string Projektnamn
address string Projektadress
latitude decimal | null Projektets latitud
longitude decimal | null Projektets longitud
client object Kopplad kund (se Kundobjekt)
status object Projektstatus
currency object Valuta som används för ekonomiska värden
total_price decimal string Aktuellt totalpris för projektet
payback_period integer | null Beräknad återbetalningstid i år
created datetime Tidpunkt för skapande
updated datetime Senaste uppdateringstidpunkt

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:

Fält Typ Beskrivning
name string Statusens visningsnamn
order integer Statusens ordningsvärde

Valutaobjekt:

Fält Typ Beskrivning
code string ISO-valutakod
name string Valutans namn

Filter

Parameter Typ Beskrivning
created_after datetime Filtrera efter skapelsedatum (nedre gräns)
created_before datetime Filtrera efter skapelsedatum (övre gräns)
updated_after datetime Filtrera efter uppdateringsdatum (nedre gräns)
updated_before datetime Filtrera efter uppdateringsdatum (övre gräns)
client UUID Filtrera efter kund-ID
status UUID Filtrera efter status-ID
name string Partiell namnmatchning utan skiftlägeskänslighet

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

Fält Typ Beskrivning
id UUID Kund-ID
name string Kundnamn
description string Ytterligare anteckningar
address string Kundadress
latitude decimal | null Kundens latitud
longitude decimal | null Kundens longitud
phone string | null Kundens telefonnummer
is_open boolean Om kunden för närvarande är aktiv
created datetime Tidpunkt för skapande
updated datetime Senaste uppdateringstidpunkt

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

Parameter Typ Beskrivning
created_after datetime Filtrera efter skapelsedatum (nedre gräns)
created_before datetime Filtrera efter skapelsedatum (övre gräns)
updated_after datetime Filtrera efter uppdateringsdatum (nedre gräns)
updated_before datetime Filtrera efter uppdateringsdatum (övre gräns)
is_open boolean Filtrera efter aktiv status (true eller false)
name string Partiell namnmatchning utan skiftlägeskänslighet
phone string Partiell telefonmatchning utan skiftlägeskänslighet

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"
}
Fält Typ Obligatoriskt Beskrivning
type string Ja Måste vara "panel"
manufacturer_name string Ja Tillverkarens namn
name string Ja Solpanelens modellnamn
net_unit_price decimal Nej Nettoenhetspris
nominal_power decimal Ja Märkeffekt (W). Måste vara mellan 1.0 och 1000.0
length decimal Ja Solpanelens längd (m). Måste vara mellan 0.1 och 5.0
width decimal Ja Solpanelens bredd (m). Måste vara mellan 0.1 och 5.0
weight decimal | null Nej Vikt (kg)
efficiency decimal Ja Verkningsgrad. Måste vara ett förhållande mellan 0 och 1
short_circuit_current decimal Ja Kortslutningsström (A). Måste vara mellan 0.00001 och 999.99999
open_circuit_voltage decimal Ja Tomgångsspänning (V). Måste vara mellan 0.00001 och 999.99999
current_temperature_coefficient decimal | null Nej Strömtemperaturkoefficient. Om den anges måste den vara mellan −99.999999 och 99.999999
voltage_temperature_coefficient decimal | null Nej Spänningstemperaturkoefficient
power_temperature_coefficient decimal | null Nej Effektens temperaturkoefficient

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
}
Fält Typ Obligatoriskt Beskrivning
type string Ja Måste vara "inverter"
manufacturer_name string Ja Tillverkarens namn
name string Ja Växelriktarmodellens namn
net_unit_price decimal Nej Nettoenhetspris
nominal_power decimal Ja Märkeffekt (W). Måste vara mellan 100.0 och 100000000.0
number_of_dc_inputs integer Ja Antal DC-ingångar. Måste vara minst 1

Övrigt

{
  "type": "other",
  "name": "Montagesystem",
  "unit": "st",
  "net_unit_price": "50.00"
}
Fält Typ Obligatoriskt Beskrivning
type string Ja Måste vara "other"
name string Ja Komponentnamn
unit string Nej Måttenhet
net_unit_price decimal Nej Nettoenhetspris

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:

Filterfält Beteende
created_after / created_before Intervallfilter på skapandetidpunkt
updated_after / updated_before Intervallfilter på senaste uppdateringstidpunkt
start_at_after / start_at_before Intervallfilter på händelsens starttid
end_at_after / end_at_before Intervallfilter på händelsens sluttid

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:

Resurs Läsbehörighet Skrivbehörighet
Kalender calendar_read (stöds inte)
Projekt projects_read (stöds inte)
Kunder clients_read clients_write
Komponenter (stöds inte) components_write

10. Felhantering

Felformat

Allmänt fel:

{
  "detail": "Felmeddelande"
}

Valideringsfel på fältnivå:

{
  "field_name": ["Felmeddelande"]
}

Felreferens

Status Kategori Betydelse
401 Autentisering Ogiltig, saknad eller inaktiv API-nyckel; felaktigt headerformat
402 Verksamhet Företaget är inaktivt
403 Auktorisering API-nyckeln saknar den erforderliga resursbehörigheten
4xx Validering Fältnivåfel returneras som ett objekt

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

Kontakta oss

Behöver du hjälp?

support@easysolar.app

Tveka inte att höra av dig så svarar vårt dedikerade team snabbt på dina frågor.

Sälj automatiskt med AI

Skapa en automatiserad AI-säljare på 2 minuter

Lägg till AI-generatorn för solcellsofferter på din nuvarande webbplats. Ange dina priser, välj dina produkter och anpassa ditt företags varumärkesprofil. Dina kunder får en omedelbar offert, och du får ett omedelbart e-postmeddelande för varje offert och intresserad kund.

Detektering av takkanter för solpaneler