Dokumentacija vanjskog API-ja

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 kalendara
4. API projekata
5. API klijenata
6. API komponenti
7. Konvencije podataka
8. Ponašanje filtriranja
9. Model dopuštenja
10. Rukovanje pogreškama
11. Obrasci integracije
12. Stabilnost i verzioniranje

1. Autentikacija

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

Authorization: Api-Key <raw_api_key>

Napomene: - API ključeve stvaraju i njima upravljaju vlasnici i administratori tvrtke. - Svaki je ključ ograničen na određena dopuštenja 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, stigli ste do posljednje stranice.

3. API kalendara

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

Potrebno dopuštenje: 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 projekata

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

Potrebno dopuštenje: 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 se vraća kao decimalni niz radi očuvanja preciznosti. 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 klijenata

Predstavlja korisničke 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}/

Potrebna dopuštenja: clients_read (čitanje), clients_write (upis)

Primjer odgovora

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

Kreiranje 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žuriranje 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 za koordinate

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

Filtri

6. API komponenti

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

Krajnja točka

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

Potrebno dopuštenje: 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 stvaraju ako ne postoje.
• Jedinstvenost proizvođača vrijedi unutar tvrtke.
• Sva polja specifična za panel validiraju 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 polja datuma i vremena vraćaju se u formatu ISO 8601, 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

Obrada null vrijednosti

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

8. Ponašanje filtriranja

Opća pravila

• Svi filtri su opcionalni ako nije drukčije navedeno.
• Više filtara kombinira se logikom AND.
• Vrijednosti višestrukog odabira filtra (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 polja name i phone bez razlikovanja velikih i malih slova:

?name=solar

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

9. Model dopuštenja

Dopuštenja API ključa konfiguriraju se neovisno za svaki resurs:

10. Rukovanje pogreškama

Format pogreške

Opća pogreška:

{
  "detail": "Poruka pogreške"
}

Pogreška validacije na razini polja:

{
  "field_name": ["Poruka pogreške"]
}

Referenca pogrešaka

Kontrolni popis integracije

Ako naiđete na pogreške, provjerite:

1. API ključ ima odgovarajuća dopuštenja za resurs.
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 za sinkronizaciju podataka:

1. Dohvatite krajnju točku popisa (s paginacijom).
2. Pohranite id kao vanjsku referencu.
3. Za inkrementalnu sinkronizaciju koristite polje updated.

Rukovanje paginacijom

Krećite se kroz stranice povećavanjem offseta sve dok next nije 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 datuma za dohvat samo zapisa koji su se promijenili od posljednje sinkronizacije:

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

Najbolje prakse filtriranja

• Za sinkronizacije velikog volumena prednost dajte filtrima temeljenima na ID-ju (client, status) umjesto pretraživanja teksta.
• Kombinirajte više filtara kako biste smanjili broj rezultata.
• Izbjegavajte široka pretraživanja teksta nad 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 (kompatibilno unatrag)

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

Politika verzioniranja

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

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

Promjene koje proširuju funkcionalnost smatraju se kompatibilnima unatrag i mogu se uvesti bez promjene verzije.

Kraj dokumentacije