Appotio pomoć
API za rezervacije

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

  1. U Appotiju otvorite Postavke → Integracije i pritisnite Uključi API. To mogu vlasnik i administratori.
  2. Ključ se prikazuje samo jednom — kopirajte ga i spremite u postavke svog servera (npr. kao varijablu okruženja APPOTIO_API_KEY).
  3. 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

  1. Vaš server pošalje rezervaciju (POST /appointments). Termin još nije potvrđen (odgovor ima pending_confirmation: true) i dotad ne zauzima vrijeme: može ga rezervirati i netko drugi.
  2. 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.
  3. Ako klijent ne potvrdi u roku od 30 minuta (confirm_until u 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:

ŠtoKoliko
Svi zahtjevi120 u minuti
Rezervacije i prijave na grupne termine20 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:

StatuscodeZnačenje
401INVALID_API_KEYKljuč nedostaje, pogrešan je ili je zamijenjen novim
403ONLINE_BOOKING_OFFOnline rezervacije su isključene
403ACCESS_LAPSEDPretplata organizacije je istekla
422po polju, vidi doljeNeispravan zahtjev ili termin više nije slobodan
429Previše zahtjeva
502UNAVAILABLEAppotio 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." }
  }
}
KodPoljeZnačenje
SLOT_TAKENstart_timeNetko je upravo uzeo to vrijeme — ponovno učitajte slobodna vremena
DATE_OUT_OF_RANGEdateTaj dan se ne može rezervirati online (prošao je ili je predaleko)
USER_ID_PROHIBITEDuser_idOrganizacija sama dodjeljuje zaposlenika; ne šaljite user_id
USER_NOT_ELIGIBLEuser_idTaj zaposlenik ne radi tu uslugu
SESSION_NOT_FOUNDsessionGrupni termin više nije otvoren za prijave
SESSION_FULLsessionGrupni termin je popunjen
ALREADY_JOINEDsessionKlijent je već prijavljen
PENDING_EXISTScontactZa taj broj ili adresu već čeka rezervacija koju klijent nije potvrdio
CONTACT_LIMITcontactNa taj broj ili adresu danas je otišlo previše nepotvrđenih zahtjeva za potvrdu
PHONE_INVALIDphoneOrganizacija potvrdu šalje SMS-om, a taj broj ne postoji (npr. nedostaje znamenka)
SMS_PHONE_REQUIREDphoneOrganizacija potvrdu šalje SMS-om, a to nije broj mobitela na koji šaljemo SMS
REQUIRED, INVALID_OPTION, NUMERICanswers.NOdgovor na N-to pitanje grupnog termina
REQUIRED, EMAIL, REGEX, MAXbilo kojePolje nedostaje ili nije u ispravnom obliku

Klijentu prikažite svoju poruku prema kodu.

Na ovoj stranici