API și webhookuri: programările salonului tău, acolo unde ai nevoie de ele
Contabila vrea programările lunii într-un tabel. Programul de newsletter vrea clientele noi. Site-ul făcut de vărul tău vrea să programeze direct în agendă. Pentru toate astea creezi o cheie în Slotora, o dai instrumentului și alegi ce are voie să vadă. Pentru Zapier sau Make nu-ți trebuie programator și nu plătești nimic în plus.
0 lei pe lună · 0% comision · fără limită de programări sau cliente · fără card la înregistrare · SMS-urile și extraopțiunile AI se plătesc din credite și nu pornesc până nu le activezi
Creează cont gratuitCe leagă saloanele de obicei
Zapier
Fiecare programare nouă prinsă de „Webhooks by Zapier” și trimisă mai departe: un rând în Google Sheets, un mesaj în Slack, o persoană nouă în lista de newsletter.
Make
Un scenariu care pornește la fiecare eveniment trimis de Slotora sau care citește, la o oră fixă, programările și clientele din ziua respectivă.
Contabila
O cheie care doar citește programările, cu prețul și ce s-a plătit pe fiecare. Dacă ascunzi datele de contact ale clientelor, cheia nu le vede nici ea.
Site-ul tău
Orele libere citite din API și o programare făcută pe aceleași reguli ca la recepție, fără să-i trimiți clientei un link către altă pagină.
Cheile: câte una pentru fiecare instrument
O cheie API o creează doar proprietara sau un administrator, din browser, la Setări → API și webhook-uri. Cheia apare o singură dată, ca s-o lipești imediat în instrument. Slotora păstrează doar o amprentă a ei, așa că nimeni n-o mai poate citi după aceea, nici noi.
Dă fiecărui instrument cheia lui: când revoci una, se oprește doar instrumentul acela. O cheie se oprește și singură când persoana care a creat-o nu mai administrează salonul. Poți avea până la 20 de chei active și până la 10 adrese de webhook.
Ce are voie o cheie
La creare bifezi ce poate face cheia. Cele trei permisiuni de citire sunt bifate de la început, programarea nu.
| Permisiune | Ce deschide |
|---|---|
| Citește programările | Programările cu numele clientei, serviciul, colega, prețul și ce s-a plătit, plus orele libere |
| Citește clientele | Nume, telefon și e-mail, limba și acordul pentru mesaje de marketing |
| Citește serviciile și echipa | Lista de servicii cu prețuri și durate, echipa și locațiile salonului |
| Face programări | O programare la o oră pe care salonul o oferă, ca de la recepție; oprită până o bifezi |
Totul circulă ca JSON, prin HTTPS, la adresa slotora.io/api/v1. Descrierea completă, pe care o înțeleg și instrumentele, este la /api/v1/openapi.json.
Regulile pe care le respectă orice cerere
Cheia merge în antetul Authorization, ca Bearer, sau în X-Api-Key, niciodată în adresă, unde ar ajunge în jurnalele altora. Orele vin în fusul orar al salonului, cu decalajul scris lângă ele, ca tabelul să arate aceeași oră ca agenda. Programările se citesc implicit de azi pe 31 de zile; un interval cerut poate avea cel mult 366 de zile.
Listele vin pe pagini de până la 100 de rânduri, 50 dacă nu ceri altfel, iar nextCursor duce la pagina următoare. O cheie poate face 120 de cereri pe minut; peste ele, răspunsul este 429, cu ora la care poți reveni.
O programare făcută prin API trece prin același cod ca una făcută la recepție: ora trebuie să fie liberă, iar clienta primește confirmarea obișnuită. Cu un Idempotency-Key, o cerere repetată în cinci minute nu face o a doua programare. Fiecare cerere a unei chei stă 30 de zile în jurnalul salonului.
Webhookuri: Slotora te anunță singur
Lipești adresa primită de la instrument, bifezi ce să trimitem și apeși „Adaugă webhook”. Slotora caută schimbările la fiecare sfert de oră, așa că un eveniment ajunge în cel mult vreo cincisprezece minute.
| Eveniment | Când pleacă |
|---|---|
| booking.created | S-a făcut o programare: online, la recepție, de recepționerul telefonic AI sau prin API |
| booking.updated | Programarea a fost mutată, dată altei colege, schimbată la preț sau marcată sosită, finalizată ori neprezentare |
| booking.cancelled | Programarea a fost anulată, de clientă sau de salon |
| client.created | A apărut o clientă nouă în listă |
| payment.recorded | S-au încasat bani pe o programare: numerar, card, transfer sau online |
Adresa trebuie să fie https, pe portul obișnuit, accesibilă pe internet; redirecționările nu se urmează.
Ce se întâmplă cu fiecare trimitere
Semnătura
Fiecare mesaj e semnat
Antetul Slotora-Signature are ora trimiterii și o semnătură HMAC-SHA256 a orei și a corpului, făcută cu secretul whsec_ al adresei, arătat o singură dată. Serverul tău o recalculează și refuză ce e mai vechi de cinci minute; Zapier și Make n-au nevoie de ea.
Răspunsul
Orice 2xx înseamnă primit
Dacă instrumentul nu răspunde în 10 secunde sau răspunde altceva, trimiterea se reia după 1, 5 și 30 de minute, apoi după 2, 6, 12 și 24 de ore: opt încercări în total.
Oprirea
O adresă care tot eșuează se oprește
După 15 eșecuri la rând sau trei zile numai cu eșecuri, trimiterea se oprește și primești o notificare. După ce repari adresa, o pornești din nou de pe aceeași pagină.
Testul
„Trimite un test”, fără date reale
Butonul trimite un mesaj semnat cu o programare de probă, ca Zapier sau Make să învețe câmpurile fără numele unei cliente adevărate.
Ce nu iese niciodată din Slotora
Notițele, ale clientei sau ale programării, și câmpul de atenționare nu apar nici în răspunsuri, nici în webhookuri. Adresa, CUI-ul, ziua de naștere, etichetele, punctele de fidelitate și salariile echipei nu sunt deloc în API.
Dacă ai ascuns de echipă telefoanele și e-mailurile clientelor, API-ul le ascunde la fel: vin goale, cu semnul contactsHidden. Fiecare clientă poartă și câmpul marketing.optedOut: când e adevărat, programul de newsletter trebuie s-o lase pe dinafară.
Sincer: ce nu face
- Nu e în catalogul Zapier sau Make
- Nu există încă o aplicație Slotora în cataloagele lor. Folosești modulele lor generale de webhook și de cereri HTTP, care nu cer nimic dintr-un catalog.
- Nu e în timp real
- Un eveniment ajunge în aproximativ un sfert de oră. Pentru o programare nouă, aplicația Slotora îți trimite oricum o notificare pe telefon, pe loc.
- Nu programează în afara regulilor
- Prin API nu poți pune o programare peste program, peste altă clientă sau la un preț ales de instrument. Excepțiile rămân ale recepției.
- Cheile se fac din browser
- În aplicația Slotora vezi cheile, webhookurile și jurnalul cererilor, dar o cheie nouă sau o adresă nouă le adaugi din browser.
Întrebări despre API
Costă ceva API-ul?
Nu. Cheile, cererile și webhookurile fac parte din Slotora, la 0 lei pe lună. Limita este de 120 de cereri pe minut pentru fiecare cheie.
Am nevoie de un programator?
Pentru Zapier sau Make, nu: lipești o adresă, apeși „Trimite un test” și potrivești câmpurile. Pentru un site sau un program făcut de tine, cine îl scrie are nevoie de descrierea de la /api/v1/openapi.json.
Poate o recepționeră să creeze o cheie?
Nu. Cheile și webhookurile le creează doar proprietara sau un administrator, iar o cheie se oprește singură când omul care a creat-o nu mai administrează salonul.
Pot trimite clientele noi direct în programul de newsletter?
Da, cu evenimentul client.created sau citind lista de cliente. Ține cont de marketing.optedOut: clientele care au refuzat mesajele de marketing nu trebuie adăugate.
Ce se întâmplă dacă îmi schimb instrumentul?
Revoci cheia veche, ștergi sau pui pe pauză adresa veche de webhook și faci una nouă pentru instrumentul nou. Celelalte chei merg mai departe neatinse.
Datele salonului tău, unde lucrezi deja
Deschizi contul, creezi o cheie pentru primul instrument și trimiți un test. Restul îl face Zapier, Make sau omul care îți ține site-ul.