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

2. Lapozás

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

Paraméterek

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

Kategóriaértékek

Beágyazott objektumok

Ügyfél objektum:

Résztvevő objektum:

Szűrők

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

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:

Pénznem objektum:

Szűrők

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

Ü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

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

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
}

Egyéb

{
  "type": "other",
  "name": "Rögzítőrendszer",
  "unit": "pcs",
  "net_unit_price": "50.00"
}

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ö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:

10. Hibakezelés

Hibaformátum

Általános hiba:

{
  "detail": "Hibaüzenet"
}

Mezőszintű validációs hiba:

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

Hibareferencia

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