Limity i bezpieczeństwo

Limity zapytań

Na minutę: 60 żądań na klucz, 240 na biuro (wszystkie klucze razem) i 120 z jednego adresu IP klienta. Zapisy liczą się do tych limitów i do własnych okien: 30 zapisów na klucz i 120 na biuro. Udane odpowiedzi mają X-RateLimit-Limit i X-RateLimit-Remaining dla okna klucza (przy zapisach dla okna zapisów). Odpowiedź 429 zawsze ma Retry-After (sekundy do końca okna) i nie ma nagłówków X-RateLimit-*. Gdy magazyn limitów jest niedostępny, API odmawia żądań z 429 zamiast obsługiwać je bez limitu.

Co zapisujemy w logach

Każdy uwierzytelniony odczyt zostawia wpis audytu: klucz, szablon ścieżki (/api/v1/leads/{id}, nigdy samo id), kod HTTP, liczba zwróconych rekordów i sieć /24 (IPv4) albo /48 (IPv6), z której przyszło żądanie. Bez wartości filtrów, identyfikatorów i danych z odpowiedzi.

Każda próba zapisu, także odrzucona, zostawia wpis z kluczem, zasobem, operacją (create, update, delete), id rekordu, nazwami wysłanych pól, kodem HTTP i siecią jak wyżej. Nigdy z wartościami.

Czego nie ma w v1

Nie ma trwałego usuwania klientów ani ofert (patrz tabela operacji), DELETE dla zapytań i transakcji ani operacji zbiorczych. Prowizje, rozliczenia, notatki wewnętrzne, publikacja na portalach i zdjęcia nie są zapisywalne. To API nie używa OAuth: tylko klucze. Asystenci AI (Claude) łączą się przez osobny serwer MCP chroniony OAuth pod adresem https://estalo.pl/api/mcp, który czyta przez ten sam rejestr i ten sam czytnik z zakresami, a z zakresami zmian zapisuje przez tę samą usługę zapisu w dwóch krokach (podgląd, potem potwierdzenie użytkownika): ai-assistant.md.

Izolacja danych biura

Każdy rekord w Estalo należy do jednego biura, a baza danych ma polityki bezpieczeństwa na poziomie wierszy (RLS) na każdej tabeli z danymi biura. API stosuje te same reguły co aplikacja:

• Odczyt zawsze filtruje po biurze klucza, potem po przypisaniu (dla ról innych niż kierownictwo), a na końcu pomija rekordy ukryte (kosz, zarchiwizowani klienci). Rekord innego biura odpowiada 404, tak jak nieistniejący.
• Zapis wykonuje się jako twórca klucza, przez te same funkcje co aplikacja webowa i mobilna, w ramach polityk RLS bazy. Baza dodatkowo sprawdza przy każdym zapisywanym wierszu, czy klucz ma zakres zapisu tego zasobu.
• Klucz nigdy nie widzi więcej niż jego twórca, a uprawnienia twórcy są sprawdzane przy każdym żądaniu: zmiana roli, odejście z biura albo brak aktywnego planu działają od następnego żądania.

Klucze i sekrety

• Estalo przechowuje tylko skrót SHA-256 klucza. Pełny klucz widzisz raz, przy tworzeniu; później tylko jego początek.
• Każdy klucz ma datę ważności (30, 90 albo 365 dni). Wymiana i unieważnienie działają od następnego żądania.
• Klucz z zakresem zapisu może utworzyć tylko właściciel z włączoną weryfikacją dwuetapową, a zapis musi być wcześniej włączony dla biura. Gdy twórca klucza wyłączy weryfikację dwuetapową albo właściciel wyłączy zmiany, klucz przestaje zapisywać.
• Sekret webhooka (whsec_…) jest pokazywany raz i przechowywany w postaci zaszyfrowanej.

Zalecenia dla integratora

• Trzymaj klucz po stronie serwera: w menedżerze sekretów albo zmiennej środowiskowej. Nigdy w kodzie strony WWW, aplikacji mobilnej, repozytorium, arkuszu ani w zgłoszeniu do pomocy technicznej.
• Jedna integracja, jeden klucz, tylko potrzebne zakresy. Zakres zapisu dawaj tylko tej integracji, która zapisuje.
• Wybieraj najkrótszą sensowną ważność i wymieniaj klucz przed jej końcem. Przy podejrzeniu wycieku unieważnij klucz od razu.
• Klucz widzi to co jego twórca. Do integracji, która ma widzieć całe biuro, klucz tworzy właściciel; klucz agenta zobaczy tylko rekordy agenta.
• Obsługuj 429 zgodnie z Retry-After. Ponawiaj zapisy z tym samym Idempotency-Key, a przy edycji wysyłaj expected_updated_at, żeby nie nadpisać cudzej zmiany.
• W odbiorniku webhooków weryfikuj podpis, odrzucaj stare znaczniki czasu, usuwaj duplikaty po X-Estalo-Event-Id, a aktualny stan rekordu pobieraj przez API.
• Nie zapisuj w logach nagłówka Authorization ani pełnych odpowiedzi API. Dane z API to dane osobowe klientów biura: przechowuj je tak jak pozostałe dane biura i tylko tak długo, jak potrzebuje ich integracja.

Zgłaszanie podatności

Podejrzenie podatności zgłoś prywatnie na biuro@programo.pl, nie w publicznym zgłoszeniu. Opisz wpływ i kroki odtworzenia (adres, żądanie, rola konta) i nie dołączaj prawdziwych kluczy ani danych klientów.