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": [] } ] }'