Vânzare

API & Webhooks în HoReCaOS: ghid integratori

4 min de cititGhid HoReCaOS5 întrebări frecvente

Pagina API & Webhooks din HoReCaOS e locul unde legi sistemul restaurantului de lumea din afară: AI-uri precum Claude sau ChatGPT, servere externe și orice integrare program-la-program. E un episod tehnic, așa că mergem pe fiecare card, câmp și buton, cu capcanele care contează. O găsești la Tools → API (URL: /tools/api).

Conectează AI-ul tău (fără cod)#

Primul card, Conectează AI-ul tău, e cel mai simplu și nu cere programare. Legi HoReCaOS de contul tău de Claude sau ChatGPT și îți întrebi datele direct din chat: meniul, comenzile zilei, stocurile scăzute, rezervările. Folosești abonamentul tău de AI, iar accesul este doar de citire — AI-ul vede, nu modifică.

Pași:

1. Apasă Copiază lângă Adresa conectorului.
2. În Claude (Desktop, web sau mobil): Setări → Connectors → Add custom connector, lipești adresa, dai Add. Ești adus înapoi în HoReCaOS ca să aprobi — apoi ești conectat.
3. În ChatGPT: Settings → Connectors → Create (necesită Developer Mode activat), lipești adresa, faci autentificarea OAuth și aprobi pe ecranul HoReCaOS.

Aplicațiile legate apar în Aplicații conectate. Inițial scrie „Nicio aplicație conectată încă." Capcana clasică: dacă lipești adresa dar nu revii să aprobi în HoReCaOS, conexiunea nu se finalizează.

Chei API (zzk_, doar citire)#

Cardul Chei API e pentru integrări program-la-program, nu pentru AI conversațional. Apeși Generează cheie API și primești o cheie care începe cu zzk_, cu acces doar de citire.

Reguli esențiale:

• Cheia se afișează o singură dată, la generare. Copiaz-o și păstreaz-o într-un loc sigur (secrets manager, variabilă de mediu pe server).
• Nu o pune niciodată în cod public, în front-end sau în repository.
• Dacă o pierzi sau se compromite, generezi una nouă și o ștergi pe cea veche.

Inițial pagina arată „Nu ai chei API generate."

Webhooks (notificări către tine)#

Cardul Webhooks funcționează invers față de cheile API: HoReCaOS îți trimite ție o notificare HTTP când se produce un eveniment, de exemplu o comandă nouă. Apeși Webhook nou, introduci URL-ul serverului tău care ascultă și alegi evenimentele.

Bune practici:

• Endpoint-ul tău trebuie să răspundă rapid cu 200 OK; dacă întârzie sau pică, livrarea eșuează și se reîncearcă.
• Fă procesarea grea asincron — răspunde imediat, procesează după.
• Validează că cererea vine chiar de la HoReCaOS înainte să acționezi pe baza ei.

Inițial: „Niciun webhook."

API REST /api/v1#

Toate endpoint-urile sunt versionate sub /api/v1. Cele afișate:

• GET /api/v1/menu — meniul
• GET /api/v1/orders — lista comenzilor
• POST /api/v1/orders — creezi o comandă
• GET /api/v1/openapi.json — schema OpenAPI completă (utilă pentru generare automată de cod)

Autentificarea se face prin header Authorization: Bearer <cheie>. Ai două opțiuni:

• Cheie API (zzk_...) — doar citire. Perfectă pentru dashboards, rapoarte, sincronizări read-only.
• Token de utilizator obținut prin POST /api/v1/auth/login (cu PIN) — acces complet conform rolului. E necesar pentru operații de scriere, cum ar fi POST /api/v1/orders. Ce poate face token-ul depinde de rolul utilizatorului: un cont de ospătar nu are drepturile unui manager.

Detaliile complete sunt în link-ul „Toate endpoint-urile, erorile și exemplele →" (/tools/api/docs#endpoints).

Server MCP (pentru agenți AI)#

Ultimul bloc, Server MCP — referință, e stratul tehnic din spatele conectării AI-ului. Prin protocolul MCP, agenții descoperă uneltele disponibile: get_menu, get_orders_today, get_low_stock, get_reservations_today.

Detalii tehnice: POST /api/mcp, JSON-RPC 2.0 (Streamable HTTP), autentificare prin OAuth 2.1 sau cheie API. Descoperirea OAuth se face la /.well-known/oauth-protected-resource.

Pentru conectarea obișnuită folosește cardul Conectează AI-ul tău (OAuth, fără chei de lipit). Varianta cu cheie API rămâne doar pentru clienți MCP care nu fac OAuth, cum ar fi o configurare locală. Ghidul dedicat e la „Configurarea completă pentru Claude →" (/tools/api/docs#mcp).

Întrebări frecvente#

Trebuie să fiu programator ca să conectez AI-ul? Nu. Cardul Conectează AI-ul tău merge pe OAuth: copiezi adresa, o lipești în Claude sau ChatGPT și aprobi. Fără cod.

De ce nu-mi mai văd cheia API? Cheia zzk_ se afișează o singură dată, la generare. Dacă nu ai salvat-o, generează una nouă și șterge-o pe cea veche.

Care e diferența dintre cheia API și token-ul de utilizator? Cheia zzk_ e doar citire. Token-ul de la /api/v1/auth/login (cu PIN) oferă acces complet, limitat de rolul utilizatorului — deci și scriere, dacă rolul permite.

De ce eșuează webhook-ul meu? Cel mai des pentru că endpoint-ul nu răspunde cu 200 la timp. Răspunde imediat și procesează asincron.

Pot crea comenzi prin API? Da, cu POST /api/v1/orders, dar ai nevoie de token de utilizator cu rol care permite scrierea — nu de o cheie zzk_.

Pe scurt#

• Conectează AI-ul tău = OAuth, doar citire, fără cod — ideal pentru a-ți întreba datele din Claude/ChatGPT.
• Cheie API zzk_ = read-only, se vede o singură dată; token de utilizator (PIN) = acces complet după rol.
• Webhooks te notifică la evenimente; API REST /api/v1 și serverul MCP acoperă restul integrărilor din HoReCaOS.