Guest API AI-აგენტებისთვის

meni.ge-ს საჯარო API, რომლის მეშვეობითაც AI-ასისტენტები და აგენტები სტუმრის სახელით მოქმედებენ: ეცნობიან რესტორნის მენიუს, ეძებენ კატალოგში, აგროვებენ კალათას, აფორმებენ შეკვეთას და ჯავშნიან მაგიდას. ამ ყველაფრისთვის ავტორიზაცია საჭირო არ არის — ეს იგივე ოპერაციებია, რაც სტუმრისთვის მენიუს საიტზეა ხელმისაწვდომი.

თუ შეხვალთ meni.ge-ს თქვენი ანგარიშით (OAuth), სტუმრის ინსტრუმენტებს ემატება კიდევ თორმეტი — უკვე თქვენი ობიექტის მონაცემებსა და პარამეტრებზე წვდომისთვის. იხილეთ განყოფილება „წვდომა საკუთარ მონაცემებზე“ ქვემოთ.

ასევე ხელმისაწვდომია ცალკე MCP-სერვერი ანგარიშის API-გასაღებებით სამართავად, მენიუს, ლოკაციებისა და შეკვეთების მზა ბრძანებებით: MCP Server-ის გზამკვლევი.

რესტორნის ადრესაცია

რესტორანი ადრესირდება ლოკაციის კოდით — ეს არის მენიუს URL-ის სეგმენტი ზედა რეგისტრში. თუ მენიუ იხსნება meni.ge/MYCAFE მისამართზე, კოდია — MYCAFE. იგივე კოდი ჩაშენებულია მაგიდების QR-კოდებში.

სწრაფი დაწყება (REST)

# რას აკეთებს API
curl https://api.meni.ge/llm/v1

# რესტორნის მენიუ რუსულ ენაზე
curl "https://api.meni.ge/llm/v1/locations/MYCAFE/menu?lang=ru"

# შეკვეთის გაფორმება წასაღებად
curl -X POST https://api.meni.ge/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.meni.ge/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 — ბმული შეგიძლიათ უბრალოდ გადასცეთ ადამიანს, რათა მან დაასრულოს შეკვეთა ჩვეულებრივ checkout-ში.

შეკვეთის შექმნისას შესაძლებელია idempotencyKey-ს გადაცემა (8–64 სიმბოლო): იგივე გასაღებით განმეორება 48 საათის განმავლობაში დააბრუნებს პირვანდელ შეკვეთას და არ შექმნის მეორეს. იგივე მუშაობს ჯავშნებზეც — განმეორება იმავე ფანჯარაში დააბრუნებს პირვანდელ ჯავშანს და არ დაიკავებს მეორე მაგიდას.

დაკავშირება MCP-ით

სერვერი: https://api.meni.ge/llm/mcp — Model Context Protocol, streamable HTTP, stateless. სტუმრის ინსტრუმენტები მუშაობს ავტორიზაციის გარეშე; OAuth-ით შესვლა მათ თქვენი ანგარიშის ინსტრუმენტებს ამატებს.

კონფიგურაცია Claude Desktop / Claude Code-სთვის და თავსებადი კლიენტებისთვის:

{
  "mcpServers": {
    "meni-guest": {
      "type": "http",
      "url": "https://api.meni.ge/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-ს, საწყობს, პერსონალს, POS-ისა და სამზარეულოს ეკრანის პარამეტრებს, დოკუმენტებს და თითქმის ყველა სხვა განყოფილებას.

ლოკაციის კლიენტის საიტი (6): get_site_settings, update_site_settings, list_site_templates, apply_site_template, check_domain_availability, rename_site_domain.

შესვლა — ჩვეულებრივი OAuth 2.1 თქვენი meni.ge ანგარიშით: MCP-კლიენტი (Claude, ChatGPT, CLI) რეგისტრირდება თავად და ხსნის ავტორიზაციის ფანჯარას. ხელით არაფრის შეყვანა არ არის საჭირო.

სად მუშაობს ეს. ავტორიზებული მხარე ხელმისაწვდომია ბრენდებზე, რომლებიც მუშაობენ AWS-ის ღრუბელში საერთო ანგარიშით (meni.ge, cenaly.com და სხვები) — ავტორიზაციის სერვერად გამოიყენება ჩვენი საერთო Cognito. რუსულ კონტურში (cenaly.ru) შესვლა სხვანაირადაა მოწყობილი და OAuth იქ ჯერ არ არის ჩართული: იქ მუშაობს მხოლოდ სტუმრის ინსტრუმენტები.

• რესურსის მეტამონაცემები: https://api.meni.ge/.well-known/oauth-protected-resource
• ავტორიზაციის სერვერის მეტამონაცემები: https://api.meni.ge/.well-known/oauth-authorization-server
• კლიენტის დინამიკური რეგისტრაცია (RFC 7591): POST https://api.meni.ge/llm/oauth/register

სანამ ტოკენი არ არის, tools/list აჩვენებს მხოლოდ სტუმრის ინსტრუმენტებს — ავტორიზებული ინსტრუმენტები უბრალოდ არ ჩანს.

უფლებები ზუსტად იგივეა, რაც გაქვთ ადმინ-პანელში: მფლობელი ხედავს მთელ ანგარიშს, თანამშრომელი — თავის ლოკაციას და თავისი როლის მიხედვით. ფაილების, რომლებსაც პროდუქტი მოვლენათა ჟურნალის სახით აწარმოებს (პროფილი, მენიუს სნეპშოტი, კერძების ბარათები), პირდაპირ გადაწერა შეუძლებელია — მათთვის განკუთვნილია უსაფრთხო write_signal.

წესები და გარანტიები

• შეკვეთის ვალიდაცია ხდება აქტიური მენიუს მიხედვით: არარსებული კერძი, ვარიანტი ან დამატება — შეცდომა 400 პრობლემების სიით; ფასებსა და ჯამურ თანხას ითვლის სერვერი, აგენტს არ აქვს ფასის „დანიშვნის“ საშუალება.
• თვითწაღებისა და მიტანისთვის სავალდებულოა სტუმრის სახელი და ტელეფონის ნომერი; მიტანისთვის — მისამართი.
• orderId / reservationId — საიდუმლო ტოკენებია: მათი საშუალებით მოწმდება სტატუსი და უქმდება ჯავშანი. ნუ გამოაქვეყნებთ მათ.
• შეკვეთები და ჯავშნები რესტორანში რეალურ დროში ხვდება — ადმინპანელში, სამზარეულოს ეკრანზე და შეტყობინებებში, როგორც საიტიდან მიღებული ჩვეულებრივი შეკვეთები.
• სტუმრის ჯავშნებს აქვს სტატუსი pending, სანამ რესტორანი მათ ადმინპანელში არ დაადასტურებს.
• რუსეთში სააგენტო არხით ალკოჰოლის შეკვეთა შეუძლებელია. ალკოჰოლური პროდუქციის დისტანციური გაყიდვა აკრძალულია კანონით (171-FZ-ის მე-16 მუხლის მე-2 პუნქტის მე-14 ქვეპუნქტი), ამიტომ ლოკაციებისთვის ქვეყნით „რუსეთი“ ალკოჰოლის შემცველი პოზიციის მქონე შეკვეთა ვალიდაციას ვერ გადის: 400 პასუხში ბრუნდება სტრიქონი ამ პოზიციის დასახელებით და განმარტებით, რომ მისი შეკვეთა შესაძლებელია მხოლოდ მიმტანთან დარბაზში. შეკვეთა ხელახლა უნდა აეწყოს ალკოჰოლის გარეშე.

მანქანურად წაკითხვადი აღმოჩენა

• https://meni.ge/llms.txt — API-ის მოკლე რუკა LLM-ისთვის;
• GET https://api.meni.ge/llm/v1 — discovery-დოკუმენტი: ენდპოინტების სრული სია, შეკვეთის, ჯავშნისა და კალათასთან მუშაობის მაგალითები, ბმულები OAuth-მეტამონაცემებზე.