API za rezervacije
Rezervacije iz vlastitog sustava ili s vlastite web stranice, u vlastitom dizajnu.
Svaka organizacija u Appotiju ima svoju stranicu za rezervacije. Ako želite da se klijenti naručuju u vašem sustavu ili na vašoj web stranici, s obrascem koji izgleda kao ostatak stranice, vaš developer može koristiti API za rezervacije.
Kroz API vaš server može:
- dohvatiti organizaciju, usluge s cijenama i zaposlenike (ako ih klijent smije birati),
- doznati u koje dane i u koje vrijeme ima slobodnih termina,
- rezervirati termin,
- dohvatiti grupne termine i prijaviti klijenta na njih.
Sve što ste postavili pod Online rezervacije vrijedi i ovdje: najkraća najava, koliko unaprijed se može rezervirati, tko bira zaposlenika, odobravanje rezervacija i rok za otkazivanje.
Uključivanje
- U Appotiju otvorite Postavke → Integracije i pritisnite Uključi API. To mogu vlasnik i administratori.
- Ključ se prikazuje samo jednom — kopirajte ga i spremite u postavke svog
servera (npr. kao varijablu okruženja
APPOTIO_API_KEY). - Adresu API-ja kopirajte s iste kartice:
https://app.appotio.com/api/v1.
API radi samo dok su online rezervacije uključene i dok je pretplata aktivna.
Autentikacija
Svaki zahtjev nosi ključ u zaglavlju Authorization:
curl https://app.appotio.com/api/v1/salon \
-H "Authorization: Bearer sk_…"Ključ je tajna
API se poziva s vašeg servera, nikad izravno iz preglednika ili mobilne aplikacije: tko ima ključ, može rezervirati u ime vaše organizacije. Ne stavljajte ga u JavaScript web stranice, u aplikaciju ni u git repozitorij.
Izgubljen ključ ne može se ponovno prikazati — Appotio čuva samo njegov otisak. Na istoj kartici napravite novi ključ: stari tada odmah prestaje raditi. Isključi API poništava ključ bez zamjene.
Zaštita od spama je vaša
Appotio ne može znati tko je ispunio vaš obrazac — vidi samo vaš server. Zato:
- obrazac na svojoj stranici zaštitite od spama sami (npr. ograničenjem po IP adresi ili provjerom e-pošte),
- prije poziva provjerite podatke koje je klijent upisao.
Rezervacija preko API-ja ponaša se kao rezervacija na našoj stranici: klijent dobije poruku za potvrdu kanalom koji ste odabrali pod Obavijesti za klijente — pa i SMS-om, koji se plaća iz vašeg salda. Lažne rezervacije koje propustite troše saldo.
E-pošta klijentima ima i dnevnu granicu, zajedničku s terminima upisanima u kalendar: zahtjev za potvrdu koji ide e-poštom broji se kao prva poruka novom klijentu. Kad je granica dosegnuta, poruka ne odlazi, klijent nema što potvrditi i rezervacija nakon 30 minuta nestaje. Kad se to dogodi, javljamo vam u zvoncu u aplikaciji.
Kako ide rezervacija
- Vaš server pošalje rezervaciju (
POST /appointments). Termin još nije potvrđen (odgovor imapending_confirmation: true) i dotad ne zauzima vrijeme: može ga rezervirati i netko drugi. - Klijent dobije poruku (e-poštu ili SMS) s poveznicom. Otvaranjem poveznice termin je potvrđen — ako je vrijeme još slobodno. Tko prvi potvrdi, njegov je termin; onaj tko zakasni na stranici vidi da je zauzet.
- Ako klijent ne potvrdi u roku od 30 minuta (
confirm_untilu odgovoru), termin se briše.
Ako organizacija odobrava rezervacije, nakon potvrde klijenta termin čeka i odobrenje organizacije.
Kojim će kanalom stići poruka piše u booking.confirm_channel ("email" ili "sms")
— recite klijentu gdje da je potraži.
Ograničenja
Ograničenja štite naš server i broje se po ključu:
| Što | Koliko |
|---|---|
| Svi zahtjevi | 120 u minuti |
| Rezervacije i prijave na grupne termine | 20 u minuti, 200 na sat |
Svaki odgovor ima zaglavlja X-RateLimit-Limit i X-RateLimit-Remaining.
Prekoračenje vraća 429 sa zaglavljem Retry-After (u sekundama).
Greške
Greške imaju message (za developera, na engleskom) i code:
| Status | code | Značenje |
|---|---|---|
401 | INVALID_API_KEY | Ključ nedostaje, pogrešan je ili je zamijenjen novim |
403 | ONLINE_BOOKING_OFF | Online rezervacije su isključene |
403 | ACCESS_LAPSED | Pretplata organizacije je istekla |
422 | po polju, vidi dolje | Neispravan zahtjev ili termin više nije slobodan |
429 | Previše zahtjeva | |
502 | UNAVAILABLE | Appotio trenutačno nije dostupan; pokušajte ponovno |
Greška 422 ima kod po polju:
{
"message": "That time is no longer available.",
"errors": {
"start_time": { "code": "SLOT_TAKEN", "message": "That time is no longer available." }
}
}| Kod | Polje | Značenje |
|---|---|---|
SLOT_TAKEN | start_time | Netko je upravo uzeo to vrijeme — ponovno učitajte slobodna vremena |
DATE_OUT_OF_RANGE | date | Taj dan se ne može rezervirati online (prošao je ili je predaleko) |
USER_ID_PROHIBITED | user_id | Organizacija sama dodjeljuje zaposlenika; ne šaljite user_id |
USER_NOT_ELIGIBLE | user_id | Taj zaposlenik ne radi tu uslugu |
SESSION_NOT_FOUND | session | Grupni termin više nije otvoren za prijave |
SESSION_FULL | session | Grupni termin je popunjen |
ALREADY_JOINED | session | Klijent je već prijavljen |
PENDING_EXISTS | contact | Za taj broj ili adresu već čeka rezervacija koju klijent nije potvrdio |
CONTACT_LIMIT | contact | Na taj broj ili adresu danas je otišlo previše nepotvrđenih zahtjeva za potvrdu |
PHONE_INVALID | phone | Organizacija potvrdu šalje SMS-om, a taj broj ne postoji (npr. nedostaje znamenka) |
SMS_PHONE_REQUIRED | phone | Organizacija potvrdu šalje SMS-om, a to nije broj mobitela na koji šaljemo SMS |
REQUIRED, INVALID_OPTION, NUMERIC | answers.N | Odgovor na N-to pitanje grupnog termina |
REQUIRED, EMAIL, REGEX, MAX | bilo koje | Polje nedostaje ili nije u ispravnom obliku |
Klijentu prikažite svoju poruku prema kodu.