API dla agentów AI

Ostatnia aktualizacja: 03.09.2026

Ta strona opisuje publiczne API serwisu Szambi — na tyle dokładnie, żeby asystent działający w imieniu użytkownika mógł zapisać go na listę oczekujących albo zgłosić firmę do programu partnerskiego bez zgadywania i bez wysyłania próbnych żądań. Opis maszynowy tego samego API znajdziesz w specyfikacji OpenAPI 3.1.

Punkty startowe

Odkrywanie zaczyna się od katalogu API w standardowej przestrzeni /.well-known/, zgodnie z RFC 9727. Strona główna ogłasza go nagłówkiem Link: </.well-known/api-catalog>; rel="api-catalog" oraz znacznikiem <link rel="api-catalog"> w sekcji <head>.

Adres	Co zawiera
/.well-known/api-catalog	Katalog API w formacie `application/linkset+json`: odnośniki do specyfikacji, tej dokumentacji i health-checku.
/openapi.json	Specyfikacja OpenAPI 3.1 — pola, limity długości, kody błędów.
/llms.txt	Skondensowany opis produktu, cennik i etap projektu. Stąd bierz odpowiedzi o produkcie, nie z API.
`Accept: text/markdown`	Każda podstrona wydana jako czysty markdown zamiast HTML-a. Ten sam plik leży też pod adresem podstrony z dopiskiem `index.md`.
/sitemap.xml	Pełna lista publicznych adresów.
/api/health	Stan usługi. Odpowiedź 200 oznacza, że API działa.

Zasady korzystania

Dwa endpointy zapisu przyjmują dane osobowe i wysyłają e-mail do wskazanej osoby. Dlatego obowiązują przy nich reguły twardsze niż zwykłe „nie przekraczaj limitu":

Zapis wykonuj tylko na wyraźną prośbę użytkownika. Zapisanie kogoś, kto o to nie prosił, wysyła mu e-mail, którego się nie spodziewa, i umieszcza jego dane w naszej bazie bez podstawy.
Znacznik zgody to moment zgody użytkownika, nie moment wysłania żądania. Pola consentTimestamp i zgodaTimestamp są dokumentacją zgody na przetwarzanie danych (RODO). Wpisz w nie czas, w którym użytkownik potwierdził, że zna politykę prywatności, w formacie ISO 8601 ze strefą czasową — bez strefy żądanie zostanie odrzucone kodem NO_CONSENT. Data poprawna, ale z przyszłości albo starsza niż 30 dni, wraca jako CONSENT_OUT_OF_WINDOW: zgody sprzed miesiąca nie przyjmiemy, trzeba ją odebrać na nowo.
Przesyłaj wyłącznie dane podane przez użytkownika. Adres e-mail musi być jego własny — to na niego idzie potwierdzenie z numerem referencyjnym. Nie uzupełniaj pól zgadywanymi wartościami.
Numer referencyjny pokaż użytkownikowi. refId z odpowiedzi 201 to jedyny identyfikator, po którym można później znaleźć zgłoszenie.
Odpowiedzi 409 nie ponawiaj. Oznacza, że zgłoszenie już istnieje — powtórzenie żądania niczego nie zmieni.
Przedstaw się w User-Agent. Nazwa agenta i adres kontaktowy pomagają odróżnić ruch asystentów od nadużyć, gdy patrzymy na limity.
Nie wywołuj /api/wizyta. To licznik wejść ludzi na stronę; odczyt treści przez agenta nie jest wizytą i zafałszowałby statystykę.

Serwis nie prowadzi sprzedaży i nie przyjmuje płatności. Lista pozycji wysłana w polu zamowienie jest deklaracją zainteresowania, a nie zamówieniem ani rezerwacją towaru — szczegóły w regulaminie.

Zapis na listę oczekujących

POST /api/waitlist — zapisuje osobę lub firmę na listę oczekujących na zestaw Szambi. Kluczem jest adres e-mail. Limit: 3 zapisy na godzinę z jednego adresu IP.

POST https://szambi.pl/api/waitlist
Content-Type: application/json

{
  "name": "Anna Kowalska",
  "email": "[email protected]",
  "phone": "+48 600 100 200",
  "consentTimestamp": "2026-09-03T10:15:00+02:00",
  "zamowienie": [{ "id": "zestaw", "ilosc": 1 }]
}

Wymagane: name (2–100 znaków), email (do 254 znaków), consentTimestamp. Opcjonalne: phone (do 20 znaków) oraz zamowienie — lista pozycji z cennika przedsprzedaży, każdy produkt najwyżej raz, ilość od 1 do 20:

zestaw — Zestaw Szambi (600 zł)
czujnik — Sam czujnik (500 zł)
stacja — Sama stacja bazowa (200 zł)

Zapis firmowy włącza się polem isBusiness: true (musi być booleanem) i wymaga dodatkowo companyName oraz taxId — NIP-u lub KRS-u zapisanego cyframi. Ceny i opis zamówienia liczy serwer z własnego cennika, więc kwot się nie przesyła.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "success": true,
  "refId": "SZB-7K2M9QX4",
  "position": 128,
  "message": "Zapisano na listę oczekujących."
}

Zgłoszenie do programu partnerskiego

POST /api/partner — zgłoszenie firmy instalacyjnej lub serwisowej do programu partnerskiego. Kluczem jest NIP: sprawdzana jest jego suma kontrolna, a firma już zgłoszona dostaje kod 409. Limit: 5 zgłoszeń na godzinę z jednego adresu IP.

POST https://szambi.pl/api/partner
Content-Type: application/json

{
  "imie": "Jan",
  "nazwisko": "Nowak",
  "firma": "Instalacje Nowak",
  "nip": "1234563218",
  "email": "[email protected]",
  "telefon": "+48 600 100 200",
  "wiadomosc": "Montujemy zbiorniki na Podlasiu.",
  "zgodaTimestamp": "2026-09-03T10:15:00+02:00"
}

Wymagane: imie (2–60 znaków), nazwisko (2–80), firma (2–160), nip (10 cyfr), email (do 254 znaków), zgodaTimestamp. Opcjonalne: telefon (do 20 znaków) i wiadomosc (do 1000 znaków). Przekroczenie któregokolwiek z tych limitów wraca jako FIELD_TOO_LONG z nazwą pola w komunikacie — wartości nie obcinamy za nadawcę. Odpowiedź 201 zawiera refId w formacie SZP-XXXXXXXX.

Zgłoszenie jest nawiązaniem kontaktu, nie zawarciem umowy — obszar działania i warunki współpracy ustalamy indywidualnie, poza serwisem.

Błędy i limity

Każdy błąd wraca jako JSON ze stałym kodem w polu error i komunikatem po polsku w polu message — dotyczy to również błędów sprzed walidacji, takich jak zepsuty JSON czy zbyt duże ciało żądania. Komunikat można pokazać użytkownikowi wprost; decyzje podejmuj po kodzie, bo treść komunikatów bywa poprawiana.

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": "DUPLICATE_EMAIL",
  "message": "Ten adres e-mail jest już na liście."
}

Kod	HTTP	Znaczenie
`INVALID_JSON`	400	Ciało żądania nie jest poprawnym JSON-em — parser odrzucił je przed walidacją pól.
`INVALID_NAME, NAME_TOO_LONG`	400	Imię krótsze niż 2 znaki albo dłuższe niż 100.
`INVALID_EMAIL, EMAIL_TOO_LONG`	400	Adres e-mail niepoprawny albo dłuższy niż 254 znaki.
`INVALID_PHONE, PHONE_TOO_LONG`	400	Telefon nie jest tekstem albo przekracza 20 znaków.
`INVALID_BUSINESS`	400	Pole isBusiness nie jest booleanem.
`NO_CONSENT`	400	Brak znacznika zgody albo zły format daty — wymagana strefa czasowa.
`CONSENT_OUT_OF_WINDOW`	400	Data poprawna, ale spoza okna: z przyszłości lub starsza niż 30 dni. U człowieka zwykle znaczy przestawiony zegar urządzenia.
`INVALID_ORDER`	400	Nieznana pozycja, powtórzony produkt albo ilość poza zakresem.
`INVALID_COMPANY, COMPANY_TOO_LONG, INVALID_TAX_ID`	400	Zapis firmowy bez nazwy firmy, nazwa dłuższa niż 160 znaków albo NIP/KRS spoza zakresu 9–14 cyfr. Wartości nie obcinamy za nadawcę.
`INVALID_IMIE, INVALID_NAZWISKO, INVALID_FIRMA, INVALID_NIP`	400	Braki w zgłoszeniu partnerskim; NIP ma sprawdzaną sumę kontrolną.
`FIELD_TOO_LONG`	400	Pole zgłoszenia partnerskiego przekracza swój limit znaków. Komunikat nazywa pole; wartości nie obcinamy za nadawcę.
`CORS_FORBIDDEN`	403	Żądanie z przeglądarki, której origin nie jest na liście dozwolonych. Klienta bez nagłówka Origin — agenta, curla, serwera — nie dotyczy.
`NOT_FOUND`	404	Nieznany adres pod /api — sprawdź ścieżkę w specyfikacji OpenAPI.
`DUPLICATE_EMAIL, DUPLICATE_NIP`	409	Zgłoszenie już istnieje. Ponowienie żądania niczego nie zmieni.
`PAYLOAD_TOO_LARGE`	413	Ciało żądania przekracza 10 kB. Skróć wiadomość albo listę pozycji.
`RATE_LIMITED`	429	Przekroczony limit żądań z jednego adresu IP.
`SERVER_ERROR`	500	Błąd serwera — zgłoszenie NIE zostało zapisane.

Limity liczone są per adres IP, a odpowiedź 429 niesie nagłówek Retry-After z liczbą sekund do ponowienia oraz standardowe nagłówki RateLimit-* z pozostałym budżetem i czasem odnowienia. Po 429 odczekaj czas z Retry-After zamiast ponawiać żądanie od razu.

Budżet zużywa każde żądanie POST, także odrzucone — zgłoszenie z błędem 400 kosztuje tyle samo, co zapisane. Przy trzech zapisach na godzinę dwie pomyłki w polach wyczerpują więc limit przed pierwszym udanym zapisem, dlatego pola sprawdzaj u siebie przed wysłaniem, a nie metodą prób. Pozostały budżet niesie nagłówek RateLimit-Remaining, dokładany również do odpowiedzi 400.

Kontakt

Aqsod Sp. z o.o.
Młynowa 80 / U1, 15-404 Białystok, Polska
E-mail: [email protected]
Telefon: +48 538 444 491

Problem ze specyfikacją albo pole, którego brakuje w opisie? Napisz — poprawimy dokumentację, zamiast kazać zgadywać.