API · Apartments
POST /v1/apartments — utwórz mieszkanie
Dodaje nowy obiekt mieszkania do konta wynajmującego. Mieszkanie zostaje utworzone w stanie setup.
POSThttps://api.mieszkanie.app/v1/apartments
Dodaje nowy obiekt mieszkania do konta wynajmującego. Mieszkanie zostaje utworzone w stanie setup — bez umów i bez historii rozliczeń. To pierwszy endpoint, który wywołasz, integrując zewnętrzny CRM.
Bearer (Clerk)Wymaga: apartments.writeIdempotentne
Opis
Tworzy mieszkanie wraz z jego cennikiem mediów (jeśli przekazany) i zwraca pełny obiekt z wygenerowanym id.
Efekty uboczne: wywołanie tworzy wpis w dzienniku audytowym i wyzwala webhook apartment.created.
Idempotencja
Powtórzenie wywołania z tym samym nagłówkiem Idempotency-Key w ciągu 24h zwróci to samo mieszkanie zamiast tworzyć duplikat.
Parametry
Body parameters
| Nazwa | Typ | Wymagane | Opis |
|---|---|---|---|
label | string | Wymagane | Etykieta widoczna w portalu i dla najemcy. Max 32 znaki. |
address | object | Wymagane | Adres mieszkania. Patrz pola zagnieżdżone. |
address.street | string | Wymagane | Ulica wraz z numerem. |
address.city | string | Wymagane | Miejscowość — bez słownika TERYT. |
address.postal_code | string | Opcjonalne | Format 00-000. |
surface_m2 | number | Opcjonalne | Metraż w m². Do proporcjonalnego dzielenia kosztów. |
tariffs | array | Opcjonalne | Cennik mediów. Może być pusty — uzupełnisz później. |
Przykład zapytania
curl -X POST https://api.mieszkanie.app/v1/apartments \ -H "Authorization: Bearer $MIESZKANIE_TOKEN" \ -H "Idempotency-Key: imp-a83-2026-04" \ -d '{ "label": "A83", "address": { "street": "Mokotowska 12/4", "city": "Warszawa" } }'
Odpowiedzi
201 Created· json
1
2
3
4
5
6
{ "id": "apt_2GhJ4kRz92", "label": "A83", "state": "setup", "created_at": "2026-05-10T11:24:08Z"}
Błędy
| Kod | HTTP | Co widzi operator |
|---|---|---|
validation_failed | 400 | „Sprawdź podświetlone pola formularza." |
label_conflict | 409 | „Mieszkanie o tej etykiecie już istnieje." |
plan_limit_reached | 403 | „Twój plan pozwala na 5 mieszkań." |
Limity wywołań
Standardowy limit zasobu
POST /v1/apartments jest limitowane do 60 wywołań/min i 5 000/dobę na klucz. Przekroczenie zwraca 429 rate_limited.
Wyzwalane webhooki
apartment.created— natychmiast po utworzeniu, payload to ten sam obiekt jak w odpowiedzi 201.audit.event— zdarzenieapartment.createdtrafia także do globalnego strumienia audytu.