For: Full Stack · Backend API

API reference

Every endpoint of the Sufra API, with access rules, request bodies and responses.

All endpoints live under /api, take and return JSON, and are in src/app/api. Amounts are integers in the currency's smallest unit (OMR: baisa). Errors always look like:

{ "error": { "code": "cart_invalid", "message": "Choose the required options for every dish." } }
Status When
400 body is not JSON
401 unauthorized: dashboard endpoint without a valid session
403 forbidden: staff calling an owner-only endpoint
404 not_found
409 conflicts: closed, not_accepting, bad_transition, slug_taken, last_owner, ...
422 validation and other input problems
429 rate_limited
502 / 503 payment provider or AI unavailable

Dashboard endpoints use the sufra_session cookie set by POST /api/auth/login (httpOnly, 12 hours).

Public

GET /api/menu

The menu and what a client needs to build an order.

{
  "restaurant": { "nameAr": "سُفرة", "nameEn": "Sufra", "currency": "OMR", "currencyDecimals": 3, "openNow": true, "acceptingOrders": true },
  "pricing": { "taxPercent": 5, "deliveryFee": 500, "minOrder": 2000 },
  "orderTypes": { "PICKUP": true, "DELIVERY": true, "DINE_IN": true },
  "payments": { "CASH": true, "CARD": false },
  "categories": [
    { "id": "…", "slug": "wraps-burgers", "nameAr": "…", "nameEn": "Wraps & burgers",
      "items": [ { "id": "…", "slug": "chicken-shawarma", "nameEn": "Chicken shawarma", "price": 1300, "available": true,
        "tags": ["popular"], "image": "/images/menu/chicken-shawarma.webp", "prepMinutes": 8, "calories": 540,
        "optionGroups": [ { "id": "…", "nameEn": "Size", "required": true, "maxSelect": 1,
          "options": [ { "id": "…", "nameEn": "Double", "priceDelta": 600 } ] } ] } ] }
  ]
}

POST /api/orders

Places an order. Limited to 8 per minute per visitor.

{
  "type": "DELIVERY",
  "customerName": "Salim Al Harthy",
  "phone": "+968 9123 4567",
  "address": "Qurum, Way 2601, Building 12",
  "tableNo": "",
  "notes": "Please ring the bell",
  "paymentMethod": "CASH",
  "locale": "en",
  "items": [
    { "itemId": "…", "quantity": 2, "optionIds": ["…", "…"], "note": "no pickles" }
  ]
}
Field Rules
type PICKUP, DELIVERY (needs address, 5+ characters) or DINE_IN (needs tableNo); must be enabled in settings
phone 8–15 digits, optional +, spaces and dashes
paymentMethod CASH or CARD; must be enabled
items 1–60 lines, quantity 1–50, options must belong to the dish, required groups answered, no more than maxSelect per group

Responses: 201 {"code": "SF-7KQ2-M9XD"} for cash; 201 {"code": "…", "payUrl": "https://…thawani.om/pay/…"} for card (send the customer to payUrl). Errors: closed, not_accepting, type_disabled, payment_disabled, invalid_phone, address_required, table_required, cart_invalid, below_minimum, payment_unavailable.

The server ignores any price sent by the client: it prices every line from the database (src/lib/pricing.ts), adds the delivery fee for delivery, and tax on subtotal plus delivery fee.

GET /api/orders/{code}

Tracking for the customer (120 requests per minute per visitor).

{ "order": { "code": "SF-7KQ2-M9XD", "status": "PREPARING", "type": "DELIVERY", "customerName": "Salim Al Harthy",
  "phone": "+••• •••• •567", "subtotal": 5600, "deliveryFee": 500, "tax": 305, "total": 6405,
  "paymentMethod": "CASH", "paymentStatus": "UNPAID", "createdAt": "…",
  "items": [ { "nameEn": "Chicken shawarma", "quantity": 2, "unitPrice": 2200, "lineTotal": 4400,
    "options": [ { "group": { "en": "Size" }, "name": { "en": "Double" }, "priceDelta": 600 } ], "note": "no pickles" } ],
  "events": [ { "status": "NEW", "at": "…" }, { "status": "PREPARING", "at": "…" } ] } }

Statuses: NEW, PREPARING, READY, OUT_FOR_DELIVERY, COMPLETED, CANCELLED. Payment: UNPAID, PAID, FAILED.

POST /api/reservations

{ "name": "Salim", "phone": "92223333", "people": 4, "date": "2026-10-20", "time": "20:00", "notes": "birthday" }

201 {"code": "RS-…"}. People 1–30, date within the next 60 days. 5 per minute per visitor.

GET /api/payments/thawani/return?order={code}&locale={ar|en}

Where Thawani sends the customer back. Checks the session with Thawani, marks the order paid or cancelled, and redirects to the tracking page. See Payments.

Sign-in

Endpoint Body Response
POST /api/auth/login {"email", "password"} 200 {"user": {"name", "email", "role"}} and the session cookie; 401 invalid_credentials. 10 attempts per minute per visitor, 8 per email per 15 minutes
POST /api/auth/logout none 200 {"ok": true}, cookie removed

Dashboard (session required)

Endpoint Who Description
GET /api/dashboard/stats staff today (orders, sales, average, cancelled, by type), active orders, pending reservations, last 7 days, best sellers
GET /api/dashboard/orders?view=active|today|all&q= staff orders with full details; q searches code, phone and name
GET /api/dashboard/orders/{id} staff one order
PATCH /api/dashboard/orders/{id} staff {"status": "READY", "note": "…"} moves along the flow (409 bad_transition otherwise); {"paymentStatus": "PAID"} records cash (card orders refused)
GET /api/dashboard/categories staff categories with dish counts
POST /api/dashboard/categories owner {"slug", "nameAr", "nameEn", "sort", "active"}
PATCH /api/dashboard/categories/{id} owner any of the fields above
DELETE /api/dashboard/categories/{id} owner only when empty (409 not_empty)
GET /api/dashboard/items?category={id} staff all dishes, hidden categories included
POST /api/dashboard/items owner a dish (fields below)
GET /api/dashboard/items/{id} staff one dish
PATCH /api/dashboard/items/{id} owner; staff for {"available"} only any dish fields; optionGroups replaces all groups
DELETE /api/dashboard/items/{id} owner past orders keep their copy
POST /api/dashboard/upload owner multipart file (JPEG/PNG/WebP, 4 MB) → {"url": "/uploads/…"}
GET /api/dashboard/settings staff settings plus integrations: {thawani, thawaniMode, ai}
PATCH /api/dashboard/settings owner; staff for {"acceptingOrders"} only any settings field, hours as [{"day": 0–6, "open": "HH:MM", "close": "HH:MM", "closed": false}]
GET /api/dashboard/reservations?view=upcoming|all staff reservations
PATCH /api/dashboard/reservations/{id} staff {"status": "CONFIRMED"} (PENDING, CONFIRMED, DECLINED, SEATED, CANCELLED)
POST /api/dashboard/ai/describe owner {"nameAr", "nameEn", "notes"} → {"suggestion": {"ar", "en"}}; 503 ai_disabled when not set up
GET /api/dashboard/staff owner accounts
POST /api/dashboard/staff owner {"name", "email", "password" (10+), "role": "OWNER"|"STAFF"}
PATCH /api/dashboard/staff/{id} owner name, role, active, password; 409 last_owner protects the last owner

Dish fields for POST/PATCH /api/dashboard/items:

{
  "slug": "chicken-shawarma", "categoryId": "…", "nameAr": "شاورما دجاج", "nameEn": "Chicken shawarma",
  "descAr": "…", "descEn": "…", "price": 1300, "image": "/uploads/…webp", "calories": 540, "prepMinutes": 8,
  "tags": ["popular"], "available": true, "featured": false, "sort": 12,
  "optionGroups": [
    { "nameAr": "الحجم", "nameEn": "Size", "required": true, "maxSelect": 1,
      "options": [ { "nameAr": "عادي", "nameEn": "Regular", "priceDelta": 0 }, { "nameAr": "دبل", "nameEn": "Double", "priceDelta": 600 } ] }
  ]
}

Tags: spicy, vegetarian, new, popular, gluten-free.

Example: a cash order with curl

curl -s http://localhost:3301/api/menu > menu.json
curl -s -X POST http://localhost:3301/api/orders -H "Content-Type: application/json" -d '{
  "type": "PICKUP", "customerName": "Test", "phone": "91234567", "paymentMethod": "CASH", "locale": "en",
  "items": [ { "itemId": "<id of a dish from menu.json>", "quantity": 3, "optionIds": [] } ] }'