Integrare · Dezvoltatori

API REST și webhook-uri HoReCaOS

Pentru integrări program-la-program: un site de comenzi, un dashboard propriu, un ERP al grupului. HoReCaOS are API REST versionat, chei API cu scope-uri și webhook-uri care îți trimit evenimentele.

Ce face concret

• API REST sub /api/v1, de exemplu GET /api/v1/menu, GET /api/v1/orders, POST /api/v1/orders, plus schema completă în /api/v1/openapi.json.
• Chei API (zzk_…) doar pentru citire, afișate o singură dată la generare.
• Token de utilizator (login cu PIN) pentru scriere, limitat de rolul utilizatorului.
• Webhook-uri: HoReCaOS trimite o cerere HTTP la evenimente (de exemplu comandă nouă), cu reîncercare dacă serverul tău nu răspunde.
• Idempotency-Key pe cereri, ca o comandă retrimisă să nu se dubleze.
• OAuth pentru aplicații conectate, același mecanism folosit de conectorul MCP pentru Claude.

Cum o pornești

1. În Tools → API apeși Generează cheie API și o păstrezi într-un loc sigur.
2. Citești documentația din aplicație (endpoint-uri, erori, exemple) și schema OpenAPI.
3. Pentru notificări, adaugi un Webhook nou cu URL-ul serverului tău și alegi evenimentele.

Limite și ce să știi

• Modulul e în beta: lista de evenimente și de endpoint-uri se extinde încă.
• Cheile API sunt doar de citire; scrierea cere token de utilizator cu rol potrivit.
• Endpoint-ul tău de webhook trebuie să răspundă repede cu 200; procesarea grea o faci după.

Pas cu pas: ghidul API & Webhooks.

Întrebări frecvente

Pot crea comenzi prin API?

Da, cu POST /api/v1/orders, folosind un token de utilizator al cărui rol permite scrierea. Cheile zzk_ sunt doar de citire.

Există documentație OpenAPI?

Da. Schema completă e la /api/v1/openapi.json, iar documentația cu exemple e în aplicație, la Tools → API.

Ce se întâmplă dacă serverul meu pică la un webhook?

Livrarea eșuează și HoReCaOS o reîncearcă. Răspunde rapid cu 200 și procesează asincron.