Externí dokumentace API

Integrace na základě API klíče Vám poskytuje přístup ke Kalendáři, projektům, klientům a komponentám. To Vám dává flexibilitu 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í filtrů
9. Model oprávnění
10. Práce s chybami
11. Integrační vzory
12. Stabilita & 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í

Výpisové 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í.

Koncové body

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

Ukázka odpovědi

{
  "id": "7d0f4d55-3b66-4c71-a86d-2b0ef2fca6d5",
  "category": "meeting",
  "subject": "Úvodní návštěva na místě",
  "description": "Projednání požadavků na instalaci a kontrola střechy.",
  "client": {
    "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
    "name": "Solar Corp",
    "address": "Hlavní 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 záznamy projektů souvisejících s klientem (např. fotovoltaické instalace). Pouze pro čtení.

Koncové body

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

Ukázka odpovědi

{
  "id": "d8e22cb9-1d88-4a3d-a3fd-f954d1f23d59",
  "name": "Fotovoltaická instalace - kancelář ve Varšavě",
  "address": "Aleje Jerozolimskie 120, Varšava",
  "latitude": 52.2297,
  "longitude": 21.0122,
  "client": {
    "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
    "name": "Solar Corp",
    "address": "Hlavní 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 byla zachována 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í a zápisu.

Koncové body

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)

Ukázka 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í 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}/

Zahrňte pouze pole, která chcete aktualizovat:

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

Pravidla souřadnic

• latitude a longitude musí být vždy uvedeny společně.
• Zadání pouze jedné souřadnice způsobí validační chybu.
• Pokud není nastavena poloha, obě pole se vracejí jako null.

Filtry

6. API komponent

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

Koncový bod

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

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

Typy komponent

Jsou podporovány tři typy komponent: panel, inverter a other.

Fotovoltaický 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.
• Před vytvořením se ověří všechna pole specifická pro panel.

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é značky

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 používají u klientů a projektů. Ukládají se jako geografický bod a vracejí se jako samostatná pole:

"latitude": 52.2297,
"longitude": 21.0122

Práce s hodnotou null

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

8. Chování filtrů

Obecná pravidla

• Všechny filtry jsou volitelné, pokud není uvedeno jinak.
• Více filtrů se kombinuje logikou AND.
• Hodnoty vícevýběrových filtrů (např. category) interně používají logiku OR.
• Neplatné hodnoty filtrů vrací prázdné výsledky nebo validační chybu v závislosti na typu pole.

Filtry časového rozsahu

Dostupné napříč endpointy:

Textové vyhledávací filtry

Částečná shoda názvu a telefonního čísla bez ohledu na velikost písmen u name a phone:

?name=solar

Odpovídá: "Solar Corp", "Můj solární projekt" atd.

9. Model oprávnění

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

10. Práce s chybami

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 apod.) patří do stejného rozsahu společnosti.

11. Integrační vzory

Strategie synchronizace

Doporučený postup pro synchronizaci dat:

1. Načtěte výpisový endpoint (stránkovaně).
2. Uložte id jako externí referenci.
3. Pro přírůstkové synchronizace používejte pole updated.

Práce se stránkováním

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

Pro načtení pouze záznamů změněných od poslední synchronizace použijte datumové filtry:

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

Doporučené postupy filtrování

• Pro synchronizace s vysokým objemem upřednostňujte filtry založené na ID (client, status) před textovým vyhledáváním.
• Kombinací více filtrů zmenšíte velikost výsledné množiny.
• Vyhněte se širokým textovým vyhledáváním na velkých datových sadách.

12. Stabilita & 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í
• Schéma autentizace

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

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

Politika verzování

V URL není aktuálně zveřejněna žádná explicitní verze. Zlomové změny zavedou nový jmenný prostor endpointů:

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

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

Konec dokumentace