Pe scurt
- API-ul v1 are cinci operații: căutarea pacientului după telefon, crearea pacientului, lista medicilor, lista programărilor și crearea unei programări.
- Poți crea câte o cheie API pentru fiecare sistem conectat, afișată o singură dată și revocabilă separat; cheile și webhook-urile le gestionează proprietarul clinicii în Setări → Integrări.
- Webhook-urile anunță programarea nouă, mutată, confirmată, anulată sau ștearsă și pacientul nou, indiferent dacă schimbarea vine din calendar, din programarea online, de pe WhatsApp sau din API; fiecare cerere e semnată cu HMAC-SHA256.
- Observațiile din programări și din fișa pacientului nu se transmit nici prin API, nici prin webhook-uri.
- API-ul și webhook-urile sunt disponibile doar pe planul Enterprise; documentația completă e publică pe perlato.ro/dezvoltatori.
Ce poți face prin API
| Operație | Cerere |
|---|---|
| Caută pacient după telefon | GET /api/v1/patients?phone= |
| Creează pacient (doar telefonul e obligatoriu) | POST /api/v1/patients |
| Lista medicilor | GET /api/v1/doctors |
| Programările dintr-un interval | GET /api/v1/appointments?from=&to= |
| Creează programare | POST /api/v1/appointments |
Căutarea întoarce o listă, pentru că pe același telefon pot exista mai mulți pacienți (de exemplu un copil pe numărul părintelui). Fiecare pacient vine cu următoarea lui programare. Crearea pacientului și a programării este sigură la reîncercare: dacă există deja pacientul sau aceeași programare activă, primești înregistrarea existentă, nu o dublură.
Programarea creată prin API apare imediat în calendar cu sursa „Telefon”, trece prin aceeași verificare de suprapuneri ca la recepție (medic ocupat sau blocare în calendar → eroare 409) și primește reminderul obișnuit de la clinică. Ora trimisă fără fus orar este înțeleasă ca ora României.
Exemplu: centrala telefonică
- La apel
Centrala caută numărul apelantului. Dacă există pacient, medicul sau recepția văd numele și următoarea programare.
- Număr necunoscut
Centrala creează pacientul doar cu telefonul. Apelul se poate repeta fără să apară dubluri; medicul completează numele în fișă.
- Programare din apel
Operatorul alege medicul și ora, iar centrala creează programarea. Dacă intervalul e ocupat, primește 409 și propune altă oră.
Despre ce trebuie verificat la furnizorul centralei, din perspectiva GDPR, vezi ghidul de mai jos.
Webhook-uri: agenda te anunță singură
La configurare alegi evenimentele dorite: pacient nou, programare nouă, mutată (oră, durată sau medic), confirmată, anulată sau ștearsă. Perlato trimite un POST JSON la adresa ta, iar cererea poartă antetul X-Perlato-Signature, calculat ca HMAC-SHA256 cu secretul webhook-ului. Documentația publică include exemple de verificare în Python și Node.js.
- Răspunzi cu orice cod 2xx în cel mult 10 secunde; altfel livrarea se reîncearcă după 30 de secunde, 2 minute, 10 minute, 1 oră și 6 ore, apoi e marcată eșuată.
- Aceeași livrare poate sosi de două ori; identificatorul din corp te ajută să ignori dublurile.
- Adresa trebuie să fie https pe portul 443 și publică; adresele din rețele interne sunt refuzate.
- Din Setări → Integrări poți trimite un eveniment de test și vezi istoricul livrărilor.
Securitate și date
- Cheia API stă doar pe serverul sistemului conectat, nu în browser sau în aplicații mobile. Se afișează o singură dată la creare și se revocă imediat din Setări → Integrări.
- Limite: 120 de cereri pe minut și 500 de creări pe zi pentru fiecare cheie; peste limită răspunsul este 429.
- Programările pot fi citite pentru ultimele 31 de zile și viitor, pe intervale de cel mult 62 de zile; API-ul nu este o arhivă.
- Observațiile medicale nu sunt expuse. Numele, telefonul, emailul și datele programărilor sunt date personale: sistemul care le primește intră în evidența GDPR a clinicii.
În ce plan e și cum se activează
API-ul și webhook-urile sunt incluse în planul Enterprise, care pornește de la 349 lei/lună (279 lei/lună la plata anuală), cu 5 medici incluși. Integrarea asistată cu sistemele clinicii (configurare și teste împreună cu furnizorul) costă 1.500 lei, o singură dată. Enterprise se activează după o discuție scurtă: scrie la contact@perlato.ro sau cere un demo. Dezvoltatorii găsesc referința completă pe perlato.ro/dezvoltatori.
Întrebări frecvente
Ce plan include API-ul?
Doar Enterprise. Pe Starter și Pro, rutele de gestionare a cheilor și API-ul v1 răspund cu eroarea 403.
Cine poate crea chei API?
Doar proprietarul clinicii, din Setări → Integrări. Recomandăm câte o cheie pentru fiecare sistem conectat, ca s-o poți revoca separat.
Pot primi observațiile medicale ale programărilor?
Nu. Observațiile nu sunt întoarse de API și nu sunt trimise în webhook-uri, pentru că pot conține informații medicale.
Ce fac dacă serverul meu e oprit când vine un webhook?
Perlato reîncearcă livrarea de cinci ori, în decurs de aproximativ 7 ore, apoi o marchează eșuată. Livrările eșuate rămân vizibile în Setări → Integrări.
Încearcă gratuit 14 zile
Cardul se introduce la înscriere, dar nu se încasează nimic în perioada de probă. Anulezi oricând din aplicație.
Vezi planurile și prețurile