الربط

نقاط النهاية والصلاحيات

الفكرة

لا تصل إلى بيانات أي تاجر إلا بموافقته. الموافقة تتم برمز ربط يصدره نظامك، ويدخله التاجر في حسابه على AurMap.

1. نظامك يطلب رمزا لفرع محدد عنده.
2. تعرض الرمز للتاجر نصا أو QR في لوحة التحكم عندك.
3. التاجر يمسح الرمز من حسابه في AurMap، ويختار المكان، ويراجع الصلاحيات، ويوافق. يوافق فقط من يملك صلاحية «AurMap والتكاملات» في حساب التاجر.

في شاشة الموافقة يرى التاجر اسم شريكك الموثق وشعاره من لوحة المطورين، لا الاسم الذي ترسله في external_location_name. بهذا لا يستطيع أحد أن ينتحل اسم شريك آخر. 4. يصلك حدث link.created.

الرمز صالح 15 دقيقة، ويستعمل مرة واحدة.

الصلاحيات

الصلاحيات سبع. customer:contact يمنحها التاجر بموافقة منفصلة، حماية لبيانات العملاء الشخصية بحسب نظام حماية البيانات الشخصية. اطلبها فقط إذا احتاجها نظامك، مثل برنامج ولاء يطابق العميل برقمه. قبل أن تطلبها يوافق فريقنا على حسابك لها، ويرى التاجر الغرض الذي أعلنته في شاشة الربط.

اطلب ما تحتاجه فقط. التاجر يرى القائمة قبل الموافقة.

مستوى الربط

لكل مكان مصدر واحد للقائمة. إذا ربط التاجر مكانا له مصدر آخر، نسأله أيهما يبقى. لا يكون للمكان مصدران في الوقت نفسه.

إصدار رمز ربط

POST /link-codes

aurmap POST /v1/link-codes '{"level":"place","external_location_id":"pos-branch-17","external_location_name":"Al Rayhan, Olaya","scopes":["catalog:write","inventory:write","orders:read","orders:write"]}'

201

{
  "code": "7KQ2M9XA",
  "display_code": "7KQ2-M9XA",
  "qr_url": "https://aurmap.com/link/7KQ2M9XA",
  "qr_png_url": "https://partners.aurmap.com/v1/link-codes/7KQ2M9XA/qr.png",
  "status": "pending",
  "expires_at": "2026-10-14T12:15:00Z"
}

اعرض display_code كما هو، أو اعرض QR يفتح qr_url. الرمز مكون من 8 حروف وأرقام، ولا يحتوي I ولا L ولا O ولا U، فلا يختلط على التاجر.

const code = await aurmap('POST', '/v1/link-codes', {
  level: 'place',
  external_location_id: 'pos-branch-17',
  external_location_name: 'Al Rayhan, Olaya',
  scopes: ['catalog:write', 'inventory:write', 'orders:read', 'orders:write'],
});
showToMerchant(code.display_code, code.qr_url);

$code = aurmap('POST', '/v1/link-codes', [
    'level' => 'place',
    'external_location_id' => 'pos-branch-17',
    'external_location_name' => 'Al Rayhan, Olaya',
    'scopes' => ['catalog:write', 'inventory:write', 'orders:read', 'orders:write'],
]);

متابعة الرمز

الحدث link.created يكفي. وإذا أردت أن تعرض للتاجر النتيجة مباشرة، اسأل عن الرمز:

aurmap GET /v1/link-codes/7KQ2M9XA

{ "code": "7KQ2M9XA", "status": "redeemed", "link_id": "lnk_2h6j4n" }

الحالات: pending وredeemed وexpired وdeclined.

كائن الربط

{
  "link_id": "lnk_2h6j4n",
  "mode": "live",
  "level": "place",
  "merchant": { "merchant_id": "mer_5r8k2d", "name": "مطعم الريحان" },
  "place": { "place_id": "plc_9q3w7e", "name": "الريحان - العليا" },
  "external_location_id": "pos-branch-17",
  "scopes": ["catalog:write", "inventory:write", "orders:read", "orders:write"],
  "created_at": "2026-10-14T12:03:11Z",
  "removed_at": null
}

إضافة صلاحية

أصدر رمزا جديدا بكل الصلاحيات التي تريدها، القديمة والجديدة. حين يوافق التاجر يتحدث الربط نفسه، ويصلك link.updated. لا تضاف صلاحية دون موافقة التاجر.

إلغاء الربط

• التاجر يستطيع إلغاء الربط في أي وقت من حسابه.
• وأنت تستطيع إلغاءه بـ DELETE /links/{link_id}.
• في الحالتين يصلك link.removed، وفيه removed_by: merchant أو partner أو aurmap.

aurmap DELETE /v1/links/lnk_2h6j4n

{ "link_id": "lnk_2h6j4n", "removed_at": "2026-10-20T08:00:00Z", "removed_by": "partner" }

بعد الإلغاء:

• أي طلب على هذا المكان يرد 410 LINK_REMOVED.
• تختفي قائمتك من صفحة المكان خلال دقيقة.
• الطلبات التي وصلت قبل الإلغاء تستطيع إنهاءها خلال 24 ساعة، فلا يبقى طلب معلقا في المطبخ.

أخطاء شائعة