Externí dokumentace API

Integrace založená na API klíči vám poskytuje přístup ke kalendáři, projektům, klientům a komponentám. Díky tomu můžete flexibilně propojit své systémy a automatizovat procesy.

Obsah

1. Autentizace
2. Stránkování
3. API kalendáře
4. API projektů
5. API klientů
6. API komponent
7. Datové konvence
8. Chování filtrování
9. Model oprávnění
10. Ošetření chyb
11. Integrační vzory
12. Stabilita a verzování

1. Autentizace

Všechny požadavky musí v hlavičce obsahovat API klíč.

Authorization: Api-Key <raw_api_key>

Poznámky: - API klíče vytvářejí a spravují vlastníci společnosti a administrátoři. - Každý klíč je omezen na konkrétní oprávnění k prostředkům. - Všechny požadavky jsou automaticky omezeny na společnost přiřazenou k API klíči.

Chyby autentizace

2. Stránkování

Seznamové endpointy (Kalendář, Projekty, Klienti) používají stránkování limit/offset.

Parametry

Obálka odpovědi

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

Když je next null, dosáhli jste poslední stránky.

3. API kalendáře

Představuje naplánované události, jako jsou schůzky, hovory a instalace. Pouze pro čtení.

Endpointy

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

Požadované oprávnění: calendar_read

Příklad odpovědi

{
  "id": "7d0f4d55-3b66-4c71-a86d-2b0ef2fca6d5",
  "category": "meeting",
  "subject": "Úvodní návštěva na místě",
  "description": "Probereme požadavky na instalaci a kontrolu střechy.",
  "client": {
    "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
    "name": "Solar Corp",
    "address": "Hlavní ulice 10, Varšava",
    "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"
}

Přehled polí

Hodnoty kategorií

Vnořené objekty

Objekt klienta:

Objekt účastníka:

Filtry

Příklad:

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. API projektů

Představuje projektové záznamy související s klienty (např. fotovoltaické instalace). Pouze pro čtení.

Endpointy

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

Požadované oprávnění: projects_read

Příklad odpovědi

{
  "id": "d8e22cb9-1d88-4a3d-a3fd-f954d1f23d59",
  "name": "Fotovoltaická instalace - varšavská kancelář",
  "address": "Aleje Jerozolimskie 120, Varšava",
  "latitude": 52.2297,
  "longitude": 21.0122,
  "client": {
    "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
    "name": "Solar Corp",
    "address": "Hlavní ulice 10, Varšava",
    "phone": "+48123456789",
    "is_open": true
  },
  "status": {
    "name": "Probíhá",
    "order": 2
  },
  "currency": {
    "code": "PLN",
    "name": "Polský zlotý"
  },
  "total_price": "42500.00",
  "payback_period": 8,
  "created": "2026-05-01T09:00:00Z",
  "updated": "2026-06-01T15:30:00Z"
}

Přehled polí

total_price se vrací jako desetinný řetězec, aby se zachovala přesnost. payback_period je null, pokud ještě nebyla vypočítána. latitude/longitude jsou null, pokud není nastavena poloha.

Vnořené objekty

Objekt stavu:

Objekt měny:

Filtry

Příklad:

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

5. API klientů

Představuje zákaznické entity. Podporuje operace čtení i zápisu.

Endpointy

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

Požadovaná oprávnění: clients_read (čtení), clients_write (zápis)

Příklad odpovědi

{
  "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
  "name": "Solar Corp",
  "description": "Komerční zákazník se zájmem o střešní fotovoltaickou instalaci.",
  "address": "Hlavní ulice 10, Varšava",
  "latitude": 52.2297,
  "longitude": 21.0122,
  "phone": "+48123456789",
  "is_open": true,
  "created": "2026-05-01T10:15:00Z",
  "updated": "2026-06-01T08:45:30Z"
}

Přehled polí

Vytvořit klienta

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

{
  "name": "Název klienta",
  "description": "Komerční zákazník",
  "address": "Adresa",
  "phone": "+48123456789",
  "latitude": 52.2297,
  "longitude": 21.0122
}

Aktualizovat klienta

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

Uveďte pouze pole, která chcete aktualizovat:

{
  "address": "Nová adresa 15, Varšava",
  "phone": "+48987654321"
}

Pravidla pro souřadnice

• latitude a longitude musí být vždy uvedeny společně.
• Pokud zadáte pouze jednu souřadnici, vznikne validační chyba.
• Pokud není nastavena žádná poloha, obě pole se vrátí jako null.

Filtry

6. API komponent

Vytváří komponenty pro použití v projektech. Pouze pro zápis.

Endpoint

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

Požadované oprávnění: components_write

Typy komponent

Podporovány jsou tři typy komponent: panel, inverter a 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"
}

Střídač

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

Ostatní

{
  "type": "other",
  "name": "Montážní systém",
  "unit": "ks",
  "net_unit_price": "50.00"
}

Odpověď

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

Poznámky

• Výrobci se automaticky vytvářejí, pokud neexistují.
• Jedinečnost výrobce je omezena na společnost.
• Všechna pole specifická pro panel se před vytvořením validují.

7. Datové konvence

ID

Všechny identifikátory prostředků jsou řetězce UUID, stabilní a globálně jedinečné v rámci společnosti:

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

Časová razítka

Všechna pole typu datetime se vracejí ve formátu ISO 8601, vždy v UTC:

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

Geolokace

Souřadnice se vztahují na klienty a projekty. Jsou ukládány jako geografický bod a vracejí se jako samostatná pole:

"latitude": 52.2297,
"longitude": 21.0122

Práce s hodnotou null

Pole, která nejsou nastavena, se vracejí jako null — z odpovědi nejsou nikdy vynechána.

8. Chování filtrování

Obecná pravidla

• Všechny filtry jsou volitelné, pokud není uvedeno jinak.
• Více filtrů se kombinuje logikou AND.
• Hodnoty vícenásobného výběru filtru (např. category) interně používají logiku OR.
• Neplatné hodnoty filtru vrátí prázdné výsledky nebo validační chybu podle typu pole.

Filtry časového rozsahu

Dostupné napříč endpointy:

Filtry textového vyhledávání

Částečná shoda názvu a telefonu bez rozlišení velikosti písmen:

?name=solar

Odpovídá: "Solar Corp", "Můj fotovoltaický projekt" atd.

9. Model oprávnění

Oprávnění API klíče se konfigurují nezávisle pro každý prostředek:

10. Ošetření chyb

Formát chyb

Obecná chyba:

{
  "detail": "Chybová zpráva"
}

Validační chyba na úrovni pole:

{
  "field_name": ["Chybová zpráva"]
}

Přehled chyb

Kontrolní seznam integrace

Pokud narazíte na chyby, ověřte:

1. API klíč má správná oprávnění k prostředkům.
2. Účet společnosti je aktivní.
3. Všechny hodnoty filtrů (ID atd.) patří do stejného rozsahu společnosti.

11. Integrační vzory

Strategie synchronizace

Doporučený postup pro synchronizaci dat:

1. Načtěte seznamový endpoint (se stránkováním).
2. Uložte id jako externí referenci.
3. Pro přírůstkovou synchronizaci používejte pole updated.

Zpracování stránkování

Procházejte stránky zvyšováním offsetu, dokud není next 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

Přírůstková synchronizace

Použijte filtry podle data k načtení pouze záznamů změněných od poslední synchronizace:

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

Osvědčené postupy filtrování

• Při synchronizacích s velkým objemem dat upřednostňujte filtry založené na ID (client, status) před textovým vyhledáváním.
• Kombinujte více filtrů, abyste zmenšili velikost výsledné sady.
• Vyhněte se širokému textovému vyhledávání ve velkých datových sadách.

12. Stabilita a verzování

Stabilní záruky

Následující se nezmění bez verzované migrace:

• URL endpointů
• Názvy polí
• Formát UUID
• Struktura stránkování
• Autentizační schéma

Může se změnit (bez narušení kompatibility)

• Volitelné filtry (mohou být přidány nové filtry)
• Rozšíření odpovědi (mohou být přidána nová pole)

Politika verzování

V URL není v současnosti uvedena žádná explicitní verze. Změny porušující kompatibilitu zavedou nový jmenný prostor endpointů:

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

Doplňující změny se považují za neporušující kompatibilitu a mohou být nasazeny bez navýšení verze.

Konec dokumentace