ابنِ على Hekk

سجّل وكيلك، ومرّر مستخدمك عبر شاشة موافقة Hekk، ثم نادِ ١٢ أداة عبر MCP أو REST — السجل نفسه يشغّل الاثنين.

الوكلاء عملاء OAuth عموميون: رمز تفويض مع PKCE ‏(S256). لا يوجد سر عميل — والـ client_id ليس بيانات اعتماد.

الربط السهل (مسار المستهلك)

المساعدون الشخصيون لا يحتاجون تسجيلاً ولا OAuth: أرسل بيانات العميل نفسه، فترسل له حِك رمزاً لمرة واحدة، وتمريره يمنحك رمز وصول Bearer مرتبطاً بتفويض قابل للإلغاء. استخدم OAuth أدناه عندما تطلق منتجاً يحتاج هوية عميل خاصة وروابط إعادة توجيه.

# 1. Start — Hekk sends the customer a one-time code (SMS or email)
curl -X POST https://hekkapp.com/api/agent/v1/connect/start \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fatima Ahmed",
    "phone": "3xxxxxxx",
    "email": "[email protected]",
    "need": "AC repair at home, tomorrow morning",
    "budget": 25,
    "agent_name": "Claude",
    "locale": "ar"
  }'
# → { "connect_id": "…", "channel": "sms", "expires_in_seconds": 900 }

# 2. Verify — relay the code the customer read back to you
curl -X POST https://hekkapp.com/api/agent/v1/connect/verify \
  -H "Content-Type: application/json" \
  -d '{ "connect_id": "<connect_id>", "code": "123456" }'
# → { "access_token": "hga_…", "refresh_token": "hgr_…", "grant": { … }, "customer": { … } }

التفويضات الصادرة بهذا المسار تتبع مُعرّف العميل المشترك personal-assistant (استخدمه لتجديد الرمز). الميزانية المذكورة تصبح سقف المهمة وسقف الثلاثين يوماً معاً؛ وبدون ميزانية ينتظر كل حجز أو دفعة موافقة العميل عبر البريد.

البدء السريع

1. 1. سجّل وكيلك أدناه — تحصل على client_id فورًا.

2. 2. أرسل مستخدمك إلى عنوان التفويض (يسجّل الدخول ويحدد الصلاحيات والحدود):

   https://hekkapp.com/en/agents/connect?response_type=code&client_id=<client_id>&redirect_uri=<redirect_uri>&scope=discover%20book&state=<state>&code_challenge=<S256_challenge>&code_challenge_method=S256

3. 3. استبدل الرمز بالرموز (وصول ساعة، تحديث ٣٠ يومًا متجدد):

   curl -X POST https://hekkapp.com/api/agent/v1/oauth/token \
     -H "Content-Type: application/json" \
     -d '{
       "grant_type": "authorization_code",
       "code": "<code>",
       "redirect_uri": "<redirect_uri>",
       "client_id": "<client_id>",
       "code_verifier": "<pkce_verifier>"
     }'

   curl -X POST https://hekkapp.com/api/agent/v1/oauth/token \
     -H "Content-Type: application/json" \
     -d '{
       "grant_type": "refresh_token",
       "refresh_token": "<refresh_token>",
       "client_id": "<client_id>"
     }'

4. 4. نادِ الأدوات عبر MCP أو REST — أدوات الإنفاق تتطلب Idempotency-Key عبر REST:

   {
     "mcpServers": {
       "hekk": { "url": "https://hekkapp.com/agents/mcp" }
     }
   }

   curl -X POST https://hekkapp.com/api/agent/v1/tools/create_booking \
     -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: <unique-key>" \
     -d '{
       "providerId": "<providerId>",
       "serviceId": "<serviceId>",
       "address": "Building 12, Road 3419, Manama",
       "acceptedPrice": 25.000
     }'

رمز الوصول يعيش ساعة، لكن المنحة والوكيل والعميل يُعاد التحقق منهم عند كل نداء — الإلغاء والإيقاف ينفذان فورًا لا عند الانتهاء.

البدء السريع ونقاط الاتصال

الصلاحيات

مرجع الأدوات

{ "categories": [{ "slug": "plumbing", "nameEn": "Plumbing", "nameAr": "السباكة" }] }

{ "quotes": [{ "providerId": "…", "providerName": "…", "startingPrice": 15.000, "currency": "BHD" }] }

{ "bookingId": "…", "status": "PENDING", "price": 25.000 }

{ "status": "ACCEPTED", "price": 25.000, "provider": { "name": "…", "phone": "+973…" } }

{ "bookings": [{ "bookingId": "…", "status": "COMPLETED", "hasReview": false }] }

{ "messageId": "…", "at": "2026-01-01T10:00:00.000Z" }

{ "messages": [{ "from": "PROVIDER", "body": "On my way", "viaAgent": false }] }

{ "bookingId": "…", "status": "COMPLETED" }

{ "paymentId": "…", "status": "AUTHORIZED", "method": "CASH" }

{ "reviewId": "…", "attribution": "via_agent" }

{ "bookingId": "…", "status": "CANCELLED" }

{ "actions": [{ "tool": "create_booking", "result": "ok", "amount": 25.000 }] }

{ "approvalId": "…", "status": "APPROVED", "tool": "create_booking", "bookingId": "…", "expiresAt": "…" }

الضوابط والأخطاء والحدود

{
  "status": "pending_human_approval",
  "approval": {
    "id": "<approvalId>",
    "confirmUrl": "https://hekkapp.com/en/agents/approvals/<token>",
    "expiresAt": "2026-01-01T12:30:00.000Z"
  },
  "reason": "This action is over your spend limit and needs your confirmation."
}

// Then poll the outcome (do NOT retry the original call with a new Idempotency-Key):
// POST https://hekkapp.com/api/agent/v1/tools/get_approval  { "approvalId": "<approvalId>" }
// → { "status": "PENDING" | "APPROVED" | "DECLINED" | "EXPIRED", "bookingId": "…" }

تغيير (يوليو 2026): عندما يطلب الوكيل صلاحية كاملة (بدون معامل scope)، تعرض شاشة الموافقة صلاحيات الإنفاق (book, complete, pay, review) غير محددة افتراضيًا — على المستخدم تفعيلها بنفسه. اطلب فقط الصلاحيات التي يحتاجها وكيلك.