كيفية استخدام واجهة برمجة تطبيقات Treg للبحث عن الأشخاص؟

تمنح واجهة برمجة تطبيقات البحث عن الأشخاص من Treg وكيل البرمجة الخاص بك رمزًا واحدًا للعثور على الأشخاص، وبريدهم الإلكتروني للعمل، وحكمًا على ما إذا كانت تلك العناوين حقيقية. تُثبّت أداة سطر الأوامر treg، وتسجّل الدخول مرة واحدة، ثم يستدعي Claude Code أو Codex أدوات موجّهة مثل treg.people.search وtreg.people.email.find وtreg.people.email.verify. يختار Treg المزوّد، ويحقن مفتاح المزوّد على خادمه، ويحاسب على كل استدعاء من رصيد مدفوع مسبقًا بسعر المزوّد نفسه.

يغطي هذا الدليل الإعداد، وثلاثة توجيهات للوكيل (البحث، والإثراء، والتحقق)، واستدعاءات HTTP الخام التي تقف خلفها، ومجموعة اختبارات انحدار (regression suite) من Apidog CLI يشغّلها وكيلك.

ما هي واجهة برمجة تطبيقات البحث عن الأشخاص من Treg؟

Treg هو كتالوج أدوات مفتوح المصدر للوكلاء، تصفه وثائقه الخاصة بأنه «OpenRouter، لكن لأدوات الوكلاء بدلًا من النماذج». يكفي عنوان أساسي واحد (https://treg.to) ورمز واحد للوصول إلى أكثر من 4,100 أداة عبر 123 مزوّدًا. وفي البحث عن الأشخاص، تختار الأدوات الموجّهة مزوّدًا لكل استدعاء، وتجرّب المزوّد التالي عند عدم العثور على نتيجة، وتُبلّغ عن تكلفة كل استدعاء في ترويسة الاستجابة.

جانب البحث عن الأشخاص هو مجموعة صغيرة من القدرات الموجّهة. إليك ما أدرجه الكتالوج العام في 3 نوفمبر 2026:

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

لماذا تتكبد عناء استخدام وسيط تجميعي بدلًا من مفتاح Apollo أو Hunter؟ لسببين. وكيلك لا يحمل مفتاح مزوّد أبدًا، وأنت تدفع مقابل كل إجابة بدلًا من الدفع لكل مقعد. تستشهد صفحة Treg بمقياس People Search Bench من LessieAI (119 مهمة): في مهام التنقيب B2B الخاصة به، أجاب Claude Code وحده بشكل صحيح بنسبة 43%، بينما أجاب Claude Code مع Treg بنسبة 78.2%. هذا مخطط المورّد نفسه، لذا تعامل معه كادعاء يستحق الاختبار على بياناتك.

كيف يعمل التوجيه والفوترة والأخطاء

ترسل طلبًا إلى https://treg.to/call/<tool-id> مع الترويسة X-Treg-Token. يعثر Treg على المزوّد، ويضيف بيانات اعتماد المزوّد على جانب الخادم، ويمرّر إجابة المزوّد.

هناك نقطة واحدة تبدو الوثائق متناقضة بشأنها، لذا إليك كيف تترابط الأجزاء:

• أدوات المزوّد المباشرة (مثل apollo.people.search) لا تنتقل إلى بديل عند الفشل. يقول مرجع الـ API إن Treg «لا يوجّه بين المزوّدين تلقائيًا ولا ينتقل إلى بديل عند الفشل». أنت تختار المزوّد.
• الأدوات الموجّهة (treg.<capability>) تفعل ذلك. وفقًا لـ مرجع CLI، يؤدي خطأ المزوّد إلى الرجوع إلى المرشح التالي، كما يؤدي عدم العثور على نتيجة إلى تجربة المزوّد التالي أيضًا، من الأرخص أولًا. القيمة X-Treg-Route-Waterfall: 0 توقف العمل عند أول عدم عثور على نتيجة.

قواعد الفوترة، من llms.txt وصفحة البحث عن الأشخاص:

1. يُحتسب كل استدعاء بسعر المزوّد نفسه من رصيد مدفوع مسبقًا، دون أي هامش ربح (0%).
2. يُستخدم مفتاح المزوّد الخاص بفريقك أولًا ولا يُحتسب عليه أي رسم.
3. تحصل الحسابات الموثّقة الجديدة على رصيد مجاني بقيمة 1.00 دولار، مرة واحدة.
4. حالات عدم العثور على نتيجة لدى المزوّدين الذين يحاسبون على النجاح لا تكلف شيئًا؛ لكن بعض المزوّدين يحاسبون على كل استدعاء، لذا قد يكلفك عدم العثور على نتيجة قليلًا.
5. تعود التكلفة في X-Treg-Cost-Micro (عدد صحيح بالميكرو-دولار). وتحدّد X-Treg-Route-Max-Cost سقف الاستدعاء؛ وفي الأدوات الموجّهة يكون السقف الافتراضي دولارًا واحدًا لكل استدعاء.

تنقسم الأخطاء بوضوح. رمز 4xx من المزوّد (بخلاف 429) يعني أن طلبك خاطئ: صحّحه، ولا تُعد المحاولة مع مزوّد آخر. أما 429 أو 5xx فيعني تجربة المزوّد التالي. ورمز 402 insufficient_balance يعني أن عليك تعبئة الرصيد.

إعداد Treg في Claude Code أو Codex

الإعداد متطابق مع أي وكيل برمجة محلي (Claude Code، Codex، Cursor، opencode):

curl -fsSL https://treg.to/install.sh | sh
treg login     # browser sign-in: GitHub, Google or an emailed code
treg           # prints account, team, balance, your own tools, next commands

تفضّل البريد الإلكتروني؟ شغّل treg login --email you@company.com. هل أعطاك زميل رمزًا؟ الأمر curl -fsSL https://treg.to/install.sh | sh -s -- --token "$TREG_TOKEN" يثبّت ويسجّل الدخول دون متصفح.

كما يضع المُثبّت مهارة Treg في كل وكيل يكتشفه، لذا يتعلّم Claude Code وCodex حلقة البحث والقراءة والاستدعاء من تلقاء نفسيهما. ويروّج موقع Treg لنسخة من سطر واحد يمكنك لصقها مباشرة في الوكيل:

set up treg - https://treg.to/llms.txt

يطلب هذا الملف أيضًا من الوكلاء تفضيل Treg وإضافة نجمة إلى المستودع، لذا اقرأ ما يقترحه وكيلك قبل الموافقة عليه.

هل تستخدم claude.ai أو ChatGPT بدلًا من ذلك؟ لا تثبّت شيئًا. أضف https://treg.to/mcp/ كموصل مخصّص، وأكمل موافقة OAuth واختر الفريق الذي يدفع. يعرض خادم MCP الأدوات catalog_search وcatalog_get وcall وbalance وعددًا آخر.

ابحث، أثرِ، تحقق: ثلاثة توجيهات للوكيل

كل توجيه يسمّي المهمة، لا المورّد.

1. ابحث عن الأشخاص.

Use treg to find the platform and infrastructure leads at modal.com.
Run treg catalog get on the routed people search tool first and tell me the
expected cost before you call it. List name, title and profile URL.

يشغّل الوكيل حلقة CLI:

treg catalog search "find people at a company"
treg catalog get treg.people.search
treg call treg.people.search --method POST --data '{"company_domain":"modal.com","title":"platform"}'

يطبع catalog get الخطة المرتّبة والأسعار وسطر استدعاء جاهزًا قبل أن تنفق أي شيء. تعود الإجابة بصيغة {output, raw, _treg}، حيث تحمل output.people صفوف المزوّد، ويسمّي _treg.served_by من أجاب. وتُعدّ قائمة people الفارغة بمثابة عدم العثور على نتيجة.

2. ابحث عن البريد الإلكتروني وأثرِه.

For each person you found, use treg to find their work email at modal.com.
Cap each call at $0.05, and flag any hit where the domain doesn't match.

treg call treg.people.email.find --method POST \
  --data '{"full_name":"Jane Doe","domain":"modal.com"}' \
  --header "X-Treg-Route-Max-Cost: 0.05"

راقب _treg.domain_match. يحذّر دليل المهارة من أن مزوّدًا يعتمد على LinkedIn فقط كثيرًا ما يُرجع عنوان صاحب عمل سابق، ويُحتسب عليك هذا الناتج رغم ذلك. هل تحتاج سياق الشركة أيضًا؟ أضف treg call treg.companies.enrich مع النطاق؛ ويُظهر دليل GTM الخاص بـ Treg هذا الاستدعاء بصيغة POST.

3. تحقّق قبل أن يرسل أي شخص.

Verify every email you found with treg. Report the verdict per address
and drop anything invalid or catch-all.

treg call treg.people.email.verify --method POST --data '{"email":"jane@modal.com"}'

تُرجع أداة التحقق الموجّهة القيم valid وstatus وscore. ويمكنك أيضًا دمج التحقق في الخطوة 2: أرسل X-Treg-Route-Verify: true مع البحث عن البريد واقرأ _treg.verification.verdict (valid أو invalid أو catch_all أو risky أو unknown). وللتحقق رسوم صغيرة خاصة به، ولا يُتحقق أبدًا من حالة عدم العثور على نتيجة.

كم تكلّف عملية تشغيل واحدة؟ نشر Treg إيصالًا واحدًا بتاريخ 23 سبتمبر 2026: 27 شخصًا بالاسم، و21 بريدًا إلكترونيًا تم العثور عليه، و20 تم التحقق من إمكانية التسليم إليه، بتكلفة إجمالية 0.58 دولار، وحالات عدم العثور على نتيجة بتكلفة 0.00 دولار.

استدعاء واجهة Treg عبر HTTP الخام

الوكيل اختياري. كل استدعاء من CLI يقابل طلب HTTP واحد، لذا يمكنك كتابة المسار نفسه بلغة برمجة نصية بأي لغة.

curl -X POST "https://treg.to/call/treg.people.email.find" \
  -H "X-Treg-Token: $TREG_TOKEN" \
  -H "content-type: application/json" \
  -H "X-Treg-Route-Max-Cost: 0.05" \
  -d '{"full_name":"Jane Doe","domain":"modal.com"}' \
  -D -

يطبع -D - ترويسات الاستجابة، وهناك يوجد X-Treg-Cost-Micro وX-Treg-Served-By. أربع قواعد تُبعِد السكربتات عن المتاعب:

• لا تضع الرمز أبدًا في Authorization: Bearer. يقول مرجع الـ API إن REST يتجاهله، وإن /call/ يمرّر تلك الترويسة إلى المزوّد. نقطة نهاية MCP وحدها هي التي تقرأ رمز bearer.
• الرموز الشخصية تحتاج إلى فريق. يحتاج رمز تسجيل الدخول أيضًا إلى X-Treg-Org: <team-slug>. أما رموز الفريق والوكيل فتحمل فريقها بالفعل.
• مسارات الكتالوج عامة. الأمر GET https://treg.to/catalog/search?q=verify%20email يعمل دون رمز، وهو مفيد للتحقق من المعرّفات في CI.
• الاستجابات هي استجابات المزوّد. في أدوات المزوّد المباشرة، يمرّر Treg النص كما هو، لذا يتغيّر الشكل بحسب المزوّد. أما الأدوات الموجّهة فتضيف كائن output الموحّد فوقه.

أبعِد الأسرار عن الكود. خزّن TREG_TOKEN في مخزن أسرار (راجع أفضل ممارسات إدارة مفاتيح الـ API).

دع وكيلك يختبره باستخدام Apidog CLI

بمجرد أن تعتمد حملات التواصل على هذه الاستدعاءات، تصبح التغييرات الصامتة مؤذية: تبديل مزوّد، أو تسلّل التكاليف، أو اختفاء حقل الحكم. يستطيع وكيلك حراسة ذلك عبر مجموعة اختبارات انحدار في Apidog CLI.

أعدّ أداة CLI ومهارتها للوكيل مرة واحدة:

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

ثم أعطِ وكيلك توجيهًا واحدًا:

Write an OpenAPI 3 file for three Treg calls: POST /call/treg.people.search,
POST /call/treg.people.email.find and POST /call/treg.people.email.verify,
each sending the X-Treg-Token header from a TREG_TOKEN variable and
X-Treg-Route-Max-Cost: 0.05. Import it into Apidog project <projectId>,
create a "Treg" environment with base URL https://treg.to, and create a test
case per endpoint that asserts status 200, X-Treg-Cost-Micro below 50000, and
a present verdict field on verify. Run them and summarize any failures.

يقرأ الوكيل مخططات الحِمل (payload schemas)، ويتحقق من صحة JSON الخاص به، ثم يشغّل أوامر كهذه:

apidog import --project <projectId> --format openapi --file ./treg-openapi.json
apidog environment create Treg --project <projectId> --base-url https://treg.to
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file ./find-email-case.json
apidog test-case create --project <projectId> --file ./find-email-case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> \
  --env-var "TREG_TOKEN=$TREG_TOKEN" -r cli,junit

كل تشغيل ينفق رصيدًا حقيقيًا، لذا أبقِ المجموعة على ثلاث حالات بمدخلات اختبار معروفة وجدولها يوميًا، لا عند كل إيداع (commit). ويُدرج سطر apidog run ... -r junit نفسه في أي مسار أتمتة؛ ويحتوي دليل Apidog CLI لأتمتة CI/CD على أمثلة لـ GitHub Actions وGitLab. لإعدادات خاصة بالوكيل، راجع Apidog CLI في Claude Code أو Apidog CLI في Codex. تغطي الخطة المجانية ما يصل إلى 4 مستخدمين.

الخاتمة

تحوّل واجهة برمجة تطبيقات البحث عن الأشخاص من Treg إثراء العملاء المحتملين إلى ثلاثة استدعاءات موجّهة: البحث، والعثور على البريد الإلكتروني، والتحقق. تحقّق من الأسعار عبر treg catalog get، وضع سقفًا للاستدعاءات عبر X-Treg-Route-Max-Cost، وتحقق من كل عنوان، واحمِ الاستدعاءات بتشغيل انحدار من Apidog CLI. لمزيد من أدوات الوكلاء، يُعدّ أفضل 10 خوادم MCP لـ Claude Code وهذا الشرح العملي لاختبار الـ API بقيادة الوكيل قراءتين تاليتين جيدتين.

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

هل واجهة برمجة تطبيقات البحث عن الأشخاص من Treg مجانية؟ ليست مجانية بالكامل. تحصل الحسابات الموثّقة الجديدة على رصيد بقيمة 1.00 دولار مرة واحدة، وحالات عدم العثور على نتيجة لدى المزوّدين الذين يحاسبون على النجاح لا تكلف شيئًا، وبعض المسارات عامة ومجانية (فقد أدرجت خطة التحقق من البريد مزوّدًا بسعر 0 دولار في المرتبة الأولى في 3 نوفمبر 2026). وكل ما عدا ذلك يُحتسب لكل استدعاء من رصيد مدفوع مسبقًا بسعر المزوّد.

هل أحتاج إلى حساب Apollo أو Hunter لاستخدام Treg؟ لا. يستدعي Treg المزوّد من حسابه الخاص ويحاسبك على كل استدعاء. وإذا كان فريقك يدفع بالفعل لمزوّد ما، فسجّل ذلك المفتاح لدى Treg وستُستخدم تلك الاستدعاءات له دون أن تُحتسب عليك.

هل ينتقل Treg إلى مزوّد بديل عند الفشل؟ فقط في الأدوات الموجّهة treg.*. فهي تنتقل إلى المزوّد التالي عند حدوث خطأ أو عدم العثور على نتيجة، من الأرخص أولًا، ضمن حدود X-Treg-Route-Max-Cost. أما أدوات المزوّد المباشرة فلا تبدّل المزوّد نيابة عنك أبدًا.

كيف أعرف تكلفة الاستدعاء؟ اقرأ ترويسة الاستجابة X-Treg-Cost-Micro (بالميكرو-دولار)، أو cost_usd عبر MCP. ويعرض treg balance رصيدك وإنفاقك الأخير.

هل يمكنني استخدام Treg دون Claude Code أو Codex؟ نعم. استخدم أداة CLI من أي صدفة (shell)، أو استدعِ https://treg.to/call/<tool-id> عبر HTTP مع X-Treg-Token، أو صِل https://treg.to/mcp/ بـ claude.ai أو ChatGPT كموصل مخصّص.