New booking
OP

Integration / API

التكامل

Provider-neutral v1 contract. AI USCC consumes this application as a booking provider.

API version
v1 · 6 endpoints live
Client authentication
Demo mode (open)

Send x-api-key or Authorization: Bearer. OAuth2 client credentials ready to slot in.

Idempotency
Enforced on create

Same key + same payload returns the same booking (200). Same key + different payload returns 409.

Endpoints

Request
{
  "customer": {
    "customerRef": "CUST-1001",
    "name": "Ahmed Al Example",
    "phone": "+9715XXXXXXXX",
    "email": "customer@example.com"
  },
  "serviceId": "majlis_hall",
  "resourceId": "MJ-001",
  "date": "2026-10-09",
  "startTime": "18:00",
  "endTime": "22:00",
  "partySize": 60,
  "attributes": {
    "eventType": "wedding"
  },
  "externalRequestId": "AIUSCC-REQ-123",
  "idempotencyKey": "AIUSCC-BOOKING-123"
}
Response · data
{
  "success": true,
  "data": {
    "bookingId": "3f0c…",
    "bookingReference": "MDB-20261009-1011",
    "status": "CONFIRMED"
  }
}

Error envelope

{
  "success": false,
  "error_code": "SLOT_CONFLICT",
  "message": "This Majlis is already booked for an overlapping time.",
  "details": {
    "conflicts": [
      {
        "bookingReference": "MDB-DEMO-0001",
        "startTime": "18:00",
        "endTime": "22:00"
      }
    ]
  }
}

Codes: VALIDATION_ERROR 400 · UNAUTHORIZED 401 · NOT_FOUND / CUSTOMER_NOT_FOUND / MAJLIS_NOT_FOUND 404 · SLOT_CONFLICT / IDEMPOTENCY_CONFLICT 409 · NOT_ELIGIBLE / CAPACITY_EXCEEDED / MAJLIS_INACTIVE / INVALID_STATUS_TRANSITION 422.

Trust boundary

  • Customer identity and contact details are taken from the customer master record, not from the request payload.
  • Eligibility is evaluated server-side by a replaceable eligibility service.
  • Client auth is isolated in one integration layer, ready for OAuth2 client credentials.
  • Send x-client-id: ai-uscc to tag bookings with source AI_USCC.
  • Secrets are never displayed in this console.