☰ Мәзір · Мейрамханалар мен кафелер
Нұсқаулықтар

Мейрамханалар мен кафелер

Мекеменің POS жүйесі Loyaltyfy арқылы үш нәрсе жасай алады: QR-мәзірді синхрондау, үстелден тапсырыс қабылдау және кассада адалдық бағдарламасын жүргізу.

Әдетте бағалар мен қолда жоқ тауарлар туралы негізгі дерек көзі POS болады. Әр тағамға external_id өрісінде өз SKU-іңізді беріп, тағамдарға сол SKU арқылы жүгініңіз. Біздің id-лерді сақтаудың керегі жоқ.

  1. 1
    Бар мәзірді оқыңыз

    GET /v1/menu барлық тілдегі санаттарды, тағамдарды және модификаторларды қайтарады. Бір тілдегі қарапайым жолдарды алу үшін ?lang=en қосыңыз.

  2. 2
    Жетіспейтінін қосыңыз

    POST /v1/menu/items шақырып, category (санат id-і немесе өз санат кодыңыз; белгісіз код санатты жасайды), external_id, бір немесе бірнеше тілдегі name және price жіберіңіз. Сол external_id қайта жіберілсе, бар тағам қайтарылады.

  3. 3
    Өзгерістерді жіберіңіз

    Әр өзгерісте немесе бірнеше минут сайын бағалар мен қолжетімділікті POST /v1/menu/items/bulk арқылы жіберіңіз. Бір шақыруда 500 тағамға дейін. Белгісіз SKU-лер not_found ішінде қайтады.

curl
curl https://loyaltyfy.io/api/v1/menu/items/bulk \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "item": "1001", "price": 4800 },
      { "item": "2040", "available": false },
      { "item": "3017", "price": 9900, "old_price": 12000 }
    ]
  }'
Жауап · 200
{
  "object": "menu_bulk_result",
  "updated": ["1001", "2040"],
  "unchanged": [],
  "not_found": ["3017"],
  "failed": []
}

Стоп-лист: available: false тағамды "сатылып кетті" белгісімен көрсетіп, тапсырыс батырмасын алып тастайды. visible: false тағамды жасырады. Модификаторлардың өз қосқышы бар, сондықтан кофені өшірмей-ақ сұлы сүтін өшіре аласыз:

curl
curl -X PATCH https://loyaltyfy.io/api/v1/menu/option_values/MOD-OAT \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "available": false }'
Фотоларды, сипаттамалар мен аудармаларды әдетте мекеме Loyaltyfy мәзір редакторында өзгертеді. Бір-бірін қайта жазып тастамау үшін тек POS шынымен басқаратын деректерді (бағалар, қолжетімділік, мүмкін атаулар) синхрондаңыз.

Үстелден тапсырыс

Тапсырыс қосулы болса (басқару панеліндегі Мәзір → Тапсырыстар), үстелдегі QR-ды сканерлеген қонақтар себетін мекемеге жібере алады. Әр үстелдің үстел нөмірі бар өз сілтемесі болады:

curl
https://loyaltyfy.io/m/your-venue?table=12

Әр тапсырыстың бағасын ағымдағы мәзір бойынша өзіміз есептейміз, сондықтан POS сомаларға сене алады. Стоп-листтегі тағамға немесе модификаторға берілген тапсырыстар сізге жетпей тұрып қабылданбайды.

  1. 1
    Жаңа тапсырыстарды алыңыз

    order.created вебхугына жазылыңыз немесе 10-15 секунд сайын GET /v1/orders?status=new сұраңыз.

  2. 2
    Қабылдаңыз

    Тапсырысты POS ішінде жасап, содан кейін өз тапсырыс id-іңізді external_id ретінде беріп, POST /v1/orders/{id}/accept шақырыңыз. SKU-лерді сәйкестендіру үшін әр жолдың external_id мәнін пайдаланыңыз.

  3. 3
    Әрі қарай жылжытыңыз

    PATCH /v1/orders/{id} шақырып, preparing, ready, served, completed мәртебесін жіберіңіз. Ал асхана тапсырысты орындай алмаса, себебін көрсетіп POST /v1/orders/{id}/reject шақырыңыз.

curl
curl "https://loyaltyfy.io/api/v1/orders?status=new" \
  -H "Authorization: Bearer sk_test_..."
Тізімдегі бір тапсырыс
{
  "object": "order",
  "id": "0c69a81c-0fbc-4333-b26c-789566b9bea4",
  "number": 10,
  "day_number": 3,
  "type": "table",
  "status": "new",
  "table": "7",
  "location": null,
  "pickup_at": null,
  "pickup_lead_minutes": null,
  "guest": null,
  "note": "No onions, please",
  "currency": "MDL",
  "subtotal": 14000,
  "item_count": 2,
  "items": [
    {
      "item_id": "a48343bd-9f6e-424a-b003-fe790617f4d6",
      "external_id": "2040",
      "name": "Zeamă",
      "quantity": 2,
      "unit_price": 7000,
      "total": 14000,
      "options": []
    }
  ],
  "payment": { "method": "cash", "status": "unpaid", "provider": null, "reference": null, "paid_at": null },
  "external_id": null,
  "reject_reason": null,
  "guest_language": "en",
  "source": "qr_menu",
  "loyalty_transaction_id": null,
  "history": [],
  "livemode": true,
  "created_at": "2026-10-06T18:14:48.233+00:00",
  "accepted_at": null,
  "prepared_at": null,
  "picked_up_at": null,
  "completed_at": null,
  "updated_at": "2026-10-06T18:14:48.233+00:00"
}
curl
curl -X POST https://loyaltyfy.io/api/v1/orders/0c69a81c-0fbc-4333-b26c-789566b9bea4/accept \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "POS-ORDER-55821" }'

Мәртебелер тек алға жылжиды: new → accepted → preparing → ready → served → completed. new мәртебесі rejected бола алады, ал кез келген ашық тапсырыс cancelled бола алады. Қадамдарды өткізіп жіберуге болады (accepted мәртебесінен бірден completed мәртебесіне ауысу дұрыс). Артқа ауыстыру 409 invalid_status_transition алады. POS интеграциясы жоқ мекемелер дәл осы мәртебелерді Тапсырыстар экранында басқарады, сондықтан POS тек қабылдап, аяқтаса да жеткілікті.

Өзімен алу тапсырыстары

Өзімен алу қосулы болса (Мәзір → Тапсырыстар), қонақ нүкте мен уақытты таңдап, телефонын қалдырады. Мұндай тапсырыстарда type: pickup, location, pickup_at және guest болады. Мәртебелер: new → accepted → ready → completed, мұнда completed берілді дегенді білдіреді; served қолданылмайды. Беру қонақтың адалдық картасына телефон бойынша есептейді және transaction.completed жібереді. Қызметкерлер тапсырыстарды Telegram-нан да жүргізе алады, сондықтан мәртебе сізсіз өзгеруі мүмкін. Сүзгі: GET /v1/orders?type=pickup&location={id}.

Өзімен алу тапсырысы
{
  "object": "order",
  "id": "5b1f0c2e-8d4a-4c1b-9a7e-2f3d6e8a1c90",
  "number": 1184,
  "day_number": 12,
  "type": "pickup",
  "status": "accepted",
  "table": null,
  "location": { "id": "e3c1a9b2-4f5d-4e6a-8b7c-1d2e3f4a5b6c", "name": "Centru", "address": "Ștefan cel Mare 120" },
  "pickup_at": "2026-10-24T09:42:00.000+00:00",
  "pickup_lead_minutes": 15,
  "guest": { "name": "Ana", "phone": "+37369123456" },
  "note": "Oat milk, please",
  "currency": "MDL",
  "subtotal": 9000,
  "item_count": 2,
  "items": [
    {
      "item_id": "7a2b3c4d-5e6f-4a1b-8c9d-0e1f2a3b4c5d",
      "external_id": "1001",
      "name": "Cappuccino",
      "quantity": 2,
      "unit_price": 4500,
      "total": 9000,
      "options": [{ "id": "9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f", "external_id": "OAT", "name": "Oat milk", "price_delta": 500 }]
    }
  ],
  "payment": { "method": "cash", "status": "unpaid", "provider": "cash", "reference": null, "paid_at": null },
  "external_id": null,
  "reject_reason": null,
  "guest_language": "ro",
  "source": "qr_menu",
  "loyalty_transaction_id": null,
  "history": [{ "status": "accepted", "at": "2026-10-24T09:28:10.000+00:00", "by": "Ion", "via": "telegram" }],
  "livemode": true,
  "created_at": "2026-10-24T09:27:31.000+00:00",
  "accepted_at": "2026-10-24T09:28:10.000+00:00",
  "prepared_at": null,
  "picked_up_at": null,
  "completed_at": null,
  "updated_at": "2026-10-24T09:28:10.000+00:00"
}

Кафе кассасындағы адалдық бағдарламасы

Кез келген POS интеграциясы сияқты: карта сканерленгенде қонақты табыңыз, төлемнен кейін чекті жіберіңіз. Штамп-картасы бар кофеханаларда («әр 6-шы кофе тегін») штампты чек береді. Мекеме қонақтар қандай тауар алатынын көруі үшін line_items өз артикулдарыңызбен жіберіңіз.

Интеграция бойынша сұрақтар: api@loyaltyfy.io. Бір жұмыс күні ішінде жауап береміз.