Appotio pomoć
API za rezervacije

Pozivi

Svi pozivi API-ja za rezervacije, s parametrima i primjerima odgovora.

Svi pozivi idu na https://app.appotio.com/api/v1 (u primjerima {API}), s ključem u zaglavlju Authorization: Bearer sk_…. Odgovori su JSON; uz POST pošaljite Content-Type: application/json.

Datumi su GGGG-MM-DD, vremena HH:MM, sve po satu organizacije (timezone u podacima o organizaciji). Cijene su u eurima.

Organizacija

GET {API}/salon

Sve što obrazac treba za početak: organizacija, pravila rezervacije, usluge i zaposlenici. Mijenja se rijetko — slobodno ga spremite u predmemoriju na nekoliko minuta.

{
  "name": "Frizerski salon Petra",
  "slug": "salon-petra",
  "url": "https://salon-petra.appotio.com",
  "logo_url": null,
  "address": "Salonska ulica 12, 40000 Čakovec",
  "contact_phone": "040 123 456",
  "timezone": "Europe/Zagreb",
  "time_format": "24h",
  "week_starts_on": "monday",
  "country": "HR",
  "booking": {
    "employee_choice": "client",
    "confirm_channel": "sms",
    "sms_countries": ["HR"],
    "confirm_minutes": 30,
    "requires_approval": false,
    "lead_minutes": 120,
    "horizon_days": 60,
    "min_date": "2026-10-07",
    "max_date": "2026-12-06"
  },
  "categories": [{ "id": "01a0…", "name": "Šišanje" }],
  "services": [
    {
      "id": "01a0…",
      "name": "Muško šišanje",
      "description": null,
      "duration_minutes": 30,
      "price": 12,
      "anchor_price": 12,
      "anchor_date": "2026-09-10",
      "color": "blue",
      "category_id": "01a0…",
      "employee_ids": null,
      "group": false,
      "questions": []
    }
  ],
  "employees": [{ "id": 2, "name": "Ivana", "avatar_url": null }]
}
  • booking.employee_choice — "client": klijent smije birati zaposlenika (employees je popunjen); "auto": organizacija dodjeljuje sama, employees je prazan i user_id se ne šalje.
  • booking.confirm_channel — kojim kanalom klijent dobiva poruku za potvrdu: "sms" ili "email". Kad je "sms", broj klijenta mora biti broj mobitela u zemlji iz booking.sms_countries (zasad samo hrvatski); drugi se odbija kodom SMS_PHONE_REQUIRED, a broj koji ne postoji (npr. s jednom znamenkom manje) kodom PHONE_INVALID.
  • booking.min_date / max_date — prvi i zadnji dan koji se može rezervirati.
  • services[].employee_ids — tko radi uslugu; null znači svi.
  • services[].employee_prices — cijene po zaposleniku, redci user_id, price i anchor_price za svakog tko radi uslugu. Prazno je kad svi naplaćuju cijenu usluge; tada vrijedi price. Ako prikazujete cijenu, prikažite onu odabrane osobe.
  • services[].group — true je grupni termin: umjesto vremena birate jedan od grupnih termina.
  • services[].anchor_price i anchor_date — bazna cijena (NN 132/2026), koju zakon traži prikazati uz cijenu, npr. „12,00 € (10. 9. 2026.)”.

Slobodni dani

GET {API}/days?service_id=…&from=2026-10-07&to=2026-10-31
Parametar
service_idobaveznoUsluga koja nije grupna
from, toobaveznoRaspon; najviše 45 dana po pozivu, sužen na min_date–max_date
user_idSamo taj zaposlenik (kad employee_choice je "client")
{ "from": "2026-10-07", "to": "2026-10-31", "available": ["2026-10-08", "2026-10-09"] }

Dani koji nisu u available nemaju nijedno slobodno vrijeme — zasivite ih u kalendaru.

Slobodna vremena

GET {API}/availability?service_id=…&date=2026-10-09
Parametar
service_idobaveznoUsluga koja nije grupna
dateobaveznoDan unutar min_date–max_date
user_idSamo taj zaposlenik
{
  "date": "2026-10-09",
  "duration_minutes": 30,
  "recommended": [
    { "start_time": "08:00", "end_time": "08:30" },
    { "start_time": "12:30", "end_time": "13:00" }
  ],
  "slots": [
    { "start_time": "08:00", "end_time": "08:30" },
    { "start_time": "08:15", "end_time": "08:45" }
  ]
}

slots su sva slobodna vremena; recommended je do tri koja organizaciji najbolje odgovaraju (popunjavaju rupe u rasporedu) — dobro ih je ponuditi prva. S user_id svaki unos ima i user_id.

Rezervacija

POST {API}/appointments
{
  "service_id": "01a0…",
  "date": "2026-10-09",
  "start_time": "08:00",
  "user_id": 2,
  "first_name": "Ana",
  "last_name": "Horvat",
  "phone": "+385911234567",
  "email": "[email protected]",
  "notes": "Prvi put dolazim."
}
Polje
service_id, date, start_timeobaveznoVrijeme iz slots
user_idSamo kad employee_choice je "client"; bez njega organizacija bira sama
first_name, last_nameobaveznoDo 100 znakova
phoneobaveznoMeđunarodni oblik: +385911234567; mobitel kad organizacija potvrdu šalje SMS-om
emailobaveznoZa poruku za potvrdu, ako organizacija ne šalje SMS
notesNapomena organizaciji, do 500 znakova
localeJezik poruka klijentu: "hr" (zadano) ili "en"

Odgovor 201:

{
  "id": 1234,
  "date": "2026-10-09",
  "start_time": "08:00",
  "end_time": "08:30",
  "service_name": "Muško šišanje",
  "employee_name": "Ivana",
  "price": 12,
  "pending_confirmation": true,
  "confirm_until": { "date": "2026-10-07", "time": "18:42" }
}

Termin čeka da ga klijent potvrdi iz poruke do confirm_until (po satu organizacije). Recite klijentu da provjeri SMS ili e-poštu, prema booking.confirm_channel. Dok ga ne potvrdi, vrijeme nije njegovo: uzima ga onaj tko prvi potvrdi, pa i drugi klijent koji je isto vrijeme odabrao nakon njega. Tko zakasni, na stranici iz poruke vidi da je termin zauzet.

Zahtjev za potvrdu broji se ondje kamo ide: na broj kad organizacija potvrdu šalje SMS-om, na adresu e-pošte kad je šalje e-poštom. Na isti broj ili adresu u organizaciji može čekati samo jedna nepotvrđena rezervacija (PENDING_EXISTS), a u danu na jedan broj idu najviše tri nepotvrđena zahtjeva za potvrdu, na jednu adresu pet, u svim organizacijama zajedno (CONTACT_LIMIT). Potvrđeni se ne broje.

Ako je vrijeme u međuvremenu zauzeto, odgovor je 422 s kodom SLOT_TAKEN — ponovno učitajte slobodna vremena.

Grupni termini

Za uslugu s "group": true:

GET {API}/sessions?service_id=…
{
  "sessions": [
    {
      "id": "01a0…",
      "code": "a9gds5lu",
      "service_id": "01a0…",
      "date": "2026-10-18",
      "start_time": "18:00",
      "end_time": "20:00",
      "capacity": 12,
      "spots_left": 5,
      "employee_name": "Ivana",
      "confirm_channel": "sms"
    }
  ]
}

Popis ide pola godine unaprijed i uključuje popunjene (spots_left: 0) — prikažite ih kao „Popunjeno”. Grupni termin može slati samo e-poštu; tada je njegov confirm_channel "email".

POST {API}/sessions/{id}/join
{
  "first_name": "Mia",
  "last_name": "Kos",
  "phone": "+385911234567",
  "email": "[email protected]",
  "notes": null,
  "answers": ["Početnik"]
}

answers su odgovori na services[].questions usluge, istim redoslijedom. Svako pitanje ima label, type (text, number ili select), za select popis options, i required. Odgovor je isti kao kod rezervacije.

Na ovoj stranici