Skip to main content

API Reference

The UCH Platform exposes a unified REST API running on Next.js Route Handlers. All traffic routes through the src/app/api/v1/[[...path]]/route.ts dispatcher.

Authentication​

All requests (except webhooks) must include a valid JWT token in the Authorization header.

Authorization: Bearer <your_jwt_token>

Additionally, multi-tenant context must be provided either in the payload or headers:

  • X-Tenant-ID
  • X-Outlet-ID

Endpoint Structure​

The generic endpoint is /api/v1/:action. The action maps to a registered handler key in src/server/handlers/registry.ts.

1. Orders API​

POST /api/v1/orders.create​

Creates a new order. Used primarily by the Waiter App and Aggregator Webhooks. Payload:

{
  "order_type": "DINE_IN",
  "table_id": "T-12",
  "waiter_id": "W-05",
  "items": [
    {
      "menu_item_id": "uuid-123",
      "quantity": 2,
      "modifiers": [...]
    }
  ]
}

POST /api/v1/orders.update_status​

Updates the lifecycle status of an order. Payload:

{
  "order_id": "uuid-456",
  "status": "FOOD_READY"
}

2. Aggregator Webhooks (UrbanPiper)​

POST /api/v1/aggregators.webhook.order_placed​

Receives a new order from Swiggy/Zomato via UrbanPiper. Automatically maps the external payload to the internal UCH orders schema and queues it for POS synchronization.

POST /api/v1/aggregators.webhook.order_status​

Receives real-time status updates (e.g., rider assigned, order cancelled by customer) from UrbanPiper.

Error Handling​

The API returns standardized error responses:

{
  "error": true,
  "code": "VALIDATION_FAILED",
  "message": "Missing required field: order_type",
  "details": [...]
}

Common HTTP Status Codes:

  • 200 OK: Success
  • 400 Bad Request: Validation failure
  • 401 Unauthorized: Invalid or missing JWT token
  • 403 Forbidden: Insufficient RBAC permissions
  • 501 Not Implemented: The handler key does not exist in the registry.