Zapis

Zmiana danych

Kto może zapisywać

Klucz zmienia dane tylko wtedy, gdy spełnione są wszystkie warunki:

1. Właściciel biura raz włączył zmiany przez API: Ustawienia › API i webhooki › Zmiany przez API. Potrzebny jest potwierdzony adres e-mail, a przy włączonej weryfikacji dwuetapowej sesja potwierdzona kodem. Do tego czasu klucze tylko czytają, a /me zwraca writes: not_activated.
2. Klucz ma zakres zapisu danego zasobu. Klucz z dowolnym zakresem zapisu może utworzyć albo wymienić tylko właściciel, który ma włączoną weryfikację dwuetapową i potwierdził to logowanie kodem.
3. Twórca klucza mógłby wprowadzić tę samą zmianę w Estalo. Zapis wykonuje się jako ta osoba, według tych samych reguł co aplikacja webowa i mobilna: członkostwo w biurze, rola, przypisane rekordy, limity planu, sprawdzanie duplikatów. Klucz agenta zmienia tylko rekordy agenta. Przypisanie rekordu do kogoś (assigned_user_id) jest dla właściciela, kierownika i dyrektora w planie dla biur.
4. Twórca klucza nadal ma włączoną weryfikację dwuetapową. Jeśli ją wyłączy, klucz dalej czyta, ale każdy zapis kończy się 401 api_key_inactive, dopóki jej nie włączy.
5. Twórca w tej chwili pracuje w biurze, do którego należy klucz. Jeśli przełączył się w Estalo na inne biuro, zapisy kończą się 409 creator_context_mismatch, dopóki nie wróci; nic nie zapisuje się gdzie indziej.

Właściciel może w tym samym miejscu ponownie wyłączyć zmiany (przy włączonej weryfikacji dwuetapowej potrzebne jest logowanie potwierdzone kodem). Klucze z zapisem nadal czytają, każdy zapis kończy się 403 writes_not_enabled, a nowego klucza z zapisem nie da się utworzyć, dopóki zmiany nie zostaną włączone ponownie.

Baza danych sprawdza zakres jeszcze raz przy każdym zapisywanym wierszu, więc klucz bez clients:write nie doda klienta nawet ścieżką kodu, o której byśmy zapomnieli.

Operacje

Zapytania i transakcje nie mają DELETE: zmieniasz ich status albo stage. Odpowiedź zawiera rekord w tym samym kształcie co GET, gdy klucz ma też zakres odczytu; w przeciwnym razie tylko { "id": … }.

Treść żądania to obiekt JSON (Content-Type: application/json) o rozmiarze do 64 KB. Pole nieznane albo tylko do odczytu kończy się 400 invalid_request z param; nic nie jest po cichu pomijane. Pola zapisywalne każdego zasobu są w dokumencie OpenAPI (ClientCreate, ClientUpdate, …) i w tabelach na stronie zasobów. W skrócie:

Uwagi: znaczniki czasu wymagają strefy czasowej. Zadanie łączy się z najwyżej jednym rekordem: wysłanie jednego related_* zastępuje powiązanie, null je usuwa. Ustawienie status zadania na done zapisuje completed_at; outcome wydarzenia zapisuje outcome_at. message zapytania zapisuje się jako treść zapytania, ale GET zwraca ją tylko dla importu maili; source: email_import jest zarezerwowane. Prowizja nie jest częścią API: transakcja utworzona przez API nie ma prowizji, dopóki ktoś jej nie uzupełni w Estalo.

Idempotencja

POST wymaga nagłówka Idempotency-Key; przy PATCH i DELETE jest opcjonalny, ale zalecany. Dla każdej zmiany użyj nowej, losowej wartości (UUID wystarczy, do 128 widocznych znaków ASCII) i używaj jej ponownie tylko przy ponawianiu tej samej zmiany. Przez 24 godziny:

• ten sam klucz z tą samą metodą, ścieżką i treścią zwraca ponownie pierwszą odpowiedź, z nagłówkiem Idempotent-Replayed: true, i niczego nie zmienia;
• ten sam klucz z innym żądaniem kończy się 422 idempotency_key_reused;
• dopóki pierwsze żądanie jeszcze trwa, 409 idempotency_in_progress: ponów za chwilę.

Odmowy wydane po przyjęciu żądania (na przykład 409 duplicate albo 402 plan_limit) są zapisywane i odtwarzane tak jak sukcesy. Odpowiedź 5xx nie jest zapisywana, więc możesz ponowić żądanie z tym samym kluczem.

Równoczesne zmiany

PATCH przyjmuje expected_updated_at: wartość updated_at, którą odczytałeś przed podjęciem decyzji o zmianie. Jeśli rekord zmienił się od tego czasu, odpowiedź to 409 conflict z aktualną wartością w details.updated_at; pobierz rekord jeszcze raz i zdecyduj ponownie. Bez tego pola wysłane pola nadpisują to, co jest w rekordzie (pozostałych pól zmiana nie dotyka).

Przykłady

Zastąp klucz i identyfikatory własnymi. Każdy POST potrzebuje własnego Idempotency-Key.

KEY="est_live_xxxxxxxxxxxx_<twój-klucz>"

# Klient
curl -s -X POST https://estalo.pl/api/v1/clients \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"first_name":"Anna","last_name":"Nowak","phone":"+48 600 000 000","type":"buyer"}'

curl -s -X PATCH https://estalo.pl/api/v1/clients/42 \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"status":"contacted","expected_updated_at":"2026-11-02T09:15:02.114+00:00"}'

curl -s -X DELETE https://estalo.pl/api/v1/clients/42 -H "Authorization: Bearer $KEY"

# Oferta
curl -s -X POST https://estalo.pl/api/v1/properties \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title":"2 pokoje, Jeżyce","price":649000,"type":"flat","address_city":"Poznań","area":48.5,"rooms":2}'

curl -s -X DELETE https://estalo.pl/api/v1/properties/0f6c2a1e-0000-4000-8000-000000000000 -H "Authorization: Bearer $KEY"

# Transakcja
curl -s -X POST https://estalo.pl/api/v1/deals \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title":"Jeżyce 2 pokoje","value":649000,"stage":"new","client_id":42,"property_id":"0f6c2a1e-0000-4000-8000-000000000000"}'

curl -s -X PATCH https://estalo.pl/api/v1/deals/7d1e0c2b-0000-4000-8000-000000000000 \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"stage":"negotiation"}'

# Wydarzenie w kalendarzu
curl -s -X POST https://estalo.pl/api/v1/events \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title":"Prezentacja","type":"meeting","start_time":"2026-11-05T10:00:00+01:00","end_time":"2026-11-05T11:00:00+01:00","client_id":42}'

# Zapytanie (na przykład z formularza na stronie biura)
curl -s -X POST https://estalo.pl/api/v1/leads \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"customer_name":"Jan Kowalski","email":"jan@example.com","message":"Czy oferta jest aktualna?","source":"www"}'

curl -s -X PATCH https://estalo.pl/api/v1/leads/a5d0c3f1-0000-4000-8000-000000000000 \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"status":"contacted"}'

# Zadanie
curl -s -X POST https://estalo.pl/api/v1/tasks \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title":"Oddzwonić","task_type":"call","due_date":"2026-11-03T09:00:00Z","related_client_id":42}'

curl -s -X PATCH https://estalo.pl/api/v1/tasks/3b9e1d40-0000-4000-8000-000000000000 \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"status":"done"}'

Błędy

Każdy błąd ma ten sam kształt i stały code:

{ "error": { "code": "insufficient_scope", "message": "…", "request_id": "…" } }

Niektóre błędy mają dodatkowo param (parametr, nagłówek albo pole, którego dotyczą) i details (identyfikatory i nazwy pól, nigdy dane innej osoby).

Rozgałęziaj logikę po code, nie po message. Odpowiedzi mają Cache-Control: no-store i X-Request-Id.