Guest API για AI-ατζέντηδες

Δημόσιο API του cenaly.com, μέσω του οποίου οι AI βοηθοί και ατζέντηδες ενεργούν για λογαριασμό του επισκέπτη: διαβάζουν το μενού του εστιατορίου, ψάχνουν στον κατάλογο, συγκεντρώνουν καλάθι, υποβάλλουν παραγγελία και κάνουν κράτηση τραπεζιού. Για όλα αυτά δεν απαιτείται εξουσιοδότηση — είναι οι ίδιες λειτουργίες που είναι διαθέσιμες στον επισκέπτη στον ιστότοπο του μενού.

Διευθυνσιοδότηση εστιατορίου#

Το εστιατόριο διευθυνσιοδοτείται με κωδικό τοποθεσίας — είναι το τμήμα του URL του μενού σε κεφαλαία γράμματα. Αν το μενού ανοίγει στο cenaly.com/MYCAFE, ο κωδικός είναι MYCAFE. Ο ίδιος κωδικός είναι ενσωματωμένος στους κωδικούς QR των τραπεζιών.

Γρήγορη εκκίνηση (REST)#

# Τι μπορεί το API
curl https://api.cenaly.com/llm/v1

# Μενού εστιατορίου στα ρωσικά
curl "https://api.cenaly.com/llm/v1/locations/MYCAFE/menu?lang=ru"

# Υποβολή παραγγελίας για παραλαβή
curl -X POST https://api.cenaly.com/llm/v1/locations/MYCAFE/orders \
  -H 'Content-Type: application/json' \
  -d '{
    "items": [{"itemId": "abc123", "quantity": 2}],
    "orderType": "pickup",
    "customer": {"name": "Επισκέπτης", "phone": "+995555123456"},
    "language": "ru"
  }'
# → {"accepted": true, "orderId": "…", "total": 24, "statusUrl": "…"}

# Κατάσταση παραγγελίας (orderId — μυστικό διακριτικό πρόσβασης)
curl https://api.cenaly.com/llm/v1/locations/MYCAFE/orders/{orderId}

Πλήρης προδιαγραφή: OpenAPI 3.1 · διαδραστική τεκμηρίωση (στη γλώσσα της επωνυμίας; ?lang=en|ka|ru|tr|sq).

Τελικά σημεία#

Καλάθι: συγκέντρωση παραγγελίας βήμα προς βήμα#

Ο ατζέντης δεν χρειάζεται να μαντέψει το περιεχόμενο της παραγγελίας με μία κίνηση — μπορεί να τηρεί καλάθι στον διακομιστή, όπως κάνει ένας άνθρωπος στο καλάθι του ιστοτόπου:

1. POST /carts με τις πρώτες γραμμές → cartId
2. PATCH /carts/{cartId} — προσθήκη, αλλαγή ποσότητας, αφαίρεση (quantity: 0)
3. POST /orders με cartId — υποβολή

Οι τιμές στο καλάθι επανυπολογίζονται πάντα με βάση το ζωντανό μενού, οπότε δεν μπορεί να εμφανίσει παρωχημένο ποσό. Το καλάθι διατηρείται 7 ημέρες. Σε κάθε απάντηση υπάρχει checkoutUrl — ο σύνδεσμος μπορεί απλώς να δοθεί σε έναν άνθρωπο, ώστε να ολοκληρώσει την παραγγελία στο συνηθισμένο ταμείο.

Κατά τη δημιουργία παραγγελίας μπορεί να μεταβιβαστεί idempotencyKey (8–64 χαρακτήρες): η επανάληψη με το ίδιο κλειδί εντός 48 ωρών θα επιστρέψει την αρχική παραγγελία και δεν θα δημιουργήσει δεύτερη. Το ίδιο ισχύει και για τις κρατήσεις — η επανάληψη στο ίδιο παράθυρο θα επιστρέψει την αρχική κράτηση και δεν θα καταλάβει δεύτερο τραπέζι.

Σύνδεση μέσω MCP#

Διακομιστής: https://api.cenaly.com/llm/mcp — Model Context Protocol, streamable HTTP, stateless. Τα εργαλεία επισκέπτη λειτουργούν χωρίς εξουσιοδότηση· η σύνδεση μέσω OAuth προσθέτει σε αυτά τα εργαλεία του Λογαριασμού σας.

Διαμόρφωση για Claude Desktop / Claude Code και συμβατούς πελάτες:

{
  "mcpServers": {
    "meni-guest": {
      "type": "http",
      "url": "https://api.cenaly.com/llm/mcp"
    }
  }
}

Εργαλεία επισκέπτη (13, χωρίς εξουσιοδότηση):

Τυπικά σενάρια:

• Γρήγορη παραγγελία: get_menu → create_order → get_order_status (ο 4ψήφιος αριθμός εμφανίζεται μετά από λίγα δευτερόλεπτα).
• Παραγγελία σε διάλογο: search_products → update_cart (ένα είδος τη φορά, όπως στη συζήτηση) → get_cart → create_order, ή να δοθεί στον επισκέπτη το checkoutUrl και να ολοκληρώσει ο ίδιος την παραγγελία.
• Ερώτηση για το κατάστημα: get_store_info (διεύθυνση, ώρες, επαφές) ή search_policies_and_faqs (όροι παράδοσης, επιστροφή, κανόνες).
• Κράτηση τραπεζιού: check_table_availability (τραπέζια από την κάτοψη της αίθουσας, ελεύθερο/κατειλημμένο για την επιλεγμένη ώρα) → create_reservation με tableId → get_reservation_status (το εστιατόριο επιβεβαιώνει το αίτημα) → αν χρειαστεί cancel_reservation.

Πρόσβαση στα δεδομένα σας#

Εάν είστε ιδιοκτήτης καταστήματος ή υπάλληλος, στα ίδια 13 εργαλεία επισκεπτών προστίθενται 12 εργαλεία διαχείρισης του λογαριασμού σας — σε δύο ομάδες.

Δεδομένα λογαριασμού (6): resolve_domain, list_files, read_file, write_file, delete_file, write_signal. Ανοίγουν όχι μόνο το μενού και τις παραγγελίες, αλλά και το CRM, την αποθήκη, το προσωπικό, τις ρυθμίσεις του ταμείου και της οθόνης κουζίνας, τα έγγραφα και σχεδόν όλες τις υπόλοιπες ενότητες.

Ιστότοπος πελάτη καταστήματος (6): get_site_settings, update_site_settings, list_site_templates, apply_site_template, check_domain_availability, rename_site_domain.

Η σύνδεση γίνεται με το συνηθισμένο OAuth 2.1 κάτω από τον λογαριασμό σας στο cenaly.com: ο MCP client (Claude, ChatGPT, CLI) εγγράφεται μόνος του και ανοίγει το παράθυρο σύνδεσης. Δεν χρειάζεται να επικολλήσετε τίποτα με το χέρι.

• Μεταδεδομένα πόρου: https://api.cenaly.com/.well-known/oauth-protected-resource
• Μεταδεδομένα server εξουσιοδότησης: https://api.cenaly.com/.well-known/oauth-authorization-server
• Δυναμική εγγραφή client (RFC 7591): POST https://api.cenaly.com/llm/oauth/register

Όσο δεν υπάρχει token, το tools/list εμφανίζει μόνο τα εργαλεία επισκεπτών — τα εξουσιοδοτημένα απλώς δεν είναι ορατά.

Κανόνες και εγγυήσεις#

• Η παραγγελία επικυρώνεται με το ζωντανό μενού: ανύπαρκτο πιάτο, παραλλαγή ή πρόσθετο — σφάλμα 400 με λίστα προβλημάτων· τις τιμές και το σύνολο τα υπολογίζει ο server, ο agent δεν έχει τρόπο να «ορίσει» τιμή.
• Για παραλαβή και παράδοση είναι υποχρεωτικά το όνομα και το τηλέφωνο του επισκέπτη· για παράδοση — η διεύθυνση.
• orderId / reservationId — μυστικά tokens: με αυτά ελέγχεται η κατάσταση και ακυρώνεται η κράτηση. Μην τα δημοσιεύετε.
• Οι παραγγελίες και οι κρατήσεις φτάνουν στο εστιατόριο σε πραγματικό χρόνο — στο admin panel, στην οθόνη κουζίνας και στις ειδοποιήσεις, όπως οι συνηθισμένες παραγγελίες από τον ιστότοπο.
• Οι κρατήσεις του επισκέπτη έχουν κατάσταση pending, μέχρι το εστιατόριο να τις επιβεβαιώσει στο admin panel.
• Στη Ρωσία δεν μπορείτε να παραγγείλετε αλκοόλ μέσω του καναλιού agent. Η εξ αποστάσεως πώληση αλκοολούχων προϊόντων απαγορεύεται από τον νόμο (εδ. 14 παρ. 2 άρθ. 16 171-FZ), γι' αυτό σε καταστήματα με χώρα «Ρωσία» μια παραγγελία με είδος αλκοόλ δεν περνά την επικύρωση: στην απάντηση 400 έρχεται μια γραμμή με το όνομα αυτού του είδους και την εξήγηση ότι μπορείτε να το παραγγείλετε μόνο από σερβιτόρο στην αίθουσα. Η παραγγελία πρέπει να συγκροτηθεί ξανά χωρίς αλκοόλ.

Μηχανικά αναγνώσιμη ανακάλυψη#

• https://cenaly.com/llms.txt — σύντομος χάρτης του API για LLM;
• GET https://api.cenaly.com/llm/v1 — έγγραφο discovery: πλήρης λίστα endpoints, παραδείγματα παραγγελίας, κράτησης και διαχείρισης καλαθιού, σύνδεσμοι στα μεταδεδομένα OAuth.