--- title: "API dla agentów AI — Szambi" description: "Dokumentacja publicznego API Szambi: katalog API wg RFC 9727, specyfikacja OpenAPI, zapis na listę oczekujących i zgłoszenia partnerskie wykonywane przez agentów AI w imieniu użytkownika." source: "https://szambi.pl/dla-agentow/" language: pl --- # 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](https://szambi.pl/openapi.json). ## Punkty startowe Odkrywanie zaczyna się od katalogu API w standardowej przestrzeni `/.well-known/`, zgodnie z [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727). Strona główna ogłasza go nagłówkiem `Link: ; rel="api-catalog"` oraz znacznikiem `` w sekcji ``. | Adres | Co zawiera | | --- | --- | | [/.well-known/api-catalog](https://szambi.pl/.well-known/api-catalog) | Katalog API w formacie `application/linkset+json`: odnośniki do specyfikacji, tej dokumentacji i health-checku. | | [/openapi.json](https://szambi.pl/openapi.json) | Specyfikacja OpenAPI 3.1 — pola, limity długości, kody błędów. | | [/llms.txt](https://szambi.pl/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](https://szambi.pl/sitemap.xml) | Pełna lista publicznych adresów. | | [/api/health](https://szambi.pl/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](https://szambi.pl/polityka-prywatnosci), 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](https://szambi.pl/regulamin). ## 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": "anna.kowalska@example.com", "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](https://szambi.pl/dla-instalatorow). 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": "kontakt@example.com", "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: [kontakt@aqsod.com](mailto:kontakt@aqsod.com) Telefon: [+48 538 444 491](tel:+48538444491) Problem ze specyfikacją albo pole, którego brakuje w opisie? Napisz — poprawimy dokumentację, zamiast kazać zgadywać.