Urbaneta tagad ir publiska API — lūk, ko jūs varat ar to darīt
Pirms dažām nedēļām īpašumu pārvaldnieks man jautāja kaut ko, kas palika atmiņā. „Mēs izmantojam Urbaneta savām ēkām, bet mūsu grāmatvedības programmatūra ir pielāgota. Vai mēs varam izvilkt rēķinu datus automātiski, nevis eksportēt CSV katru mēnesi?"
Mana atbilde tad bija „vēl ne". Mana atbilde šodien ir citāda.
Urbaneta tagad ir publiska API. Tā ir dzīva, dokumentēta un gatava integrācijām. Ja esat izstrādātājs, īpašumu pārvaldības uzņēmums ar savu tehnisko komandu vai kāds, kurš vēlas pārtraukt datu kopēšanu starp sistēmām, tas ir jums.
Kas patiešām tika izlaists
Kopā tika izlaistas trīs lietas, un tās strādā kā komplekts:
1. API dokumentācija — publiska atsauce vietnē `/api-docs`, kas precīzi paskaidro, kādi endpoint pastāv, ko tie pieņem un ko atgriež. 2. API atslēgas — ierobežotas atļaujas, ko jūs saražojat savā admin panelī, lai autentificētu pieprasījumus. 3. Webhook — reāllaika paziņojumi, kas nosūta notikumus uz jūsu serveri, nevis liek jums vaicāt izmaiņas.
Iziesim cauri katrai.
API dokumentācija: karte
Pirmā lieta, kas vajadzīga, būvējot pret jebkuru API, ir skaidra dokumentācija. Mūsējā ir pieejama `/api-docs` galvenajā Urbaneta domēnā. Bez pieslēgšanās — tā ir publiska.
Tā sedz:
- Autentifikācija: Kā iekļaut savu API atslēgu `Authorization: Bearer` headerī. - Ēkas, dzīvokļi un iedzīvotāji: CRUD darbības pamat entitātēm. - Rēķini un skaitītāju rādījumi: Dati, kas īpašumu pārvaldniekiem patiešām rūp. - Webhook abonēšana: Kā reģistrēt un pārvaldīt webhook endpoint. - Kļūdu kodi: Ko `400`, `401`, `403` un `429` nozīmē praksē, plus ātruma ierobežošanas uzvedība.
Dokumentācija ir saražota no faktiskā API pirmkoda, tāpēc tā neize no datiem. Ja endpoint mainās, dokumentācija atjaunojas līdzi.
API atslēgas: ierobežotas, ne visvarenas
Lūk kaut kas, uz ko es uzstāju dizaina laikā: API atslēgām jābūt ierobežotām. Jūs nedrīkstat dot trešās puses integrācijai atslēgu, kas var dzēst ēkas tikai tāpēc, ka tā vajag lasīt rēķinu datus.
Savā admin panelī sadaļā Integrācijas → API atslēgas jūs varat izveidot atslēgas ar konkrētām atļaujām:
- `read:buildings` — uzskaitīt ēkas un dzīvokļus - `read:invoices` — izvilkt rēķinu datus - `write:invoices` — izveidot vai atjaunināt rēķinus - `read:residents` — iedzīvotāju direktorijas piekļuve - `webhooks:manage` — abonēt un pārvaldīt webhook endpoint
Jūs varat izveidot vairākas atslēgas dažādām integrācijām. Ja piegādātāja atslēga noplūst, jūs atsaucat tikai to vienu. Nav vajadzīgs mainīt visu.
Atslēgas sākas ar `nmv_`, lai tās būtu viegli pamanāmas žurnālos un koda pārskatos. Tās izmanto SHA-256 hashēšanu mūsu pusē, tāpēc pat datubāzes pārkāpums neatklāj faktiskos tokenu.
Webhook: pārtrauciet vaicāšanu, sāciet reaģēšanu
Šī ir tā, par kuru es personīgi esmu visvairāk sajūsmināts. Vaicāšana ir izšķērdīga. Ja pārbaudāt ik pēc 5 minūtēm, vai ir izveidots jauns rēķins, jūs veicat 288 pieprasījumus dienā datiem, kas varbūt mainījās divas reizes.
Ar webhook Urbaneta nosūta notikumus uz jūsu URL, kad tie notiek:
- `invoice.created` - `invoice.paid` - `resident.invited` - `maintenance_request.updated` - `meter_reading.submitted`
Jūs abonējat notikumus, kas jūs interesē, sadaļā Integrācijas → Webhook. Urbaneta nosūta POST pieprasījumu uz jūsu endpoint ar parakstītu saturu. Jūs pārbaudāt parakstu, apstrādājiet notikumu un esat pabeigis.
Mēs iekļaujam atkārtošanas mehānismu: ja jūsu endpoint atgriež ne-2xx statusu vai izslēdzas, mēs atkārtojam ar eksponenciālu atpakaļgaitu līdz 24 stundām. Piegāde ir vismaz vienreiz, tāpēc jūsu endpoint vajadzētu būt idempotentam. Mēs arī iekļaujam `X-Urbaneta-Event-ID` headerī, lai jūs varat deduplicēt vajadzības gadījumā.
Praktisks piemērs
Sakāsim, jūs vadāt īpašumu pārvaldības uzņēmumu ar ducīt ēku. Jūs vēlaties:
1. Izvilkt visus šā mēneša rēķinus savā grāmatvedības sistēmā. 2. Atzīmēt rēķinu kā samaksātu, kad bankas pārvedums ir noticis. 3. Informēt savu uzturēšanas komandu, kad iedzīvotājs iesniedz skaitītāja foto.
Pirms API tas bija manuāls CSV eksports, izklājlapu saskaņošana un telefona zvani. Tagad tas ir:
- Cron darbs, kas reizi dienā izsauc `GET /api/v1/invoices?created_after=2026-07-01`. - Webhook apstrādātājs `invoice.paid`, kas automātiski atjaunina jūsu reģistru. - Webhook apstrādātājs `meter_reading.submitted`, kas ziņo jūsu iekšējā Slack kanālā.
Visa integrācija var prasīt izstrādātājam dienu vai divas. Laika ietaupījums sākas nekavējoties.
Ko tas nozīmē īpašumu pārvaldniekiem
Ja neesat izstrādātājs, jūs varat domāt: „tas ir forši, bet es nerakstu kodu." Godīgi. Lūk kāpēc tas joprojām ir svarīgi:
Jūsu piegādātāji var integrēties. Ja izmantojat grāmatvedības rīku, uzturēšanas platformu vai iedzīvotāju komunikācijas lietotni, jūs varat lūgt viņus būvēt Urbaneta integrāciju. API un webhook dod viņiem visu vajadzīgo. Jūs iegūstat automātisku datu sinhronizāciju neaptiekot nevienu koda rindu.
White-label portāli paliek neatkarīgi. API atslēgas ir ierobežotas katram nomniekam. Ja vadāt white-label īpašumu pārvaldības portālu zem sava domēna, jūsu API atslēgas redz tikai jūsu datus. Nav starpnomnieku noplūdes.
Kas tālāk
Pašreizējā API sedz pamata īpašumu pārvaldības plūsmas: ēkas, iedzīvotāji, rēķini, skaitītāju rādījumi, uzturēšana un maksājumi. Mēs to paplašinām, pamatojoties uz to, ko integratori faktiski prasa.
Ja kaut ko būvējat un vajadzīgs endpoint, kas vēl neeksistē, dariet mums to zināmu. API ir izveidota, lai augtu — mēs dodam priekšroku nelielas, stabilas virsmas izlaišanai un papildināšanai, nevis masīvas specifikācijas būvēšanai, ko neviens neizmanto.
Sākšana
1. Atveriet `/api-docs` savā pārlūkā. Izlasiet autentifikācijas sadaļu. 2. Ejat uz savu admin paneli → Integrācijas → API atslēgas un izveidojiet testa atslēgu. 3. Veiciet savu pirmo pieprasījumu: `GET /api/v1/buildings` ar savu atslēgu headerī. 4. Ja vajadzīgi reāllaika notikumi, ejat uz Integrācijas → Webhook un reģistrējiet savu endpoint.
Dokumentācija ietver kopējamo `curl` piemērus katram endpoint. Jums nav jāmin saturu forma.
---
Gadu atpakaļ kāds man teica, ka īpašumu pārvaldības programmatūrai vajadzētu „vienkārši strādāt" bez integrācijām. Es kādreiz tā domāju. Tagad es domāju pretējo: labākā īpašumu pārvaldības platforma ir tā, kas savienojas ar visu pārējo, ko jūs jau izmantojiet.
Tieši to mēs būvējam.
