Vanjska API dokumentacija

Integracija putem API ključa omogućuje vam pristup kalendaru, projektima, klijentima i komponentama. To vam daje fleksibilnost za integraciju s vašim sustavima i automatizaciju procesa.

Sadržaj

1. Autentikacija
2. Paginacija
3. API za kalendar
4. API za projekte
5. API za klijente
6. API za komponente
7. Konvencije podataka
8. Ponašanje filtriranja
9. Model dozvola
10. Obrada pogrešaka
11. Obrasci integracije
12. Stabilnost & verzioniranje

1. Autentikacija

Svi zahtjevi moraju sadržavati API ključ u zaglavlju zahtjeva.

Authorization: Api-Key <raw_api_key>

Napomene: - API ključeve kreiraju i njima upravljaju vlasnici i administratori tvrtke. - Svaki je ključ ograničen na određene dozvole za resurse. - Svi su zahtjevi automatski ograničeni na tvrtku povezanu s API ključem.

Pogreške autentikacije

2. Paginacija

Krajnje točke za popis (Kalendar, projekti, klijenti) koriste limit/offset paginaciju.

Parametri

Struktura odgovora

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

Kada je next null, dosegli ste posljednju stranicu.

3. API za kalendar

Predstavlja zakazane događaje kao što su sastanci, pozivi i instalacije. Samo za čitanje.

Krajnje točke

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

Potrebna dozvola: calendar_read

Primjer odgovora

{
  "id": "7d0f4d55-3b66-4c71-a86d-2b0ef2fca6d5",
  "category": "meeting",
  "subject": "Početni obilazak lokacije",
  "description": "Raspraviti zahtjeve za instalaciju i pregled krova.",
  "client": {
    "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
    "name": "Solar Corp",
    "address": "Glavna ulica 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"
}

Referenca polja

Vrijednosti kategorije

Ugniježđeni objekti

Objekt klijenta:

Objekt sudionika:

Filtri

Primjer:

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 za projekte

Predstavlja zapise projekata povezane s klijentima (npr. fotonaponske instalacije). Samo za čitanje.

Krajnje točke

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

Potrebna dozvola: projects_read

Primjer odgovora

{
  "id": "d8e22cb9-1d88-4a3d-a3fd-f954d1f23d59",
  "name": "Fotonaponska instalacija - ured u Varšavi",
  "address": "Aleje Jerozolimskie 120, Varšava",
  "latitude": 52.2297,
  "longitude": 21.0122,
  "client": {
    "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
    "name": "Solar Corp",
    "address": "Glavna ulica 10, Varšava",
    "phone": "+48123456789",
    "is_open": true
  },
  "status": {
    "name": "U tijeku",
    "order": 2
  },
  "currency": {
    "code": "PLN",
    "name": "Poljski zlot"
  },
  "total_price": "42500.00",
  "payback_period": 8,
  "created": "2026-05-01T09:00:00Z",
  "updated": "2026-06-01T15:30:00Z"
}

Referenca polja

total_price vraća se kao decimalni niz kako bi se očuvala preciznost. payback_period je null ako još nije izračunat. latitude/longitude su null ako lokacija nije postavljena.

Ugniježđeni objekti

Objekt statusa:

Objekt valute:

Filtri

Primjer:

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

5. API za klijente

Predstavlja klijentske entitete. Podržava operacije čitanja i upisa.

Krajnje točke

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

Potrebne dozvole: clients_read (čitanje), clients_write (upis)

Primjer odgovora

{
  "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
  "name": "Solar Corp",
  "description": "Komercijalni klijent zainteresiran za krovnu fotonaponsku instalaciju.",
  "address": "Glavna ulica 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"
}

Referenca polja

Kreiraj klijenta

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

{
  "name": "Naziv klijenta",
  "description": "Komercijalni klijent",
  "address": "Adresa",
  "phone": "+48123456789",
  "latitude": 52.2297,
  "longitude": 21.0122
}

Ažuriraj klijenta

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

Uključite samo polja koja želite ažurirati:

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

Pravila koordinata

• latitude i longitude uvijek moraju biti navedeni zajedno.
• Navođenje samo jedne koordinate rezultira pogreškom validacije.
• Ako lokacija nije postavljena, oba se polja vraćaju kao null.

Filtri

6. API za komponente

Stvara komponente za korištenje u projektima. Samo za upis.

Krajnja točka

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

Potrebna dozvola: components_write

Vrste komponenti

Podržane su tri vrste komponenti: panel, inverter i 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
}

Ostalo

{
  "type": "other",
  "name": "Montažni sustav",
  "unit": "kom",
  "net_unit_price": "50.00"
}

Odgovor

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

Napomene

• Proizvođači se automatski kreiraju ako ne postoje.
• Jedinstvenost proizvođača ograničena je na tvrtku.
• Sva polja specifična za panele provjeravaju se prije stvaranja.

7. Konvencije podataka

ID-jevi

Svi identifikatori resursa su UUID nizovi, stabilni i globalno jedinstveni unutar tvrtke:

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

Vremenske oznake

Sva datetime polja vraćaju se u ISO 8601 formatu, uvijek u UTC-u:

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

Geolokacija

Koordinate se odnose na klijente i projekte. Pohranjuju se kao geografska točka i vraćaju kao zasebna polja:

"latitude": 52.2297,
"longitude": 21.0122

Rukovanje null vrijednostima

Polja koja nisu postavljena vraćaju se kao null — nikada se ne izostavljaju iz odgovora.

8. Ponašanje filtriranja

Opća pravila

• Svi su filtri opcionalni osim ako nije drugačije navedeno.
• Više filtara kombinira se logikom AND.
• Vrijednosti filtara s višestrukim odabirom (npr. category) interno koriste logiku OR.
• Neispravne vrijednosti filtra vraćaju prazne rezultate ili pogrešku validacije, ovisno o vrsti polja.

Filtri raspona datuma

Dostupno na svim krajnjim točkama:

Filtri pretraživanja teksta

Djelomično podudaranje neovisno o velikim i malim slovima za name i phone:

?name=solar

Podudara se s: "Solar Corp", "Moj fotonaponski projekt", itd.

9. Model dozvola

Dozvole API ključa konfiguriraju se neovisno po resursu:

10. Obrada pogrešaka

Format pogreške

Opća pogreška:

{
  "detail": "Poruka o pogrešci"
}

Pogreška validacije na razini polja:

{
  "field_name": ["Poruka o pogrešci"]
}

Referenca pogrešaka

Kontrolni popis integracije

Ako naiđete na pogreške, provjerite:

1. API ključ ima ispravne dozvole za resurse.
2. Račun tvrtke je aktivan.
3. Sve vrijednosti filtra (ID-jevi itd.) pripadaju istom opsegu tvrtke.

11. Obrasci integracije

Strategija sinkronizacije

Preporučeni pristup sinkronizaciji podataka:

1. Dohvatite krajnju točku za popis (s paginacijom).
2. Pohranite id kao vanjsku referencu.
3. Koristite polje updated za inkrementalne sinkronizacije.

Rukovanje paginacijom

Krećite se kroz stranice povećavajući offset dok next ne postane 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

Inkrementalna sinkronizacija

Koristite filtre prema datumu za dohvat samo zapisa promijenjenih od posljednje sinkronizacije:

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

Najbolje prakse filtriranja

• Prednost dajte filtrima temeljenima na ID-jevima (client, status) umjesto tekstualnim pretraživanjima pri sinkronizacijama velikog volumena.
• Kombinirajte više filtara kako biste smanjili veličinu skupa rezultata.
• Izbjegavajte široka tekstualna pretraživanja na velikim skupovima podataka.

12. Stabilnost i verzioniranje

Stabilna jamstva

Sljedeće se neće mijenjati bez verzionirane migracije:

• URL-ovi krajnjih točaka
• Nazivi polja
• UUID format
• Struktura paginacije
• Shema autentikacije

Podložno promjenama (bez narušavanja kompatibilnosti)

• Opcionalni filtri (mogu se dodati novi filtri)
• Obogaćivanje odgovora (mogu se dodati nova polja)

Politika verzioniranja

Trenutačno u URL-u nije izložena eksplicitna verzija. Promjene koje narušavaju kompatibilnost uvest će novi prostor imena krajnjih točaka:

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

Promjene koje dodaju sadržaj smatraju se promjenama bez narušavanja kompatibilnosti i mogu se objaviti bez povećanja verzije.

Kraj dokumentacije