Zewnętrzna dokumentacja API

Integracja oparta na kluczu API daje Ci dostęp do Kalendarza, Projektów, Klientów i Komponentów. Dzięki temu możesz elastycznie integrować się ze swoimi systemami i automatyzować procesy.

Spis treści

1. Uwierzytelnianie
2. Paginacja
3. API kalendarza
4. API projektów
5. API klientów
6. API komponentów
7. Konwencje danych
8. Zachowanie filtrowania
9. Model uprawnień
10. Obsługa błędów
11. Wzorce integracji
12. Stabilność i wersjonowanie

1. Uwierzytelnianie

Wszystkie żądania muszą zawierać klucz API w nagłówku żądania.

Authorization: Api-Key <raw_api_key>

Uwagi: - Klucze API są tworzone i zarządzane przez właścicieli firmy oraz administratorów. - Każdy klucz ma zakres ograniczony do określonych uprawnień zasobów. - Wszystkie żądania są automatycznie przypisane do firmy powiązanej z kluczem API.

Błędy uwierzytelniania

2. Paginacja

Punkty końcowe listy (Kalendarz, Projekty, Klienci) korzystają z paginacji limit/offset.

Parametry

Struktura odpowiedzi

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

Gdy next ma wartość null, dotarłeś do ostatniej strony.

3. API kalendarza

Reprezentuje zaplanowane wydarzenia, takie jak spotkania, rozmowy telefoniczne i wizyty montażowe. Tylko do odczytu.

Punkty końcowe

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

Wymagane uprawnienie: calendar_read

Przykład odpowiedzi

{
  "id": "7d0f4d55-3b66-4c71-a86d-2b0ef2fca6d5",
  "category": "meeting",
  "subject": "Wstępna wizyta na miejscu",
  "description": "Omówienie wymagań dotyczących instalacji i inspekcja dachu.",
  "client": {
    "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
    "name": "Solar Corp",
    "address": "ul. Główna 10, Warszawa",
    "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"
}

Opis pól

Wartości kategorii

Zagnieżdżone obiekty

Obiekt klienta:

Obiekt uczestnika:

Filtry

Przykład:

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ów

Reprezentuje rekordy projektów powiązanych z klientami (np. instalacje fotowoltaiczne). Tylko do odczytu.

Punkty końcowe

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

Wymagane uprawnienie: projects_read

Przykład odpowiedzi

{
  "id": "d8e22cb9-1d88-4a3d-a3fd-f954d1f23d59",
  "name": "Instalacja fotowoltaiczna - biuro w Warszawie",
  "address": "Aleje Jerozolimskie 120, Warszawa",
  "latitude": 52.2297,
  "longitude": 21.0122,
  "client": {
    "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
    "name": "Solar Corp",
    "address": "ul. Główna 10, Warszawa",
    "phone": "+48123456789",
    "is_open": true
  },
  "status": {
    "name": "W trakcie realizacji",
    "order": 2
  },
  "currency": {
    "code": "PLN",
    "name": "Złoty polski"
  },
  "total_price": "42500.00",
  "payback_period": 8,
  "created": "2026-05-01T09:00:00Z",
  "updated": "2026-06-01T15:30:00Z"
}

Opis pól

total_price jest zwracane jako ciąg dziesiętny, aby zachować precyzję. payback_period ma wartość null, jeśli nie został jeszcze obliczony. latitude/longitude mają wartość null, jeśli nie ustawiono lokalizacji.

Zagnieżdżone obiekty

Obiekt statusu:

Obiekt waluty:

Filtry

Przykład:

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

5. API klientów

Reprezentuje encje klientów. Obsługuje operacje odczytu i zapisu.

Punkty końcowe

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

Wymagane uprawnienia: clients_read (odczyt), clients_write (zapis)

Przykład odpowiedzi

{
  "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
  "name": "Solar Corp",
  "description": "Klient komercyjny zainteresowany instalacją fotowoltaiczną na dachu.",
  "address": "ul. Główna 10, Warszawa",
  "latitude": 52.2297,
  "longitude": 21.0122,
  "phone": "+48123456789",
  "is_open": true,
  "created": "2026-05-01T10:15:00Z",
  "updated": "2026-06-01T08:45:30Z"
}

Opis pól

Utwórz klienta

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

{
  "name": "Nazwa klienta",
  "description": "Klient komercyjny",
  "address": "Adres",
  "phone": "+48123456789",
  "latitude": 52.2297,
  "longitude": 21.0122
}

Aktualizuj klienta

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

Uwzględnij tylko pola, które chcesz zaktualizować:

{
  "address": "Nowy adres 15, Warszawa",
  "phone": "+48987654321"
}

Zasady dotyczące współrzędnych

• latitude i longitude muszą być zawsze podawane razem.
• Podanie tylko jednej współrzędnej powoduje błąd walidacji.
• Jeśli nie ustawiono lokalizacji, oba pola są zwracane jako null.

Filtry

6. API komponentów

Tworzy komponenty do użycia w projektach. Tylko do zapisu.

Punkt końcowy

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

Wymagane uprawnienie: components_write

Typy komponentów

Obsługiwane są trzy typy komponentów: panel, inverter i other.

Moduł fotowoltaiczny

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

Falownik

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

Inne

{
  "type": "other",
  "name": "System montażowy",
  "unit": "pcs",
  "net_unit_price": "50.00"
}

Odpowiedź

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

Uwagi

• Producenci są tworzeni automatycznie, jeśli nie istnieją.
• Unikalność producenta jest ograniczona do firmy.
• Wszystkie pola specyficzne dla modułów fotowoltaicznych są walidowane przed utworzeniem.

7. Konwencje danych

Identyfikatory

Wszystkie identyfikatory zasobów są ciągami UUID, stabilnymi i globalnie unikalnymi w obrębie firmy:

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

Znaczniki czasu

Wszystkie pola datetime są zwracane w formacie ISO 8601, zawsze w UTC:

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

Geolokalizacja

Współrzędne dotyczą Klientów i Projektów. Są przechowywane jako punkt geograficzny i zwracane jako osobne pola:

"latitude": 52.2297,
"longitude": 21.0122

Obsługa wartości null

Pola, które nie są ustawione, są zwracane jako null — nigdy nie są pomijane w odpowiedzi.

8. Zachowanie filtrowania

Zasady ogólne

• Wszystkie filtry są opcjonalne, chyba że zaznaczono inaczej.
• Wiele filtrów jest łączonych logiką AND.
• Wartości filtrów wielokrotnego wyboru (np. category) wewnętrznie używają logiki OR.
• Nieprawidłowe wartości filtrów zwracają puste wyniki lub błąd walidacji, w zależności od typu pola.

Filtry zakresu dat

Dostępne w różnych punktach końcowych:

Filtry wyszukiwania tekstowego

Częściowe dopasowanie bez rozróżniania wielkości liter dla name i phone:

?name=solar

Dopasowania: "Solar Corp", "My Solar Project", itp.

9. Model uprawnień

Uprawnienia klucza API są konfigurowane niezależnie dla każdego zasobu:

10. Obsługa błędów

Format błędu

Błąd ogólny:

{
  "detail": "Komunikat błędu"
}

Błąd walidacji na poziomie pola:

{
  "field_name": ["Komunikat błędu"]
}

Odwołanie do błędów

Lista kontrolna integracji

Jeśli napotkasz błędy, sprawdź:

1. Czy klucz API ma odpowiednie uprawnienia do zasobów.
2. Czy konto firmy jest aktywne.
3. Czy wszystkie wartości filtrów (identyfikatory itd.) należą do tego samego zakresu firmy.

11. Wzorce integracji

Strategia synchronizacji

Zalecane podejście do synchronizacji danych:

1. Pobierz punkt końcowy listy (z paginacją).
2. Zapisz id jako odwołanie zewnętrzne.
3. Używaj pola updated do synchronizacji przyrostowej.

Obsługa paginacji

Przechodź przez strony, zwiększając offset, aż next będzie miało wartość 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

Synchronizacja przyrostowa

Używaj filtrów dat, aby pobierać tylko rekordy zmienione od ostatniej synchronizacji:

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

Najlepsze praktyki filtrowania

• W przypadku synchronizacji o dużym wolumenie preferuj filtry oparte na identyfikatorach (client, status) zamiast wyszukiwania tekstowego.
• Łącz wiele filtrów, aby zmniejszyć rozmiar zestawu wyników.
• Unikaj szerokiego wyszukiwania tekstowego w dużych zbiorach danych.

12. Stabilność i wersjonowanie

Gwarancje stabilności

Poniższe elementy nie ulegną zmianie bez migracji wersjonowanej:

• Adresy URL punktów końcowych
• Nazwy pól
• Format UUID
• Struktura paginacji
• Schemat uwierzytelniania

Mogą ulec zmianie (niełamliwe)

• Filtry opcjonalne (mogą zostać dodane nowe filtry)
• Rozszerzanie odpowiedzi (mogą zostać dodane nowe pola)

Polityka wersjonowania

W adresie URL obecnie nie jest udostępniona jawna wersja. Zmiany łamiące zgodność wprowadzą nową przestrzeń nazw punktów końcowych:

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

Zmiany rozszerzające są uznawane za niełamliwe i mogą być wdrażane bez zwiększania wersji.

Koniec dokumentacji