واجهة REST

{
  "status": 200,
  "message": "ok",
  "data": { }
}

Authorization: Bearer wjh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# or
x-api-key: wjh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
  "status": 429,
  "message": "Too many requests",
  "data": null,
  "code": "RATE_LIMITED"
}

GET /api/v1/orders?pageSize=20
Authorization: Bearer wjh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

{
  "status": 200,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": "ord_01JABC",
        "number": "10042",
        "status": "pending",
        "customerName": "Ahmed Hassan",
        "customerPhone": "+201012345678",
        "payment": { "method": "cod", "codAmount": 495, "currency": "EGP" },
        "totals": { "subtotal": 450, "shipping": 45, "total": 495, "currency": "EGP" },
        "createdAt": "2026-10-08T17:12:04.000Z"
      }
    ],
    "nextPageToken": null
  }
}

POST /api/v1/orders
Authorization: Bearer wjh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "customerName": "Ahmed Hassan",
  "customerPhone": "+201012345678",
  "shippingAddress": {
    "city": "Cairo",
    "area": "Nasr City",
    "line1": "12 Nile St",
    "phone": "+201012345678"
  },
  "lineItems": [
    {
      "productId": "prd_01J",
      "variantId": "var_01J",
      "sku": "TEE-BLK-M",
      "title": "Cotton tee",
      "qty": 2,
      "price": 225
    }
  ],
  "payment": { "method": "cod", "codAmount": 495, "currency": "EGP" }
}

{
  "status": 201,
  "message": "created",
  "data": {
    "id": "ord_01JABC",
    "number": "10042",
    "status": "waiting_for_pickup",
    "channel": "manual",
    "customerName": "Ahmed Hassan",
    "customerPhone": "+201012345678",
    "lineItems": [
      {
        "variantId": "var_01J",
        "productId": "prd_01J",
        "sku": "TEE-BLK-M",
        "title": "Cotton tee",
        "qty": 2,
        "price": 225,
        "unitCost": 80,
        "costSource": "variant"
      }
    ],
    "payment": { "method": "cod", "codAmount": 495, "currency": "EGP" },
    "totals": { "subtotal": 450, "shipping": 45, "total": 495, "currency": "EGP" },
    "shipmentIds": ["shp_01J"],
    "shipping": {
      "shipmentId": "shp_01J",
      "carrier": "mega",
      "status": "created",
      "trackingNumber": "WJH123456789",
      "waybill": "WJH123456789",
      "megaShipmentId": "mega_987654",
      "qrCode": "MEGA-QR-PAYLOAD",
      "labelUrl": "https://labels.example.com/WJH123456789.pdf",
      "awbPrinted": false
    },
    "createdAt": "2026-10-08T17:12:04.000Z"
  }
}

DELETE /api/v1/orders/ord_01JABC
Authorization: Bearer wjh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
  "status": 200,
  "message": "cancelled",
  "data": {
    "id": "ord_01JABC",
    "status": "cancelled"
  }
}

GET /api/v1/products?pageSize=20
Authorization: Bearer wjh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

{
  "status": 200,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": "prd_01J",
        "title": "Cotton tee",
        "status": "active",
        "sku": "TEE-BLK",
        "slug": "cotton-tee",
        "brand": "Demo",
        "categoryId": "apparel",
        "subcategoryId": "tshirts",
        "description": "Soft cotton tee",
        "descriptionHtml": "<p>Soft cotton tee</p>",
        "tags": ["basics"],
        "collectionIds": ["col_01J"],
        "seo": { "title": "Cotton tee", "description": "Soft cotton tee" },
        "media": ["media/tee.jpg"],
        "mediaUrls": ["https://cdn.example.com/media/tee.jpg"],
        "trackInventory": true,
        "inventoryPolicy": "deny",
        "storeQuantity": 24,
        "warehouseQuantity": 10,
        "importSource": "vondera",
        "importExternalId": "43254206",
        "variants": [
          {
            "id": "var_01J",
            "sku": "TEE-BLK-M",
            "title": "M",
            "price": 225,
            "compareAtPrice": 275,
            "cost": 80,
            "barcode": "6220000000000",
            "attributes": { "Color": "Black", "Size": "M" },
            "inventoryQuantity": 12,
            "weightGrams": 180
          }
        ]
      }
    ],
    "nextPageToken": null,
    "warehouseEnrolled": true
  }
}

POST /api/v1/products
Authorization: Bearer wjh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "title": "Cotton tee",
  "sku": "TEE-BLK",
  "status": "active",
  "description": "Soft cotton tee",
  "variants": [
    {
      "sku": "TEE-BLK-M",
      "price": 225,
      "compareAtPrice": 275,
      "cost": 80,
      "attributes": { "Color": "Black", "Size": "M" },
      "inventoryQuantity": 12
    }
  ]
}

{
  "status": 201,
  "message": "created",
  "data": {
    "id": "prd_01J",
    "title": "Cotton tee",
    "sku": "TEE-BLK",
    "status": "active",
    "storeQuantity": 12,
    "variants": [
      {
        "id": "var_01J",
        "sku": "TEE-BLK-M",
        "price": 225,
        "compareAtPrice": 275,
        "cost": 80,
        "attributes": { "Color": "Black", "Size": "M" },
        "inventoryQuantity": 12
      }
    ]
  }
}

GET /api/v1/collections
Authorization: Bearer wjh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

{
  "status": 200,
  "message": "ok",
  "data": {
    "items": [
      { "id": "col_01J", "title": "Summer", "slug": "summer", "status": "active" }
    ],
    "nextPageToken": null
  }
}

POST /api/v1/collections
Authorization: Bearer wjh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "title": "Summer",
  "slug": "summer",
  "status": "active",
  "productIds": ["prd_01J"]
}

{
  "status": 201,
  "message": "created",
  "data": {
    "id": "col_01J",
    "title": "Summer",
    "slug": "summer",
    "status": "active",
    "productIds": ["prd_01J"]
  }
}

GET /api/v1/expenses?from=2026-10-01&to=2026-10-31
Authorization: Bearer wjh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

{
  "status": 200,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": "exp_01J",
        "categoryName": "Rent",
        "amount": 5000,
        "currency": "EGP",
        "expenseDate": "2026-10-01"
      }
    ]
  }
}

POST /api/v1/expenses
Authorization: Bearer wjh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "categoryId": "cat_rent",
  "amount": 5000,
  "currency": "EGP",
  "expenseDate": "2026-10-01",
  "vendor": "Landlord Co",
  "notes": "October rent",
  "recurringRule": "monthly"
}

{
  "status": 201,
  "message": "created",
  "data": {
    "id": "exp_01J",
    "categoryId": "cat_rent",
    "categoryName": "Rent",
    "amount": 5000,
    "currency": "EGP",
    "expenseDate": "2026-10-01",
    "vendor": "Landlord Co",
    "recurringRule": "monthly"
  }
}

GET /api/v1/analytics?from=2026-10-01&to=2026-10-17
Authorization: Bearer wjh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

{
  "status": 200,
  "message": "ok",
  "data": {
    "from": "2026-10-01",
    "to": "2026-10-17",
    "summary": {
      "orders": 128,
      "revenue": 64250,
      "currency": "EGP"
    },
    "series": [
      { "day": "2026-10-01", "orders": 8, "revenue": 4200 }
    ]
  }
}

GET /api/v1/discounts
Authorization: Bearer wjh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

{
  "status": 200,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": "dsc_01J",
        "code": "SUMMER10",
        "type": "percent",
        "value": 10,
        "active": true
      }
    ]
  }
}

GET /api/v1/customers?pageSize=20
Authorization: Bearer wjh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

{
  "status": 200,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": "cus_01JDEF",
        "name": "Ahmed Hassan",
        "phone": "+201012345678",
        "email": "ahmed@example.com"
      }
    ],
    "nextPageToken": null
  }
}

GET /api/v1/reviews?status=approved&limit=20
Authorization: Bearer wjh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

{
  "status": 200,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": "rev_01J",
        "productId": "prd_01J",
        "rating": 5,
        "body": "Great quality",
        "status": "approved",
        "createdAt": "2026-10-08T10:00:00.000Z"
      }
    ]
  }
}

GET /api/v1/shipping-fees?govId=cairo&limit=50
Authorization: Bearer wjh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

{
  "status": 200,
  "message": "ok",
  "data": {
    "currency": "EGP",
    "megaDefaultsSource": "work_places",
    "items": [
      {
        "sectorId": "sec_nasr_city",
        "name": "Nasr City",
        "govId": "cairo",
        "govName": "Cairo",
        "fee": 45,
        "currency": "EGP",
        "isOverride": false,
        "source": "wijha_default",
        "estimatedArrivalHours": 48
      }
    ]
  }
}

GET /api/v1/shipping-fees/resolve?sectorId=sec_nasr_city
Authorization: Bearer wjh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

{
  "status": 200,
  "message": "ok",
  "data": {
    "sectorId": "sec_nasr_city",
    "fee": 45,
    "currency": "EGP",
    "isOverride": false,
    "source": "wijha_default",
    "estimatedArrivalHours": 48
  }
}

GET /api/v1/balance
Authorization: Bearer wjh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

# Optional: force a fresh sync from the carrier
# GET /api/v1/balance?refresh=1

{
  "status": 200,
  "message": "ok",
  "data": {
    "available": 1250.5,
    "pending": 320,
    "settled": 0,
    "currency": "EGP",
    "lowThreshold": 200,
    "isLow": false,
    "source": "cached",
    "syncedAt": "2026-10-08T12:00:00.000Z"
  }
}

GET /api/v1/store
Authorization: Bearer wjh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

{
  "status": 200,
  "message": "ok",
  "data": {
    "id": "str_01JSTORE",
    "name": "Demo Store",
    "slug": "demo-store",
    "status": "active",
    "country": "EG",
    "timezone": "Africa/Cairo",
    "currency": "EGP",
    "contact": {
      "supportEmail": "hello@example.com",
      "supportPhone": "+201012345678",
      "tagline": "Quality basics",
      "logoUrl": "https://cdn.example.com/logo.png"
    },
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-10-08T12:00:00.000Z"
  }
}

GET /api/v1/webhooks/endpoints
Authorization: Bearer wjh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

{
  "status": 200,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": "wh_01J",
        "nickname": "ERP sync",
        "url": "https://example.com/wijha/hooks",
        "events": ["OrderCreated", "OrderStatusChanged"],
        "active": true,
        "hasSecret": true
      }
    ],
    "nextPageToken": null
  }
}

POST /api/v1/webhooks/endpoints
Authorization: Bearer wjh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "url": "https://example.com/wijha/hooks",
  "method": "POST",
  "nickname": "ERP sync",
  "events": ["OrderCreated", "OrderStatusChanged"],
  "secret": "super-secret-min-8",
  "active": true
}

{
  "status": 201,
  "message": "created",
  "data": {
    "id": "wh_01J",
    "url": "https://example.com/wijha/hooks",
    "method": "POST",
    "nickname": "ERP sync",
    "events": ["OrderCreated", "OrderStatusChanged"],
    "hasSecret": true,
    "secret": "super-secret-min-8",
    "active": true,
    "status": "active"
  }
}