كيفية العثور على العملاء المحتملين وإثرائهم من خلال Claude Code

تتيح لك واجهة Firecrawl Alexandria people API أن يجد وكيل البرمجة الخاص بك الأشخاص ويُثري بياناتهم من خلال مفتاح Firecrawl واحد. تكتشف الأدوات مجانًا عبر v2/search، وتسرد المرشحين عبر Apollo people/search مقابل 0 رصيد، وتكشف بيانات شخص واحد عبر Apollo people/match مقابل 30 رصيدًا، أو تُثري بريدًا إلكترونيًا معروفًا عبر People Data Labs person/enrich مقابل 60 رصيدًا. ويمر كل استدعاء عبر POST /v2/scrape.

تأتي كل خطوة أدناه مرتين: موجّه (prompt) لـ Claude Code (أو Codex) وأمر curl الخام، حتى تتمكن من كتابة سكربت له دون وكيل.

ما هي واجهة Firecrawl Alexandria people API

Alexandria هي مكتبة Firecrawl لمزوّدي البيانات الخارجيين، ويمكن الوصول إليها بمفتاح API الذي تستخدمه بالفعل في الكشط. ووفقًا لـ وثائق Alexandria، تكتشف أداة ما، وتفحص مدخلاتها وسعرها، ثم تشغّلها عبر scrape. الاكتشاف مجاني؛ أما التنفيذ فيستهلك الأرصدة المذكورة في الأداة.

تضم فئة People اثني عشر مزوّدًا. ويغطي اثنان منها معظم أعمال التنقيب عن العملاء المحتملين:

الأسعار هي المعروضة بجانب زر Run في صفحة Apollo وصفحة People Data Labs بتاريخ 4 نوفمبر 2026. وتذكر صفحة Apollo أيضًا أن فشل people/match «لا يُرجع أي شخص ولا تُحتسب عليه رسوم».

كم تبلغ تكلفة البحث عن شخص بالدولار

تعتمد قيمة الرصيد على خطتك. ووفقًا لـ صفحة أسعار Firecrawl، تبلغ خطة Hobby 19 دولارًا شهريًا مقابل 5,000 رصيد، وخطة Standard 99 دولارًا شهريًا مقابل 100,000 رصيد، وكلتاهما تُحاسب شهريًا.

الحساب: 19 ÷ 5,000 = 0.0038 دولار لكل رصيد، و99 ÷ 100,000 = 0.00099 دولار. البحث عن 100 معاينة وكشف أفضل 20 منها يكلّف 600 رصيد، وهو ما يتسع داخل الحد الشهري البالغ 1,000 رصيد في الخطة المجانية. كما تحدّ People Data Labs الاستخدام عند 50,000 استدعاء API سنويًا لكل مؤسسة، مشتركة بين نقاط وصول الشخص والشركة، بما في ذلك إعادة المحاولات.

الخطوة 1: اربط Claude Code بـ Firecrawl

أسرع طريق هو مثبّت الوكلاء من Firecrawl. فهو يضيف مهارات Firecrawl إلى كل وكيل برمجة يكتشفه ويسجّل دخولك عبر المتصفح:

npx -y firecrawl-cli@latest init --all --browser

أعد تشغيل الوكيل بعد ذلك. وللقيام بذلك يدويًا، استخدم npm install -g firecrawl-cli وfirecrawl login. ويغطي دليل Firecrawl CLI الخاص بنا كلتيهما، كما يغطي شرح Firecrawl MCP خادم MCP، الذي يوفّر الحلقة نفسها عبر firecrawl_search وfirecrawl_find_tools وfirecrawl_scrape.

بالنسبة لأمثلة curl أدناه، صدّر مفتاحك مرة واحدة:

export FIRECRAWL_API_KEY="fc-..."   # never commit this

الخطوة 2: اكتشف أدوات الأشخاص مجانًا

اسأل وكيلك أولًا، لأن الاكتشاف لا يكلّف شيئًا:

Use Firecrawl Alexandria to find tools that search people by job title and
company, and tools that enrich a person from an email. Inspect Apollo and
People Data Labs with find-tools and show me each capability's inputs and
credit price before you run anything.

في جوهر الأمر، هذا بحث مع ضبط sources على ["alexandria"] فقط. واستبعاد "web" يبقيه مجانيًا، لأن نتائج الويب تُحتسب برسوم:

curl https://api.firecrawl.dev/v2/search \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "find people by job title and company", "sources": ["alexandria"], "limit": 5}'

تُدرج الاستجابة tools مرتّبة، كل منها بمزوّد وإمكانية ووصف. ولقراءة المدخلات والأسعار، يشغّل الوكيل find-tools:

firecrawl find-tools --options '{"providers":["apollo","people-data-labs"],"level":"tools","expand":["options","response"]}' --include-costs

الخطوة 3: ابحث في Apollo عن مرشحين مقابل 0 رصيد

توجّه صفحة Apollo الوكلاء إلى البدء من هنا دائمًا: فهذا مجاني ويُظهر من هو موجود قبل أن تنفق أي شيء.

Run Apollo people/search through Firecrawl Alexandria for "VP of Sales" and
"Head of Revenue" at stripe.com and linear.app, 25 per page. Show name,
title, company and has_email. Don't reveal anyone yet.

الاستدعاء الخام:

curl https://api.firecrawl.dev/v2/scrape \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alexandria": {
      "provider": "apollo",
      "capability": "people/search",
      "options": {
        "person_titles": ["VP of Sales", "Head of Revenue"],
        "q_organization_domains_list": ["stripe.com", "linear.app"],
        "page": 1,
        "per_page": 25
      }
    }
  }'

تحمل كل معاينة اسم عائلة مُقنّعًا وid الخاص بـ Apollo، وهو المدخل الأكثر موثوقية للخطوة التالية.

الخطوة 4: اكشف بيانات شخص واحد عبر people/match

الآن ادفع فقط مقابل الأشخاص الذين يستحقون التواصل، بواقع 30 رصيدًا لكل مطابقة:

For the 3 previews with has_email true, run Apollo people/match with their
id. Don't set reveal_personal_emails or reveal_phone_number.

curl https://api.firecrawl.dev/v2/scrape \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alexandria": {"provider": "apollo", "capability": "people/match", "options": {"id": "<apollo_id>"}}}'

اترك رايتَي الكشف مُعطّلتين ما لم تكن بحاجة إليهما. وتذكر صفحة Apollo أن البريد الإلكتروني الشخصي «يُحتسب برسم إضافي» وأن رقم الهاتف «أغلى بكثير من المطابقة الأساسية».

الخطوة 5: أثرِ بريدًا إلكترونيًا معروفًا عبر People Data Labs

عندما يكون لديك بريد إلكتروني بالفعل، مثلًا من تسجيل وارد، فإن person/enrich يُرجع ملفًا شخصيًا أكثر اكتمالًا: بريد العمل، والمسمى الوظيفي، والشركة، ورابط LinkedIn، والخبرة والمهارات.

Enrich jane@example.com with People Data Labs person/enrich through
Firecrawl Alexandria. Set min_likelihood to 6 so a weak match comes back
as a 404 instead of a wrong record.

curl https://api.firecrawl.dev/v2/scrape \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alexandria": {"provider": "people-data-labs", "capability": "person/enrich", "options": {"email": "jane@example.com", "min_likelihood": 6}}}'

تتراوح قيمة min_likelihood من 1 إلى 10، وقيمتها الافتراضية 2. وتوضّح صفحة المزوّد المقايضة بوضوح: خطأ 404 «مجاني هنا، أما السجل الخاطئ فليس كذلك». ارفع القيمة قبل أن تُكرّر العملية على قائمة.

التعامل مع THIRD_PARTY_DATA_TERMS_REQUIRED

قد يفشل أول استدعاء مدفوع لمزوّد ما مع الخطأ THIRD_PARTY_DATA_TERMS_REQUIRED. ووفقًا للوثائق، يحمل الخطأ requiresAction.url، ويتعيّن على مسؤول المؤسسة فتحه وقبول شروط ذلك المزوّد قبل أن يمر أي استدعاء.

لا تدع الوكيل يمرّره بنقرة. تقول الوثائق إن الوكلاء يحتاجون إلى تفويض صريح من المستخدم قبل قبول الشروط، التي تنظّم كيفية استخدامك للبيانات الشخصية. أضف سطرًا واحدًا إلى CLAUDE.md: «إذا أُرجع استدعاء الخطأ THIRD_PARTY_DATA_TERMS_REQUIRED، فتوقّف واعرض عليّ requiresAction.url».

قراءة حمولة alexandria[].data

تعود النتائج في مصفوفة alexandria، بإدخال واحد لكل استدعاء أداة، مع حمولة المزوّد تحت data. ويغلّف HTTP الخام نتيجة SDK كاملة في data على المستوى الأعلى، لذا في استجابة curl توجد مطابقة Apollo في data.alexandria[0].data.person:

curl -s https://api.firecrawl.dev/v2/scrape ... | jq '.data.alexandria[0].data.person | {name, title, email, linkedin_url}'

فحصان يمنعان دخول صفوف سيئة إلى نظام CRM لديك:

1. تحقق من كل نتيجة بحثًا عن أخطاء قبل قراءة data. وتقول الوثائق ذلك صراحةً؛ فقد يفشل استدعاء واحد بينما ينجح طلب HTTP.
2. تعامل مع رسائل البريد النائبة على أنها مفقودة. تشير Apollo إلى أن البريد غير المكشوف قد يعود بالنص الحرفي email_not_unlocked@domain.com، حتى عندما يقول email_status إنه موثّق.

أما في People Data Labs، فيوجد الشخص تحت data داخل النتيجة، إلى جانب status وlikelihood في المغلّف.

أرسل ملاحظاتك واسترد رصيدًا

تدفع لك Alexandria مقابل الملاحظات. كل إرسال يعيد رصيدًا واحدًا مقابل أي تقييم، بحد أقصى يومي بتوقيت UTC يبلغ 10 أرصدة لكل موقع و100 لكل فريق. ولديك 20 دقيقة من آخر استدعاء لـ Alexandria من فريقك؛ بعد ذلك تحصل على FEEDBACK_WINDOW_EXPIRED.

من سطر الأوامر، شغّل firecrawl alexandria feedback (راجع --help للاطلاع على الخيارات). وعبر MCP، يستدعي الوكيل firecrawl_feedback مع endpoint: "alexandria". وسطر موجّه واحد يفي بالغرض: «إذا بدت نتيجة ما خاطئة أو فارغة، فأرسل ملاحظة إلى Alexandria تصف ذلك».

دع Claude Code يحرس هذه الاستدعاءات باستخدام Apidog CLI

بمجرد أن يعتمد سكربت على people/search في إرجاع id يقبله people/match، فإن إعادة تسمية حقل ما تكسره بصمت. ويستطيع وكيلك تحويل الاستدعاءات الواردة في هذا الدليل إلى سيناريو اختبار انحدار في Apidog CLI وتشغيله وفق جدول زمني. وأنت تكتب موجّهًا واحدًا.

أعدّ سطر الأوامر ومهارة الوكيل الخاصة به مرة واحدة:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_APIDOG_TOKEN>
npx -y skills add https://apidog.com   # pick Claude Code or Codex when prompted

ثم أعطِ Claude Code هذا الموجّه:

Write an OpenAPI 3 file for three Firecrawl calls from this guide:
POST /v2/search with sources ["alexandria"], POST /v2/scrape for apollo
people/search (per_page 1), and POST /v2/scrape for apollo people/match.
All send Authorization: Bearer {{FIRECRAWL_API_KEY}}. Import it into Apidog
project <projectId> and create a "Firecrawl" environment for
https://api.firecrawl.dev. Build a test scenario that runs the three in
order, saves data.alexandria[0].data.people[0].id as personId and passes it
to people/match, and asserts status 200, no result error, and a person
object on the match. Run it and summarize failures.

يقرأ الوكيل مخطط حمولة كل استدعاء، ويتحقق من صحته، ثم يشغّل أوامر مثل هذه:

apidog import --project <projectId> --format openapi --file ./firecrawl-people.json
apidog environment create Firecrawl --project <projectId> --base-url https://api.firecrawl.dev
apidog test-scenario create --project <projectId> --name "Alexandria people" --folder-id <folderId> --priority <priority>
apidog cli-schema get test-scenario-update
apidog cli-schema validate test-scenario-update --file ./people-scenario.json
apidog test-scenario update <scenarioId> --project <projectId> --file ./people-scenario.json
apidog run -t <scenarioId> --project <projectId> -e <envId> \
  --env-var "FIRECRAWL_API_KEY=$FIRECRAWL_API_KEY" -r cli,junit

تكلّف كل جولة كاملة 30 رصيدًا مقابل المطابقة، لذا جدولها يوميًا بدلًا من تشغيلها مع كل commit. ويسرد مرجع apidog run رايات التقرير والتكرار، ويوضّح Apidog CLI في Claude Code الإعداد بمزيد من التفصيل. وتغطي خطة Apidog المجانية حتى 4 مستخدمين.

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

هل واجهة Firecrawl Alexandria people API مجانية؟ الاكتشاف مجاني، وقد أظهر Apollo people/search 0 رصيد بتاريخ 4 نوفمبر 2026. أما كشف بيانات شخص فيستهلك أرصدة: 30 مقابل Apollo people/match و60 مقابل People Data Labs person/enrich. وتتضمن الخطة المجانية 1,000 رصيد شهريًا دون بطاقة.

هل أحتاج إلى حسابات منفصلة لدى Apollo أو People Data Labs؟ لا. تشغّل Alexandria كليهما عبر مفتاح Firecrawl API الخاص بك وتحتسب الرسوم بأرصدة Firecrawl. لكن على مسؤول المؤسسة قبول شروط كل مزوّد مرة واحدة، وهو ما يطلبه الخطأ THIRD_PARTY_DATA_TERMS_REQUIRED.

لماذا تُظهر استجابة people/match الخاصة بي email_not_unlocked@domain.com؟ هذا هو النص النائب لدى Apollo لبريد لم يُكشف. تعامل معه على أنه غير متاح، حتى لو قال email_status إنه موثّق.

هل يمكن لـ Codex أو Cursor تشغيل هذا بدلًا من Claude Code؟ نعم. يقوم npx -y firecrawl-cli@latest init --all بإعداد كل وكيل يُكتشف، وتعمل أدوات MCP في أي عميل MCP. كما تعمل استدعاءات curl دون أي وكيل على الإطلاق.

كيف أتجنّب الدفع مقابل مطابقات خاطئة؟ ابحث قبل أن تطابق، وطابق باستخدام id الخاص بـ Apollo بدلًا من الاسم، واضبط min_likelihood على 6 أو أعلى في People Data Labs. ولا تحتسب Apollo رسومًا على الفشل، وخطأ 404 من PDL مجاني.