Dokumentacja zewnętrznego API

Integracja oparta na kluczu API daje Ci dostęp do kalendarza, projektów, klientów i komponentów.
Zapewnia to elastyczność integracji z Twoimi systemami i automatyzacji procesów.

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. Zasady 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 oraz administratorów firmy. - Każdy klucz ma zakres określonych uprawnień do zasobów. - Wszystkie żądania są automatycznie ograniczone do firmy powiązanej z kluczem API.

Błędy uwierzytelniania

2. Paginacja

Endpointy listujące (Kalendarz, Projekty, Klienci) korzystają z paginacji limit/offset.

Parametry

Struktura odpowiedzi

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

Gdy next ma wartość null, osiągnięto ostatnią stronę.

3. API kalendarza

Reprezentuje zaplanowane wydarzenia, takie jak spotkania, rozmowy telefoniczne i instalacje. Tylko do odczytu.

Endpointy

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 obiekcie",
  "description": "Omówienie wymagań instalacyjnych 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

Obiekty zagnieżdżone

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.

Endpointy

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 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.

Obiekty zagnieżdżone

Obiekt statusu:

Obiekt waluty:

Filtry

Przykład:

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

5. API klientów

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

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

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ą zawsze być podawane razem.
• Podanie tylko jednej współrzędnej skutkuje błędem 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.

Endpoint

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.

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

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ą automatycznie tworzeni, jeśli nie istnieją.
• Unikalność producenta obowiązuje w ramach każdej firmy.
• Wszystkie pola specyficzne dla paneli są walidowane przed utworzeniem.

7. Konwencje danych

Identyfikatory

Wszystkie identyfikatory zasobów to ciągi UUID, stabilne i globalnie unikalne w ramach firmy:

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

Sygnatury czasowe

Wszystkie pola daty i czasu 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. Zasady filtrowania

Zasady ogólne

• Wszystkie filtry są opcjonalne, chyba że zaznaczono inaczej.
• Wiele filtrów jest łączonych operatorem 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 we wszystkich endpointach:

Filtry wyszukiwania tekstowego

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

?name=fotowoltaika

Pasuje do: "Solar Corp", "Mój projekt fotowoltaiczny" itd.

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": "Error message"
}

Błąd walidacji na poziomie pola:

{
  "field_name": ["Error message"]
}

Opis błędów

Lista kontrolna integracji

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

1. Czy klucz API ma prawidłowe uprawnienia do zasobu.
2. Czy konto firmy jest aktywne.
3. Czy wszystkie wartości filtrów (ID itp.) należą do tego samego zakresu firmy.

11. Wzorce integracji

Strategia synchronizacji

Zalecane podejście do synchronizacji danych:

1. Pobierz endpoint listujący (z paginacją).
2. Przechowuj id jako zewnętrzny identyfikator referencyjny.
3. Używaj pola updated do synchronizacji przyrostowej.

Obsługa paginacji

Przechodź przez strony, zwiększając offset, aż next będzie 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żyj 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

• Preferuj filtry oparte na ID (client, status) zamiast wyszukiwania tekstowego przy synchronizacjach o dużej skali.
• Łącz wiele filtrów, aby zmniejszyć liczbę wyników.
• Unikaj szerokich wyszukiwań tekstowych w dużych zbiorach danych.

12. Stabilność i wersjonowanie

Stabilne gwarancje

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

• Adresy URL endpointów
• Nazwy pól
• Format UUID
• Struktura paginacji
• Schemat uwierzytelniania

Może ulec zmianie (bez naruszania zgodności)

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

Zasady wersjonowania

W adresie URL nie jest obecnie udostępniona jawna wersja. Zmiany niekompatybilne wstecz wprowadzą nową przestrzeń nazw endpointów:

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

Zmiany rozszerzające są uznawane za niełamiące zgodności i mogą być wdrażane bez zwiększania numeru wersji.

Koniec dokumentacji