Jak połączyć się z API SON

Klucz, uwierzytelnianie, pierwsze zapytanie i limity - wszystko, czego potrzeba, aby bezpiecznie spiąć SON z innym narzędziem.

API to dodatkowe wejście do Twojego konta w Systemie Obsługi Najmu - przeznaczone dla programów, a nie dla przeglądarki. Pozwala innym narzędziom odczytywać i zapisywać dane bez logowania się ręcznie. Dzięki temu można automatyzować powtarzalne czynności (np. dodawanie najemców z formularza na stronie), spinać SON z innymi systemami (Make, n8n, własny backend) oraz podłączyć dane pod narzędzia AI typu ChatGPT.

Ten przewodnik przeprowadzi przez połączenie z API krok po kroku: od wygenerowania klucza, przez pierwsze zapytanie, po limity, które warto znać, zanim zbudujesz integrację.

Dla kogo jest ten przewodnik

• Kroki 1-2 (wygenerowanie i zabezpieczenie klucza) zrobisz sam w aplikacji SON - bez wiedzy technicznej.
• Krok 3 i dalej zakładają, że masz gotowe narzędzie do integracji (np. Make, n8n) albo osobę techniczną, która wpisze klucz w odpowiednie pole.
• Chcesz tylko połączyć SON z ChatGPT? Wygeneruj klucz (Krok 1) i przejdź od razu do sekcji Podłączenie pod ChatGPT.

W tym artykule

1. Wygeneruj klucz API
2. Ogranicz klucz do adresu IP
3. Pierwsze zapytanie
4. Limity zapytań
5. Dobre praktyki integracji
6. Podłączenie pod ChatGPT (opcjonalnie)

Krok 1 - Wygeneruj klucz API

W aplikacji SON wejdź w Ustawienia (ikona zębatki w prawym górnym rogu) → Użytkownicy i uprawnienia → zakładka Klucze API.

Kliknij „Wygeneruj nowy klucz”. W oknie „Wygeneruj klucz API” wypełniasz trzy pola: Opis (np. Make - produkcja     albo ChatGPT - odczyt     - żeby później wiedzieć, do czego służy), Ograniczenie IP oraz Status (włączony / wyłączony). Na koniec kliknij Zapisz.

Klucz przekazuje się do narzędzia jako nagłówek HTTP (w przykładach poniżej zapisany jako TWOJ_KLUCZ ):

X-SON-TOKEN: <Twój klucz>

Krok 2 - Ogranicz klucz do adresu IP

W oknie tworzenia klucza (a także później, przy edycji) dostępne jest pole „Ograniczenie IP” - najlepiej uzupełnić je od razu przy generowaniu. Wpisanie adresu IP serwera, z którego korzysta Twoja integracja, sprawia, że klucz zadziała wyłącznie z tego adresu.

To prosta, a bardzo skuteczna ochrona: nawet jeśli klucz wycieknie (trafi do logów, repozytorium, zrzutu ekranu), poza Twoim adresem IP będzie bezużyteczny.

Krok 3 - Pierwsze zapytanie

Najprościej zacząć od odczytu danych (w żargonie API: metoda GET - czyli samo pobieranie, bez zmieniania czegokolwiek).

→ Bez pisania kodu - w przeglądarce

Wejdź w interaktywną dokumentację: s3api.systemobsluginajmu.pl/v2, kliknij „Authorize”, wklej klucz i przetestuj dowolne zapytanie bezpośrednio w przeglądarce. To najszybszy sposób, żeby sprawdzić, że klucz działa.

→ Dla osób technicznych - curl    

curl   to polecenie uruchamiane w terminalu (wierszu poleceń). Jeśli nie wiesz, co to - pomiń ten fragment i skorzystaj z dokumentacji w przeglądarce powyżej. Poniższe zapytanie zwróci listę Twoich nieruchomości:

curl "https://s3api.systemobsluginajmu.pl/v2/estates" \
  -H "X-SON-TOKEN: TWOJ_KLUCZ"

Albo lista najemców, pobierana stronami (parametr per_page  - maks. 100 pozycji na stronę):

curl "https://s3api.systemobsluginajmu.pl/v2/tenants?per_page=25&page=1" \
  -H "X-SON-TOKEN: TWOJ_KLUCZ"

Limity zapytań

Aby serwer działał stabilnie dla wszystkich, zapytania do API są limitowane. Warto poznać te progi przed zbudowaniem integracji - dzięki temu unikniesz nieprzyjemnych niespodzianek na produkcji.

Limit liczby zapytań na minutę

Liczony w oknie jednej minuty, łącznie dla wszystkich kluczy konta:

Limit jednoczesnych zapytań

Niezależnie od limitu na minutę, ograniczona jest liczba równocześnie trwających zapytań (chroni to bazę danych). Liczone łącznie dla całego konta:

Co się stanie po przekroczeniu

W obu przypadkach odpowiedź zawiera nagłówek Retry-After z liczbą sekund do odczekania - wystarczy ponowić zapytanie po tym czasie. Pomocne są też nagłówki informacyjne przy każdej odpowiedzi:

• X-RateLimit-Limit  - obowiązujący limit,
• X-RateLimit-Remaining  - ile zapytań pozostało w bieżącym oknie,
• X-RateLimit-Reset  - kiedy okno się zresetuje.

Stronicowanie list (dla osób technicznych)

Przy pobieraniu list (najemcy, nieruchomości itd.) obowiązują reguły:

• rozmiar strony ustawia parametr per_page  (dawny size  nadal działa, ale jest przestarzały);
• domyślny rozmiar strony to 25, maksymalny 100 - wartość większa niż 100 zostaje przycięta do 100 (z ostrzeżeniem w polu meta.warning );
• per_page  mniejsze lub równe 0 albo nieliczbowe zwraca kod 422 ;
• iloczyn page × per_page  nie może przekroczyć 10 000 - powyżej tej granicy zwracany jest kod 422 . Przy bardzo dużych zbiorach warto skorzystać z paginacji kursorowej (parametr cursor  - sposób pobierania długiej listy po kawałku, wydajniejszy niż numery stron przy tysiącach rekordów).

Dobre praktyki integracji

Kilka nawyków, dzięki którym integracja będzie odporna na limity i awarie:

1. Ustaw u siebie progi z zapasem - np. 100/min dla odczytu zamiast 120 i 30/min dla zapisu zamiast 40. Bufor chroni przed przypadkowym przekroczeniem.
2. Reaguj na Retry-After - po kodzie 429 lub 503 odczekaj wskazaną liczbę sekund przed ponowieniem (mechanizm retry z backoffem, czyli rosnącym odstępem między próbami). To ustawienie po stronie narzędzia integracyjnego lub programisty - w narzędziach typu Make ponawianie po błędzie konfiguruje się klikaniem. Jeśli tylko klikasz w aplikacji, ten punkt Cię nie dotyczy.
3. Nie wysyłaj zbyt wielu zapytań naraz - maksymalnie 6 jednoczesnych odczytów i 3 zapisy. Lepiej kolejkować zapytania niż wysyłać wszystkie w jednej chwili.
4. Pobieraj dane stronami (per_page do 100), a przy bardzo dużych zbiorach przełącz się na cursor .
5. Zostań przy jednym kluczu na cel - dodatkowe klucze nie zwiększają limitów. Osobne klucze (inny do Make, inny do ChatGPT) ułatwiają odwołanie i namierzenie źródła nadużycia, ale - o ile klucze nie mają zawężonego zakresu - każdy z nich ma pełny dostęp. Dlatego kluczowi przekazanemu do AI odbieraj dostęp od razu po zakończeniu pracy.

Podłączenie SON pod ChatGPT (Custom GPT)

ChatGPT pozwala stworzyć własnego asystenta (Custom GPT) z tzw. akcją (Action), czyli możliwością wywoływania API. Wystarczy podać mu opis API w standardzie OpenAPI oraz klucz.

1. W ChatGPT wybierz Eksploruj GPT → Utwórz, przejdź do zakładki Skonfiguruj i kliknij Utwórz nowe działanie.
2. W polu Schemat wklej poniższy opis (obejmuje bezpieczny odczyt: nieruchomości i najemcy). Nie musisz rozumieć, co jest w tym schemacie - to gotowy opis, który mówi ChatGPT, jak sięgać po Twoje dane. Skopiuj go w całości i wklej:

openapi: 3.0.3
info:
  title: SON API (odczyt)
  version: "2.0"
servers:
  - url: https://s3api.systemobsluginajmu.pl/v2
paths:
  /estates:
    get:
      operationId: getEstates
      summary: Lista nieruchomości
      responses:
        "200": { description: OK }
  /tenants:
    get:
      operationId: getTenants
      summary: Lista najemców
      parameters:
        - name: per_page
          in: query
          schema: { type: integer, maximum: 100 }
        - name: page
          in: query
          schema: { type: integer }
      responses:
        "200": { description: OK }
components:
  securitySchemes:
    sonToken:
      type: apiKey
      in: header
      name: X-SON-TOKEN
security:
  - sonToken: []

3. W sekcji Uwierzytelnianie wybierz API Key, typ nagłówka ustaw na Custom, a jako nazwę nagłówka wpisz X-SON-TOKEN . W polu wartości wklej swój klucz (ten z opisem ChatGPT - odczyt , bez ograniczenia IP - patrz Krok 2).
4. Zapisz akcję. Gotowe - teraz możesz rozmawiać z własnymi danymi.

Przykładowe pytania do asystenta

• „Wypisz moje nieruchomości i liczbę pomieszczeń w każdej.”
• „Ilu mam najemców i którzy mają niepełne dane adresowe?”
• „Pokaż najemców pogrupowanych według miejscowości.”

^{System Obsługi Najmu - dokumentacja API. Stan na 03.07.2026. Adres bazowy: https://s3api.systemobsluginajmu.pl/v2 . Pełna interaktywna dokumentacja: s3api.systemobsluginajmu.pl/v2. Limity (łącznie dla całego konta): odczyt 120/min, zapis 40/min, eksporty 10/min; równocześnie 6 / 3 / 1. Po przekroczeniu - kod 429 lub 503 z nagłówkiem Retry-After .}