Capi Agent API — واجهة برمجة المتجر المخصص

curl -X GET https://capiagent.com/api/ingest/v1/ping \
  -H "Authorization: Bearer capi_live_xxxxxxxxxxxxxxxxxxxxxxxx"

curl -X GET https://capiagent.com/api/ingest/v1/ping \
  -H "Authorization: Bearer capi_live_xxxxxxxxxxxxxxxxxxxxxxxx"

{
  "ok": true,
  "mode": "live",
  "store": {
    "name": "Lumi Store",
    "currency": "SAR"
  }
}

curl -X POST https://capiagent.com/api/ingest/v1/products \
  -H "Authorization: Bearer capi_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "products": [
    {
      "id": "SKU-1001",
      "name": "Cotton shirt",
      "price": 199.99,
      "salePrice": 149.99,
      "costPrice": 80,
      "stock": 12,
      "url": "https://mystore.com/p/1001",
      "images": [
        "https://mystore.com/img/1001.jpg"
      ],
      "categories": [
        "Clothing"
      ],
      "variants": [
        {
          "id": "SKU-1001-M",
          "name": "M",
          "price": 149.99,
          "costPrice": 80,
          "stock": 5
        }
      ]
    }
  ]
}'

{
  "ok": true,
  "succeeded": 1,
  "failed": 0,
  "results": [
    {
      "id": "SKU-1001",
      "ok": true
    }
  ]
}

curl -X PATCH https://capiagent.com/api/ingest/v1/products/SKU-1001 \
  -H "Authorization: Bearer capi_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "price": 199.99,
  "salePrice": 149.99,
  "costPrice": 80,
  "stock": 3
}'

{
  "ok": true,
  "succeeded": 1,
  "failed": 0,
  "results": [
    {
      "id": "SKU-1001",
      "ok": true
    }
  ]
}

curl -X DELETE https://capiagent.com/api/ingest/v1/products/SKU-1001 \
  -H "Authorization: Bearer capi_live_xxxxxxxxxxxxxxxxxxxxxxxx"

{
  "ok": true,
  "succeeded": 1,
  "failed": 0,
  "results": [
    {
      "id": "SKU-1001",
      "ok": true
    }
  ]
}

curl -X POST https://capiagent.com/api/ingest/v1/orders \
  -H "Authorization: Bearer capi_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "orders": [
    {
      "id": "10045",
      "status": "processing",
      "total": 349.98,
      "currency": "SAR",
      "placedAt": "2026-10-06T09:00:00Z",
      "customer": {
        "name": "Sara",
        "phone": "966501234567",
        "email": "sara@example.com"
      },
      "items": [
        {
          "productId": "SKU-1001",
          "name": "Cotton shirt",
          "quantity": 2,
          "price": 174.99
        }
      ],
      "couponCode": "CAPI-7K3M9",
      "paymentMethod": "cod",
      "paymentUrl": "https://mystore.com/pay/10045"
    }
  ]
}'

{
  "ok": true,
  "succeeded": 1,
  "failed": 0,
  "results": [
    {
      "id": "10045",
      "ok": true
    }
  ]
}

curl -X PATCH https://capiagent.com/api/ingest/v1/orders/10045 \
  -H "Authorization: Bearer capi_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "shipped",
  "shipment": {
    "carrier": "SMSA",
    "trackingNumber": "290012345678",
    "trackingUrl": "https://track.example.com/290012345678"
  }
}'

{
  "ok": true,
  "succeeded": 1,
  "failed": 0,
  "results": [
    {
      "id": "10045",
      "ok": true
    }
  ]
}

curl -X POST https://capiagent.com/api/ingest/v1/carts \
  -H "Authorization: Bearer capi_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "carts": [
    {
      "id": "cart-7f3a",
      "currency": "SAR",
      "total": 199.99,
      "items": [
        {
          "productId": "SKU-1001",
          "name": "Cotton shirt",
          "quantity": 1,
          "price": 199.99
        }
      ],
      "customer": {
        "name": "Sara",
        "phone": "966501234567"
      },
      "checkoutUrl": "https://mystore.com/checkout/cart-7f3a",
      "updatedAt": "2026-10-06T08:40:00Z"
    }
  ]
}'

{
  "ok": true,
  "succeeded": 1,
  "failed": 0,
  "results": [
    {
      "id": "cart-7f3a",
      "ok": true
    }
  ]
}

curl -X POST https://capiagent.com/api/ingest/v1/customers \
  -H "Authorization: Bearer capi_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "customers": [
    {
      "id": "U-501",
      "name": "Sara",
      "phone": "966501234567",
      "email": "sara@example.com",
      "city": "Riyadh",
      "acceptsMarketing": true
    },
    {
      "id": "U-502",
      "email": "omar@example.com",
      "acceptsMarketing": false
    }
  ]
}'

{
  "ok": true,
  "succeeded": 2,
  "failed": 0,
  "results": [
    {
      "id": "U-501",
      "ok": true
    },
    {
      "id": "U-502",
      "ok": true
    }
  ]
}

curl -X GET https://capiagent.com/api/ingest/v1/coupons/CAPI-7K3M9 \
  -H "Authorization: Bearer capi_live_xxxxxxxxxxxxxxxxxxxxxxxx"

{
  "ok": true,
  "valid": true,
  "coupon": {
    "code": "CAPI-7K3M9",
    "discountType": "percent",
    "percent": 10,
    "expiresAt": "2026-10-12T18:00:00.000Z",
    "usageLimit": 1
  }
}

curl -X POST https://capiagent.com/api/ingest/v1/coupons/CAPI-7K3M9/redeem \
  -H "Authorization: Bearer capi_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "orderId": "10045"
}'

{
  "ok": true,
  "redeemed": true,
  "coupon": {
    "code": "CAPI-7K3M9",
    "discountType": "percent",
    "percent": 10,
    "expiresAt": "2026-10-12T18:00:00.000Z",
    "usageLimit": 1,
    "redeemedAt": "2026-10-06T10:00:00.000Z"
  }
}

curl -X DELETE https://capiagent.com/api/ingest/v1/coupons/CAPI-7K3M9/redeem \
  -H "Authorization: Bearer capi_live_xxxxxxxxxxxxxxxxxxxxxxxx"

{
  "ok": true,
  "released": true
}

POST https://your-store.com/capi/webhook
Content-Type: application/json
X-Capi-Event: order.cod_cancelled
X-Capi-Api-Version: v1
X-Capi-Event-Id: evt_cm9x2k1a80001
X-Capi-Delivery-Attempt: 1
X-Capi-Signature: t=1759740720,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

{
  "id": "evt_cm9x2k1a80001",
  "event": "order.cod_cancelled",
  "apiVersion": "v1",
  "createdAt": "2026-10-06T09:12:00.000Z",
  "data": {
    "orderId": "10045",
    "outcome": "cancelled",
    "cancelRequested": true,
    "note": "Capi Agent: the customer cancelled this cash-on-delivery order on WhatsApp.",
    "channel": "whatsapp",
    "respondedAt": "2026-10-06T09:12:00.000Z"
  }
}

import crypto from "node:crypto";

// Use the RAW request body — not a re-serialised object.
// The header may carry several v1= (while a secret is being rotated) and keys
// you do not know yet: it is valid when ANY v1 matches. Ignore the rest.
export function verifyCapiSignature(rawBody, header, secret) {
  const parts = header.split(",").map((p) => p.trim().split("="));
  const t = Number(parts.find(([key]) => key === "t")?.[1]);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // older than 5 minutes
  const expected = Buffer.from(crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex"));
  return parts.some(
    ([key, value]) => key === "v1" && Buffer.byteLength(value ?? "") === expected.length && crypto.timingSafeEqual(expected, Buffer.from(value)),
  );
}

app.post("/capi/webhook", express.raw({ type: "application/json" }), async (req, res) => {
  const raw = req.body.toString("utf8");
  if (!verifyCapiSignature(raw, req.get("X-Capi-Signature") ?? "", process.env.CAPI_WEBHOOK_SECRET)) {
    return res.status(401).end();
  }
  const event = JSON.parse(raw);
  if (await alreadyHandled(event.id)) return res.status(200).end(); // retries keep the same id

  switch (event.event) {
    case "coupon.create": {
      const coupon = await createCoupon(event.data);         // answer within 10 seconds
      await markHandled(event.id);
      return res.json({ code: coupon.code, id: coupon.id });
    }
    case "order.cod_cancelled":
      if (event.data.cancelRequested) await cancelOrder(event.data.orderId);
      else await addOrderNote(event.data.orderId, event.data.note);
      break;
    case "order.cod_confirmed":
      await markConfirmed(event.data.orderId);
      break;
    case "customer.unsubscribed":
      await unsubscribe(event.data.phone, event.data.email);
      break;
  }
  await markHandled(event.id);
  res.status(200).end();
});

<script src="https://capiagent.com/widget.js" data-store-id="STORE_ID" async></script>

// Product page — on load (and on every SPA navigation to a product)
AISA.track("PRODUCT_VIEW", { productExternalId: "SKU-1001" });

// After every successful add to cart, from any button
AISA.track("ADD_TO_CART", { productExternalId: "SKU-1001", quantity: 1 });

// Checkout page opened
AISA.track("CHECKOUT_STARTED", {});

// Thank-you page — the order id you send to POST /orders
AISA.track("CHECKOUT_STARTED", { orderExternalId: "10045" });

// Safe before widget.js has loaded (queued, sent on load):
(window.AISA = window.AISA || {}).q = window.AISA.q || [];
window.AISA.q.push(["ADD_TO_CART", { productExternalId: "SKU-1001", quantity: 1 }]);

// Every page, while the customer is logged in (phone or email required)
AISA.identify({ name: "Sara", phone: "966501234567", email: "sara@example.com" });

// Or, before widget.js has loaded:
(window.AISA = window.AISA || {}).q = window.AISA.q || [];
window.AISA.q.push(["identify", { name: "Sara", phone: "966501234567", email: "sara@example.com" }]);

// Signed (recommended): add "hash", computed on YOUR server — see SIGNED_IDENTIFY_SAMPLE.
// Then the same customer keeps one chat history in every browser.
AISA.identify({ name: "Sara", email: "sara@example.com", hash: "<?= $capiHash ?>" });