تصفّح التوثيق كاملًا

مرجع واجهة API للتجارة

اقرأ تجارة السلع حسب الدولة الشريكة وحسب منتج HS، شهرًا بشهر، من مكتب الجمارك أو الإحصاء في كل دولة تحتفظ Narwhal ببيانات مكتبها، ومن UN Comtrade أو من تقارير الدول الأخرى لبقية الدول.

نظرة عامة

تُعيد واجهة API للتجارة تجارة السلع حسب الدولة الشريكة وحسب المنتج، شهرًا واحدًا في كل مرة. الصف الواحد هو اتجاه واحد، تصدير أو استيراد، في شهر واحد، مع شريك أو منتج وقيمة بوحدات كاملة من عملة ما. تتبع المنتجات النظام المنسق (HS) بمستويات 2 و4 و6 أرقام. يبدأ السجل التاريخي في يناير 2010 حيث ينشره المصدر. تغطي الواجهة السلع فقط.

تأتي الأرقام من مكتب الجمارك أو الإحصاء في الدولة المُبلِّغة حيث تحتفظ Narwhal ببياناته، ومن UN Comtrade أو تقارير الدول الأخرى لبقية الدول الـ181 في قائمة التغطية. تذكر كل إجابة المصدر الذي أنتجها. تجد أي الدول تُجيب من أي مصدر في صفحة دول التجارة.

تُجيب سبعة مسارات، كلها تحت /v1/trade، وكل مسار منها أداة MCP أيضًا بالمعلمات نفسها والإجابة نفسها. يأخذ كل طلب المفتاح في ترويسة Authorization: Bearer، كما في بقية Narwhal.

المسارات

المسارأداة MCPما يُجيب عنه
GET /v1/trade/{country}/partnerstrade_get_partnersصادرات وواردات دولة واحدة حسب الشريك.
GET /v1/trade/{country}/productstrade_get_productsصادرات وواردات دولة واحدة حسب منتج HS، بمستوى 2 أو 4 أو 6 أرقام.
GET /v1/trade/{country}/products/{hs}trade_get_productتجارة دولة واحدة في رمز HS واحد مع كل شريك.
GET /v1/trade/flowstrade_get_flowsاستعلام مفتوح عبر عدة دول مُبلِّغة وشركاء وفصول.
GET /v1/trade/coveragetrade_get_coverageأي مصدر يُجيب عن كل دولة، والأشهر المحفوظة. مجاني.
GET /v1/trade/hs-codestrade_list_hs_codesابحث في رموز HS أو اعرضها حسب الاسم أو المستوى أو الأصل.
GET /v1/trade/hs-codes/{code}trade_get_hs_codeرمز HS واحد مع أصله والرموز التابعة له.

لكل مسار صفحته الخاصة التي تعرض كل معلمة، وطلبًا يعمل مع استجابته الفعلية، وكل خطأ.

المصادر

تأتي كل إجابة من مصدر واحد، يُذكر في basis وsource. الطلب بلا basis يأخذ أول مصدر بهذا الترتيب يحتوي على صفوف. لا تُخلط المصادر أبدًا في إجابة واحدة، ويطلب basis مصدرًا واحدًا بالاسم.

basisالمصدرما هويصل إلى
ownمكتب الجمارك أو الإحصاء التابع للدولة نفسهاأرقام المكتب نفسه، بعملته هو، كما نشرها.الشركاء، والمنتجات بمستويات 2 و4 و6 أرقام حيث يوفرها المكتب
third_partyUN Comtradeالإيداع الشهري للدولة نفسها لدى الأمم المتحدة، يُقدَّم مع ذكر المصدر.إجماليات الشركاء فقط
partner_reportedتقارير الجمارك في الدول الأخرىما تُبلِّغ به الدول الأخرى عن الدولة، مع تبديل الاتجاهين: واردات الدول الأخرى منها هي صادراتها. قياس مختلف، وليس رقمًا رسميًا أبدًا.الشركاء، والمنتجات من رقمين (2)

كانت تقارير الدول الأخرى ستسبق UN Comtrade فقط عندما يكون لدى 200 دولة مُبلِّغة على الأقل صفوف عن الدولة، وهو أكثر مما تحتفظ به Narwhal، لذلك تأتي أخيرًا. بحسب المنتج لا تحتفظ UN Comtrade بشيء، فيكون الترتيب own ثم partner_reported. إجابة تقارير الشركاء لا إجمالي رسمي لها، ولا تقبل top أو share أو ytd أو change، وتغطي 12 شهرًا على الأكثر. يعرض GET /v1/trade/coverage الحقل answers_with، وهو المصدر الذي يُجيب عن كل دولة اليوم.

أي دولة تُجيب من أي مصدر: دول التجارة.

العملة

القيم وحدات كاملة من العملة المذكورة في currency، كسلاسل عشرية. افتراضيًا تكون عملة النشر الخاصة بالمصدر. يحوّل currency=USD كل شهر بمتوسط أسعار الصرف اليومية لذلك الشهر، ويسرد السعر المستخدم لكل شهر في fx، ويسمّي الحقول المحوَّلة في calculated. يذكر مسار الاستعلام المفتوح العملة في كل صف، لأن الدول المُبلِّغة تنشر بعملات مختلفة.

التصفح بالصفحات

يحدد limit أكبر عدد من الصفوف في صفحة واحدة، من 1 إلى 1000. قيمته الافتراضية 500 في مسارات الشركاء والمنتجات والمنتج الواحد والاستعلام المفتوح، و100 في GET /v1/trade/hs-codes. عندما تتطابق صفوف أكثر، يحمل next_cursor مؤشر الصفحة التالية: أرسله كـcursor مع بقاء كل المعلمات الأخرى دون تغيير. المؤشر المأخوذ من طلب مختلف يُعيد 400 invalid_cursor. يعدّ total الصفوف المتطابقة في كل الصفحات. تُعيد أداة MCP ما لا يزيد على 200 صف في نتيجة واحدة.

السعر

تكلّف استدعاءات التجارة $2 لكل 1,000 استدعاء. الطلب الذي يُعيد صفًا واحدًا على الأقل يُحتسب استدعاءً واحدًا، وكل صفحة من إجابة طويلة تُحتسب استدعاءً واحدًا. الإجابة بلا صفوف مجانية، وكل خطأ مجاني، ومسار التغطية مجاني. راجع الأسعار لمعرفة الرصيد وعمليات الشحن.

الأخطاء

تستخدم الأخطاء بنية تفاصيل الخطأ المشتركة مع request_id. تسرد صفحة كل مسار الأخطاء التي يمكن أن يُعيدها. هذه هي الأخطاء كلها.

الحالةالرمزمتى يحدث
401, 402, 429unauthorized, insufficient_credits, rate_limitedمفتاح مفقود أو غير صالح، أو رصيد أقل من سعر الاستدعاء، أو كثرة الطلبات في الدقيقة. راجع أخطاء API والرصيد.
400invalid_queryمعلمة مفقودة أو بصيغة خاطئة أو خارج قيمها المسموح بها: مثل start=2026-13، أو start بعد end، أو إرسال ytd مع start، أو إرسال as_of أو version (تقدّم هذه المسارات ما هو محفوظ الآن). وكذلك عندما يُطلب top أو share أو ytd أو change من إجابة تقارير الشركاء.
400invalid_cursorالمؤشر ليس من المؤشرات التي أعادها هذا الطلب، أو تغيّرت معلمة أخرى منذ ذلك.
400unknown_partnerpartner ليس شريكًا للدولة في الأشهر المطلوبة، مثلًا ZZZ is not a partner of GBR.
400range_too_largeيغطي top أو share أو ytd أو change أكثر من 12 شهرًا، أو تغطي إجابة تقارير الشركاء أكثر من 12 شهرًا، أو تغطي إجابة المنتجات، بأي مستوى (2 أو 4 أو 6 أرقام)، أكثر من 12 شهرًا محفوظة من دون hs أو partner. يرفض الاستعلام المفتوح نافذة تتجاوز 12 شهرًا بالرمز invalid_query.
404hs_code_not_foundلا يوجد هذا الرمز في إصدار HS.
404country_not_coveredلا تحتفظ Narwhal بأي صفوف تجارة للدولة في أي مصدر.
404period_not_publishedالشهر المطلوب غير محفوظ (No trade rows for 2026-10.)، أو ينقص شهر يحتاجه ytd أو change.
404basis_not_availableالمصدر المطلوب، أو كل مصدر في الترتيب، لا يحتفظ بشيء للسؤال. يذكر detail السبب: مثلًا أن مكتب الدولة نفسها يوفر إجماليات الشركاء فقط دون المنتجات، أو أن إجابات تقارير الشركاء تصل إلى الفصول (من رقمين، 2) فقط، أو أن بيانات مكتب تايلاند نفسها محفوظة بـ 4 أرقام وطُلبت بـ 6. راجع مسار التغطية.
404rate_not_availableطُلب currency=USD ولا يوجد سعر صرف لأحد الأشهر.
503upstream_unavailableمصدر أسعار الصرف لا يستطيع الإجابة. يؤثر ذلك في currency=USD وفي إجابات تقارير الشركاء التي تحتاج إلى تحويل. حاول مرة أخرى بعد قليل.
503trade_data_unavailableتعذّرت قراءة ملفات المنتجات الآن. حاول مرة أخرى بعد قليل.

أخطاء API والرصيد · مرجع واجهة API للتجارة · دول التجارة

أدوات MCP

كل مسار هو أداة MCP قائمة بذاتها، بالمعلمات نفسها والإجابة نفسها. تُعيد أداة MCP ما لا يزيد على 200 صف في نتيجة واحدة، لذلك تنقّل بين الصفحات باستخدام cursor. الأدوات هي:

trade_list_hs_codestrade_get_hs_codetrade_get_coveragetrade_get_partnerstrade_get_productstrade_get_producttrade_get_flows

هل كانت هذه الصفحة مفيدة؟