> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pubrio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# استبدال الأشخاص

> استهلك أرصدة لفتح بريد إلكتروني للعمل موثَّق، وبريد إلكتروني شخصي، ورقم هاتف لشخص سبق أن تعرّفت عليه — أنماط فردية ودفعية ودفعية غير متزامنة.

واجهة Redeem People تحوّل `people_search_id` (أو رابط LinkedIn) إلى المجموعة الكاملة من بيانات التواصل الموثَّقة — بريد العمل، البريد الشخصي، الهاتف — لذلك الشخص. أنت تنفق أرصدة فقط عندما تُعاد بيانات تواصل فعلية.

```bash theme={null}
curl -X POST https://api.pubrio.com/redeem/people \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "people_search_id": "e37ccf38-ea8f-422e-9874-cb23b15e8fe4",
    "people_contact_types": ["email-work", "phone"]
  }'
```

## متى تستخدم Redeem

استخدم Redeem عندما **تعرف بالفعل هوية الشخص** وتحتاج إلى بيانات التواصل الخاصة به:

* شغّلت [People Search](/ar/api-reference/endpoint/people/search) وتريد فتح بيانات التواصل للنتائج المطابقة
* لديك رابط ملف LinkedIn وتريد التواصل مع الشخص
* لديك `people_search_id` من استجابة سابقة لـ Pubrio

إن كان لديك بدلًا من ذلك **بريد إلكتروني أو هاتف وتريد إيجاد الشخص المطابق**، استخدم [البحث عن بيانات التواصل لشخص](/ar/developer-guides/people-contact-lookup) — فهو الاتجاه المعاكس وبتكلفة رصيد واحد لكل تطابق.

## ثلاثة أنماط للاستدعاء

| النقطة الطرفية                    | استخدمها عندما               | السلوك                                          |
| --------------------------------- | ---------------------------- | ----------------------------------------------- |
| `POST /redeem/people`             | شخص واحد في كل مرة           | متزامن. تُعاد بيانات التواصل ضمن الاستجابة.     |
| `POST /redeem/people/batch`       | من 2 إلى N شخص دفعة واحدة    | غير متزامن. تُعاد `redeem_query_id` فورًا.      |
| `POST /redeem/people/batch/query` | استعلام دوري عن نتائج الدفعة | تُعاد مجموعة النتائج الكاملة عند اكتمال الدفعة. |

مسار الدفعة هو النمط المناسب لأي سير عمل قائم على قائمة — رفع ملفات CSV، تسجيل ضمن تسلسل تواصل، مزامنة CRM — لأنه يوازي عمل حل بيانات التواصل من جهة الخادم.

## بداية سريعة — استبدال فردي

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.pubrio.com/redeem/people \
    -H "pubrio-api-key: $PUBRIO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "people_search_id": "e37ccf38-ea8f-422e-9874-cb23b15e8fe4",
      "people_contact_types": ["email-work", "phone"]
    }'
  ```

  ```js JavaScript theme={null}
  const res = await fetch("https://api.pubrio.com/redeem/people", {
    method: "POST",
    headers: {
      "pubrio-api-key": process.env.PUBRIO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      people_search_id: "e37ccf38-ea8f-422e-9874-cb23b15e8fe4",
      people_contact_types: ["email-work", "phone"],
    }),
  });
  const { data } = await res.json();
  ```

  ```python Python theme={null}
  import os, requests

  res = requests.post(
      "https://api.pubrio.com/redeem/people",
      headers={"pubrio-api-key": os.environ["PUBRIO_API_KEY"]},
      json={
          "people_search_id": "e37ccf38-ea8f-422e-9874-cb23b15e8fe4",
          "people_contact_types": ["email-work", "phone"],
      },
  )
  data = res.json()["data"]
  ```
</CodeGroup>

**الاستجابة:**

```json theme={null}
{
  "data": {
    "profile": {
      "credit": 450376,
      "topup_credit": 235237,
      "total_credit_cost": 15
    },
    "peoples": [
      {
        "people_search_id": "e37ccf38-ea8f-422e-9874-cb23b15e8fe4",
        "emails": [
          { "value": "king.lai@pubrio.com", "type": "email-work", "status": "Verified" }
        ],
        "phones": [
          { "value": "+15551234567", "type": "phone", "status": null }
        ]
      }
    ]
  }
}
```

يعكس `profile` رصيدك بعد الخصم والأرصدة التي كلّفها هذا الاستدعاء، حتى تتمكن من تحديث مقياس داخل تطبيقك دون استدعاء إضافي إلى `/profile/usage`.

## المعرّفات

يمكنك تحديد الشخص المراد استبداله بطريقتين:

| المعرّف            | الوصف                                                                                                                                                                                  |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `people_search_id` | معرّف UUID تُرجعه أي نقطة بحث/查找 من Pubrio. الأرخص والأكثر موثوقية — دون خطوة حل إضافية.                                                                                               |
| `linkedin_url`     | رابط ملف LinkedIn (مثل `https://www.linkedin.com/in/jane-doe-123`). يحوّله Pubrio أولًا إلى `people_search_id`؛ وإن كان الملف جديدًا، قد يشمل ذلك خطوة إثراء خارجية تُنفَّذ مرة واحدة. |

`people_contact_types` هو العقد الذي يحدد ما تريد استرجاعه. امزج أيًا من `email-work` و`email-personal` و`phone` — تُفرَض عليك الرسوم حسب النوع المُعاد فعليًا، لا حسب النوع المطلوب. طلب `["email-work", "phone"]` والحصول على `email-work` فقط يُحصّل رسومًا على البريد الإلكتروني فقط.

## استبدال دفعي (نمط غير متزامن)

لأكثر من شخص واحد، استخدم مسار الدفعة. فهو ينفّذ كل عملية استبدال بالتوازي من جهة الخادم ويتجنب تكلفة الرحلة ذهابًا وإيابًا لكل طلب.

**الخطوة 1 — الإرسال:**

```bash theme={null}
curl -X POST https://api.pubrio.com/redeem/people/batch \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "peoples": [
      "540574d1-ff74-475b-aea2-f8ae643b806d",
      "e37ccf38-ea8f-422e-9874-cb23b15e8fe4"
    ],
    "people_contact_types": ["email-work", "phone"]
  }'
```

```json theme={null}
{
  "data": {
    "redeem_query_id": "a046c1da-b3d4-4ca1-aca6-1dd8c8055701",
    "is_completed": false,
    "estimated_time": 6,
    "estimated_time_type": "second"
  }
}
```

**الخطوة 2 — الاستعلام الدوري:**

```bash theme={null}
curl -X POST https://api.pubrio.com/redeem/people/batch/query \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "redeem_query_id": "a046c1da-b3d4-4ca1-aca6-1dd8c8055701" }'
```

عندما تكون `is_completed` بقيمة `true`، تحتوي الاستجابة على مصفوفة `peoples` الكاملة ببيانات التواصل المحلولة وإجمالي تكلفة الأرصدة للدفعة.

<Tip>
  استعلم بالوتيرة التي يبلغ عنها `estimated_time`. الاستعلام بوتيرة أضيق من التقدير يهدر رحلات الشبكة فقط — فالعمل لم يكتمل بعد.
</Tip>

## تكاليف الأرصدة

تُخصم الأرصدة **لكل جهة تواصل مُعادة**، لا لكل طلب. التسعير لكل سجل:

| نوع بيانات التواصل              | أرصدة لكل سجل |
| ------------------------------- | ------------- |
| `email-work` / `email-personal` | 5             |
| `phone`                         | 10            |

إن لم يكن لدى الشخص بريد عمل وطلبت `email-work` فقط، فلن تُفرَض عليك أي رسوم لذلك السجل. وإن طلبت بريدًا إلكترونيًا وهاتفًا معًا وأعاد Pubrio كليهما، فستُحصّل رسوم عليهما معًا. راجع [جدول الأسعار](/ar/get-started/pricing) الكامل للاطلاع على المعدلات الخاصة بكل خطة.

## أنماط شائعة

<CardGroup cols={2}>
  <Card title="مسار البحث ثم الاستبدال" icon="magnifying-glass">
    شغّل [People Search](/ar/api-reference/endpoint/people/search)، ودع المستخدم يختار صفوفًا في واجهتك، ثم أرسل معرّفات `people_search_id` المختارة عبر `/redeem/people/batch`. لن تُحصّل رسوم إلا على ما يُستخدم فعليًا.
  </Card>

  <Card title="تدفق لصق روابط LinkedIn" icon="linkedin">
    اقبل قائمة روابط LinkedIn من تصدير CRM أو إضافة متصفح. أرسلها عبر `/redeem/people` (فردي) أو أنشئ غلافًا دفعيًا بسيطًا.
  </Card>

  <Card title="تسجيل ضمن تسلسل تواصل" icon="envelope">
    قبل إضافة جهات التواصل إلى وتيرة تواصل صادرة، استبدل `email-work` فقط — يبقي التكلفة قابلة للتوقع بينما يزوّد أداة الإرسال لديك بعناوين قابلة للتسليم.
  </Card>

  <Card title="إثراء CRM" icon="database">
    اربط سجلات CRM القائمة بـ `people_search_id` (عبر [People Lookup](/ar/api-reference/endpoint/people/lookup))، ثم نفّذ الاستبدال دفعيًا وفق جدولة.
  </Card>
</CardGroup>

## الأسئلة الشائعة

<AccordionGroup>
  <Accordion title="هل سيتم تحصيل رسوم إن لم توجد بيانات تواصل؟">
    لا. تُخصم الأرصدة لكل سجل مُعاد. إن لم يتوفر بريد عمل لشخص ما، فلن تدفع شيئًا مقابل ذلك النوع من بيانات التواصل — حتى إن كنت قد طلبته.
  </Accordion>

  <Accordion title="ماذا لو ظهر نفس الشخص مرتين في دفعتي؟">
    تُزال التكرارات من جهة الخادم. تُحصَّل الرسوم مرة واحدة فقط.
  </Accordion>

  <Accordion title="ماذا يحدث إن كان رابط LinkedIn غير معروف لدى Pubrio؟">
    يحاول Pubrio حلًا خارجيًا لمرة واحدة. إن أمكن حلّ الملف الشخصي، يُطبَّق تسعير الاستبدال المعتاد. وإن تعذّر ذلك، لا تُحصّل أي أرصدة.
  </Accordion>

  <Accordion title="ما مدى حداثة بيانات التواصل؟">
    يعيد Pubrio التحقق من سجلات البريد الإلكتروني والهاتف بشكل دوري متجدد. يأتي كل سجل تواصل مصحوبًا بحقل `status` (`Verified`، أو `null`، إلخ) بحيث يمكنك تصفية السجلات الموثَّقة فقط من جهتك.
  </Accordion>

  <Accordion title="هل يمكنني استبدال الهاتف فقط، أو البريد فقط، أو البريد الشخصي فقط؟">
    نعم — `people_contact_types` مصفوفة. مرّر بالضبط الأنواع التي تريدها؛ ستُحصَّل رسوم فقط على ما يُعاد فعليًا.
  </Accordion>

  <Accordion title="دفعي مقابل فردي — متى يتفوق النمط غير المتزامن؟">
    عند تجاوز نحو 3 سجلات، تتفوق الدفعة من حيث زمن الاستجابة وموثوقية كل سجل. تنفّذ نقطة الدفعة التوزيع داخليًا وتوازي أي رحلات إثراء خارجية، بحيث تقترب دفعة من 50 سجلًا من زمن إجمالي قدره 5 ثوانٍ بدل 50 رحلة طلب منفردة.
  </Accordion>
</AccordionGroup>

## صفحات ذات صلة

<CardGroup cols={2}>
  <Card title="البحث عن بيانات التواصل لشخص" icon="magnifying-glass-arrow-right" href="/ar/developer-guides/people-contact-lookup">
    بحث عكسي: أوجد شخصًا من بريد إلكتروني أو هاتف أو اسم + نطاق. رصيد واحد لكل تطابق.
  </Card>

  <Card title="People Search" icon="users" href="/ar/api-reference/endpoint/people/search">
    ابحث عن أشخاص يطابقون ملفًا معينًا (المنصب، الموقع، حجم الشركة، التقنيات، إلخ).
  </Card>

  <Card title="People Lookup" icon="user" href="/ar/api-reference/endpoint/people/lookup">
    احصل على الملف الكامل لشخص واحد من معرّف — دون فتح بيانات التواصل.
  </Card>

  <Card title="الأسعار" icon="coins" href="/ar/get-started/pricing">
    تكاليف الأرصدة عبر جميع النقاط الطرفية، حسب فئة الخطة.
  </Card>
</CardGroup>