Külső API-dokumentáció

Integrálja rendszereit az EasySolar API-val

Az API-kulcs alapú integráció hozzáférést biztosít a naptárhoz, projektekhez, ügyfelekhez és komponensekhez.
Ez rugalmasságot ad rendszereivel való integrációhoz és folyamatok automatizálásához.

Külső API-dokumentáció

Az API-kulcs alapú integráció hozzáférést biztosít a naptárhoz, projektekhez, ügyfelekhez és komponensekhez. Ez rugalmasságot ad rendszereivel való integrációhoz és folyamatok automatizálásához.


Tartalomjegyzék

  1. Hitelesítés
  2. Lapozás
  3. Naptár API
  4. Projektek API
  5. Ügyfelek API
  6. Komponensek API
  7. Adatkonvenciók
  8. Szűrési viselkedés
  9. Jogosultságmodell
  10. Hibakezelés
  11. Integrációs minták
  12. Stabilitás és verziókezelés

1. Hitelesítés

Minden kérésnek tartalmaznia kell API-kulcsot a kérés fejlécében.

Authorization: Api-Key <raw_api_key>

Megjegyzések: - Az API-kulcsokat a cégtulajdonosok és az adminok hozzák létre és kezelik. - Minden kulcs meghatározott erőforrás-jogosultságokra van korlátozva. - Minden kérés automatikusan az API-kulcshoz rendelt céghez van kapcsolva.

Hitelesítési hibák

Állapot Ok
401 Hiányzó vagy érvénytelen API-kulcs
401 Hibás formátumú Authorization fejléc
401 Inaktív API-kulcs
403 Hiányzó erőforrás-jogosultság
402 A cég inaktív

2. Lapozás

A listázó végpontok (Naptár, Projektek, Ügyfelek) limit/offset lapozást használnak.

Paraméterek

Paraméter Leírás Alapértelmezett Maximum
limit A visszaadandó eredmények száma 100 500
offset Lapozási eltolás 0 —

Válaszstruktúra

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

Ha a next értéke null, elérte az utolsó oldalt.


3. Naptár API

Ütemezett eseményeket jelöl, például megbeszéléseket, hívásokat és telepítéseket. Csak olvasható.

Végpontok

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

Szükséges jogosultság: calendar_read

Válaszminta

{
  "id": "7d0f4d55-3b66-4c71-a86d-2b0ef2fca6d5",
  "category": "meeting",
  "subject": "Első helyszíni felmérés",
  "description": "A telepítési követelmények és a tetőellenőrzés megbeszélése.",
  "client": {
    "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
    "name": "Solar Corp",
    "address": "Fő utca 10, Varsó",
    "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"
}

Mezőreferencia

Mező Típus Leírás
id UUID Esemény azonosítója
category string Esemény kategóriája (lásd az alábbi értékeket)
subject string Esemény címe
description string További eseményjegyzetek
client object | null Kapcsolt ügyfél
participants array Az eseményhez rendelt munkatársak
start_at datetime Esemény kezdési időpontja (UTC)
end_at datetime Esemény befejezési időpontja (UTC)
full_day boolean Az esemény a teljes napot lefedi-e
created_at datetime Esemény létrehozásának időbélyege

Kategóriaértékek

Érték Leírás
meeting Találkozó
call Telefonhívás
installation Telepítési időpont
contract Szerződéskötés
quotation Árajánlat bemutatása

Beágyazott objektumok

Ügyfél objektum:

Mező Típus Leírás
id UUID Ügyfél azonosítója
name string Ügyfél neve
address string Ügyfél címe
phone string Ügyfél telefonszáma
is_open boolean Az ügyfél aktív állapota

Résztvevő objektum:

Mező Típus Leírás
first_name string Munkatárs keresztneve
last_name string Munkatárs vezetékneve
email string Munkatárs e-mail címe

Szűrők

Paraméter Típus Leírás
start_at_after datetime Szűrés az ezen időpont után kezdődő eseményekre
start_at_before datetime Szűrés az ezen időpont előtt kezdődő eseményekre
end_at_after datetime Szűrés az ezen időpont után végződő eseményekre
end_at_before datetime Szűrés az ezen időpont előtt végződő eseményekre
category string (multi) Szűrés kategória szerint; több értékhez ismételje meg
client UUID Szűrés ügyfél-azonosító alapján

Példa:

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. Projektek API

Az ügyfélhez kapcsolódó projektadatokat képviseli (pl. napelemes telepítések). Csak olvasható.

Végpontok

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

Szükséges jogosultság: projects_read

Válaszminta

{
  "id": "d8e22cb9-1d88-4a3d-a3fd-f954d1f23d59",
  "name": "Napelemes telepítés - varsói iroda",
  "address": "Aleje Jerozolimskie 120, Varsó",
  "latitude": 52.2297,
  "longitude": 21.0122,
  "client": {
    "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
    "name": "Solar Corp",
    "address": "Fő utca 10, Varsó",
    "phone": "+48123456789",
    "is_open": true
  },
  "status": {
    "name": "Folyamatban",
    "order": 2
  },
  "currency": {
    "code": "PLN",
    "name": "Lengyel zloty"
  },
  "total_price": "42500.00",
  "payback_period": 8,
  "created": "2026-05-01T09:00:00Z",
  "updated": "2026-06-01T15:30:00Z"
}

Mezőreferencia

Mező Típus Leírás
id UUID Projekt azonosítója
name string Projekt neve
address string Projekt címe
latitude decimal | null Projekt szélességi koordinátája
longitude decimal | null Projekt hosszúsági koordinátája
client object Kapcsolt ügyfél (lásd: Ügyfél objektum)
status object Projekt állapota
currency object A pénzügyi értékekhez használt pénznem
total_price decimal string Aktuális projekt teljes ára
payback_period integer | null Becsült megtérülési idő években
created datetime Létrehozás időbélyege
updated datetime Utolsó frissítés időbélyege

A total_price pontosság megőrzése érdekében decimális szövegként kerül visszaadásra. A payback_period értéke null, ha még nincs kiszámítva. A latitude/longitude értéke null, ha nincs megadva helyszín.

Beágyazott objektumok

Állapot objektum:

Mező Típus Leírás
name string Státusz megjelenített neve
order integer Státusz sorrendi értéke

Pénznem objektum:

Mező Típus Leírás
code string ISO pénznemkód
name string Pénznem neve

Szűrők

Paraméter Típus Leírás
created_after datetime Szűrés létrehozási dátum alapján (alsó határ)
created_before datetime Szűrés létrehozási dátum alapján (felső határ)
updated_after datetime Szűrés frissítési dátum alapján (alsó határ)
updated_before datetime Szűrés frissítési dátum alapján (felső határ)
client UUID Szűrés ügyfél-azonosító alapján
status UUID Szűrés státuszazonosító alapján
name string Nagy- és kisbetűtől független részleges névegyezés

Példa:

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

5. Ügyfelek API

Ügyfélentitásokat képvisel. Olvasási és írási műveleteket támogat.

Végpontok

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}/

Szükséges jogosultságok: clients_read (olvasás), clients_write (írás)

Válaszminta

{
  "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
  "name": "Solar Corp",
  "description": "Kereskedelmi ügyfél, akit érdekel egy tetőre telepített napelemes rendszer.",
  "address": "Fő utca 10, Varsó",
  "latitude": 52.2297,
  "longitude": 21.0122,
  "phone": "+48123456789",
  "is_open": true,
  "created": "2026-05-01T10:15:00Z",
  "updated": "2026-06-01T08:45:30Z"
}

Mezőreferencia

Mező Típus Leírás
id UUID Ügyfél azonosítója
name string Ügyfél neve
description string További megjegyzések
address string Ügyfél címe
latitude decimal | null Ügyfél szélességi koordinátája
longitude decimal | null Ügyfél hosszúsági koordinátája
phone string | null Ügyfél telefonszáma
is_open boolean Az ügyfél jelenleg aktív-e
created datetime Létrehozás időbélyege
updated datetime Utolsó frissítés időbélyege

Ügyfél létrehozása

POST https://api-production.easysolar-app.com/integrations/clients/
{
  "name": "Ügyfélnév",
  "description": "Kereskedelmi ügyfél",
  "address": "Cím",
  "phone": "+48123456789",
  "latitude": 52.2297,
  "longitude": 21.0122
}

Ügyfél frissítése

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

Csak azokat a mezőket adja meg, amelyeket frissíteni szeretne:

{
  "address": "Új cím 15, Varsó",
  "phone": "+48987654321"
}

Koordinátaszabályok

  • A latitude és longitude értékeket mindig együtt kell megadni.
  • Csak az egyik koordináta megadása validációs hibát eredményez.
  • Ha nincs megadva helyszín, mindkét mező null értékként kerül visszaadásra.

Szűrők

Paraméter Típus Leírás
created_after datetime Szűrés létrehozási dátum alapján (alsó határ)
created_before datetime Szűrés létrehozási dátum alapján (felső határ)
updated_after datetime Szűrés frissítési dátum alapján (alsó határ)
updated_before datetime Szűrés frissítési dátum alapján (felső határ)
is_open boolean Szűrés aktív állapot szerint (true vagy false)
name string Nagy- és kisbetűtől független részleges névegyezés
phone string Nagy- és kisbetűtől független részleges egyezés a telefonszámra

6. Komponensek API

Komponensek létrehozása projektekben való használatra. Csak írható.

Végpont

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

Szükséges jogosultság: components_write

Komponenstípusok

Három komponens típus támogatott: panel, inverter és other.


Panel

{
  "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"
}
Mező Típus Kötelező Leírás
type string Igen Csak "panel" érték lehet
manufacturer_name string Igen Gyártó neve
name string Igen Panelmodell neve
net_unit_price decimal Nem Nettó egységár
nominal_power decimal Igen Névleges teljesítmény (W). Értéke 1.0 és 1000.0 között kell legyen
length decimal Igen Panel hossza (m). Értéke 0.1 és 5.0 között kell legyen
width decimal Igen Panel szélessége (m). Értéke 0.1 és 5.0 között kell legyen
weight decimal | null Nem Tömeg (kg)
efficiency decimal Igen Átalakítási hatásfok. 0 és 1 közötti arányszámnak kell lennie
short_circuit_current decimal Igen Rövidzárlati áram (A). Értéke 0.00001 és 999.99999 között kell legyen
open_circuit_voltage decimal Igen Nyitott áramköri feszültség (V). Értéke 0.00001 és 999.99999 között kell legyen
current_temperature_coefficient decimal | null Nem Áram-hőmérsékleti együttható. Ha meg van adva, értéke −99.999999 és 99.999999 között kell legyen
voltage_temperature_coefficient decimal | null Nem Feszültség-hőmérsékleti együttható
power_temperature_coefficient decimal | null Nem Teljesítmény-hőmérsékleti együttható

Inverter

{
  "type": "inverter",
  "manufacturer_name": "SMA",
  "name": "Sunny Tripower 5.0",
  "net_unit_price": "900.00",
  "nominal_power": "5000.000",
  "number_of_dc_inputs": 2
}
Mező Típus Kötelező Leírás
type string Igen Csak "inverter" érték lehet
manufacturer_name string Igen Gyártó neve
name string Igen Invertermodell neve
net_unit_price decimal Nem Nettó egységár
nominal_power decimal Igen Névleges teljesítmény (W). Értéke 100.0 és 100000000.0 között kell legyen
number_of_dc_inputs integer Igen DC bemenetek száma. Legalább 1 kell legyen

Egyéb

{
  "type": "other",
  "name": "Rögzítőrendszer",
  "unit": "pcs",
  "net_unit_price": "50.00"
}
Mező Típus Kötelező Leírás
type string Igen Csak "other" érték lehet
name string Igen Komponens neve
unit string Nem Mértékegység
net_unit_price decimal Nem Nettó egységár

Válasz

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

Megjegyzések

  • A gyártók automatikusan létrejönnek, ha még nem léteznek.
  • A gyártó egyedisége cégenként van érvényesítve.
  • A panelspecifikus mezők mindegyike ellenőrzésre kerül létrehozás előtt.

7. Adatkonvenciók

Azonosítók

Minden erőforrás-azonosító UUID sztring, amely stabil és cégen belül globálisan egyedi:

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

Időbélyegek

Minden datetime mező ISO 8601 formátumban, mindig UTC-ben kerül visszaadásra:

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

Geolokáció

A koordináták az Ügyfelekre és Projektekre vonatkoznak. Földrajzi pontként tároljuk őket, és külön mezőként adjuk vissza:

"latitude": 52.2297,
"longitude": 21.0122

Null értékek kezelése

A nem beállított mezők null értékként kerülnek visszaadásra — soha nem maradnak ki a válaszból.


8. Szűrési viselkedés

Általános szabályok

  • Minden szűrő opcionális, kivéve, ha másként van megadva.
  • Több szűrő ÉS logikával kombinálódik.
  • A többször választható szűrőértékek (pl. category) belsőleg VAGY logikát használnak.
  • Az érvénytelen szűrőértékek a mező típusától függően üres eredményt vagy validációs hibát adnak vissza.

Dátumtartomány-szűrők

Elérhetők az összes végponton:

Szűrőmezők Viselkedés
created_after / created_before Tartományszűrő a létrehozás időbélyegére
updated_after / updated_before Tartományszűrő az utolsó frissítés időbélyegére
start_at_after / start_at_before Tartományszűrő az esemény kezdési időpontjára
end_at_after / end_at_before Tartományszűrő az esemény befejezési időpontjára

Szöveges keresési szűrők

Nagy- és kisbetűtől független részleges egyezés a name és phone mezőkön:

?name=solar

Találatok: "Solar Corp", "Saját napelemes projektem", stb.


9. Jogosultságmodell

Az API-kulcs jogosultságai erőforrásonként külön vannak beállítva:

Erőforrás Olvasási jogosultság Írási jogosultság
Naptár calendar_read (nem támogatott)
Projektek projects_read (nem támogatott)
Ügyfelek clients_read clients_write
Komponensek (nem támogatott) components_write

10. Hibakezelés

Hibaformátum

Általános hiba:

{
  "detail": "Hibaüzenet"
}

Mezőszintű validációs hiba:

{
  "field_name": ["Hibaüzenet"]
}

Hibareferencia

Állapot Kategória Jelentés
401 Hitelesítés Érvénytelen, hiányzó vagy inaktív API-kulcs; hibás fejlécformátum
402 Üzleti A cég inaktív
403 Engedélyezés Az API-kulcshoz nincs meg a szükséges erőforrás-jogosultság
4xx Validáció A mezőszintű hibák objektumként kerülnek visszaadásra

Integrációs ellenőrzőlista

Hiba esetén ellenőrizze:

  1. Az API-kulcshoz a megfelelő erőforrás-jogosultságok tartoznak.
  2. A cégfiók aktív.
  3. Minden szűrőérték (azonosítók stb.) ugyanahhoz a céghatókörhöz tartozik.

11. Integrációs minták

Szinkronizálási stratégia

Az adatok szinkronizálásához javasolt megközelítés:

  1. Hívja le a listázó végpontot (lapozottan).
  2. Tárolja az id értéket külső hivatkozásként.
  3. Inkrementális szinkronizáláshoz használja az updated mezőt.

Lapozás kezelése

Lépjen végig az oldalakon az offset növelésével, amíg a next értéke null nem lesz:

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

Inkrementális szinkronizálás

Használjon dátumszűrőket, hogy csak az utolsó szinkronizálás óta módosult rekordokat kérje le:

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

Szűrési bevált gyakorlatok

  • Feldolgozásra nagy mennyiségnél az azonosító-alapú szűrőket (client, status) részesítse előnyben a szöveges keresések helyett.
  • Több szűrő kombinálásával csökkentse az eredményhalmaz méretét.
  • Kerülje a széles körű szöveges kereséseket nagy adathalmazokon.

12. Stabilitás és verziókezelés

Stabilitási garanciák

Az alábbiak verziózott migráció nélkül nem változnak:

  • Végpont URL-ek
  • Mezőnevek
  • UUID formátum
  • Lapozási szerkezet
  • Hitelesítési séma

Változhatnak (nem törő módosítások)

  • Opcionális szűrők (új szűrők adhatók hozzá)
  • Válaszbővítések (új mezők adhatók hozzá)

Verziókezelési irányelv

Az URL-ben jelenleg nincs explicit verzió feltüntetve. A törő változások új végpontnévteret vezetnek be:

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

A hozzáadó változtatások nem törőnek minősülnek, és verzióemelés nélkül is bevezethetők.


Dokumentáció vége

Lépjen kapcsolatba velünk

Segítségre van szüksége?

support@easysolar.app

Forduljon hozzánk bizalommal, és dedikált csapatunk gyorsan válaszol a megkereséseire.

Értékesítsen automatikusan AI-val

Hozzon létre egy automatizált AI-értékesítőt 2 perc alatt

Adja hozzá az AI napelemes ajánlatgenerátort a meglévő weboldalához. Állítsa be az árait, válassza ki termékeit, és szabja testre cége arculatát. Ügyfelei azonnali ajánlatot kapnak, Ön pedig minden ajánlatról és érdeklődő ügyfélről azonnali e-mail értesítést kap.

Tetőszél-érzékelés napelemekhez