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

مرجع API لتجارة منتج واحد

اقرأ صادرات دولة ووارداتها من رمز HS واحد مع كل شريك، صفًا لكل شريك وشهر واتجاه، مع اسم الرمز.

نظرة عامة

GET /v1/trade/{country}/products/{hs}

يُعيد GET /v1/trade/{country}/products/{hs} تجارة دولة واحدة في رمز HS واحد مع كل شريك: صف لكل شريك وشهر واتجاه، واسم الرمز. hs رمز من 2 أو 4 أو 6 أرقام.

استخدمه لمعرفة أي الشركاء يشترون منتجًا أو يبيعونه. يقبل الخيارات نفسها التي يقبلها مسار الشركاء، وطلب الشركاء مع hs يُعيد الأرقام نفسها.

الرمز الذي لا يوجد في إصدار HS يُعيد 404 hs_code_not_found. أداة MCP هي trade_get_product وتأخذ المعلمات نفسها.

طلب

البند 8517 (أجهزة الهاتف وغيرها من الأجهزة لإرسال البيانات واستقبالها) للمملكة المتحدة مع الولايات المتحدة في يونيو 2026، والاستجابة الفعلية:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/GBR/products/8517?partner=USA&start=2026-06&end=2026-06"
المملكة المتحدة، البند 8517، مع الولايات المتحدة
{
  "country": "GBR",
  "basis": "own",
  "source": "HM Revenue & Customs",
  "reporters_included": null,
  "note": null,
  "coverage": "full",
  "partner_coverage": "all",
  "scope": "goods",
  "currency": "GBP",
  "classification": "HS",
  "edition": "2022",
  "edition_basis": "inferred_from_year",
  "valuation_basis": "not_stated",
  "trade_system": "not_stated",
  "partner_basis": "not_stated",
  "trade_scope": "all_partners",
  "latest_period": "2026-09",
  "total_basis": "customs",
  "totals": [
    {
      "period": "2026-06",
      "flow": "export",
      "official_total": null,
      "sum_of_rows": "46135455"
    },
    {
      "period": "2026-06",
      "flow": "import",
      "official_total": null,
      "sum_of_rows": "89090099"
    }
  ],
  "fx": null,
  "calculated": [
    "sum_of_rows"
  ],
  "total": 2,
  "product_code": "8517",
  "product_level": 4,
  "product_label": "Telephone sets, incl. telephones for cellular networks or for other wireless networks; other apparatus for the transmission or reception of voice, images or other data, incl. apparatus for communication in a wired or wireless network [such as a local or wide area network]; parts thereof (excl. than transmission or reception apparatus of heading 8443, 8525, 8527 or 8528)",
  "rows": [
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "46135455",
      "net_weight_kg": "74435",
      "rank": null,
      "share": null,
      "change": null,
      "partner": "USA",
      "partner_label": "United States",
      "partner_kind": "country",
      "unallocated_reason": null
    },
    {
      "flow": "import",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "89090099",
      "net_weight_kg": "246068",
      "rank": null,
      "share": null,
      "change": null,
      "partner": "USA",
      "partner_label": "United States",
      "partner_kind": "country",
      "unallocated_reason": null
    }
  ],
  "next_cursor": null
}

يوجد صف واحد لكل اتجاه. تحتوي totals على إجمالي البند 8517 مع الولايات المتحدة، وهو مجموع الصفين، ويكون official_total null لأن الناشر لا يطبع إجماليًا لمنتج واحد.

المعلمات

معلمةالموضعالنوعمطلوبالافتراضيالقيم المسموح بها ومعناها
countryمسارسلسلة نصيةنعملا شيءرمز ISO 3166-1 alpha-3 للدولة المُبلِّغة، بأحرف كبيرة، مثل GBR. الرمز الذي لا يعود لدولة يُعيد 400. الدولة التي لا أرقام لها تُعيد 404 country_not_covered.
hsمسارسلسلة نصيةنعملا شيءرمز HS من 2 أو 4 أو 6 أرقام، مثل 85 أو 8517 أو 851713. أي طول آخر يُعيد 400. الرمز الذي لا اسم له في إصدار HS ولا صفوف له للدولة يُعيد 404 hs_code_not_found. بيانات تايلاند محفوظة بـ 4 أرقام، لذا يُعيد رمز من 6 أرقام لتايلاند 404 basis_not_available.
partnerاستعلامسلسلة نصيةلاكل الشركاءرمز ISO 3166-1 alpha-3 لشريك واحد، بأحرف كبيرة. الرمز الذي ليس شريكًا للدولة يُعيد 400 unknown_partner.
flowاستعلامسلسلة نصيةلاالاتجاهانexport أو import.
startاستعلامسلسلة نصية، YYYY-MMلاأحدث شهر محفوظأول شهر، شاملًا. مع start ومن دون end تمتد الإجابة إلى أحدث شهر محفوظ. start بعد end يُعيد 400.
endاستعلامسلسلة نصية، YYYY-MMلاأحدث شهر محفوظآخر شهر، شاملًا. مع end وحده تكون الإجابة أحدث شهر محفوظ في ذلك التاريخ أو قبله.
basisاستعلامسلسلة نصيةلاأفضل مصدر محفوظown أو third_party أو partner_reported. يطلب مصدرًا واحدًا بالاسم ويتخطى الترتيب. المصدر الذي لا يحتفظ بشيء للسؤال يُعيد 404 basis_not_available.
currencyاستعلامسلسلة نصيةلاعملة المصدر نفسهUSD. يحوّل كل شهر بمتوسط سعره اليومي.
topاستعلامعدد صحيحلاكل الصفوفمن 1 إلى 1000. يُبقي N من أكبر صفوف الدول في كل شهر واتجاه، مرتبة بالقيمة وتُفَضّ حالات التعادل برمز الشريك، ويضيف rank إلى كل صف. لا تُرتَّب صفوف المجموعات والصفوف غير المخصصة. محسوب. يغطي 12 شهرًا على الأكثر. لا يصلح لإجابات تقارير الشركاء.
shareاستعلاممنطقيلاfalsetrue يضيف share إلى كل صف: قيمته مقسومة على مجموع صفوف الدول في الشهر والاتجاه نفسيهما، ككسر من 1 بـ6 منازل عشرية. محسوب. يغطي 12 شهرًا على الأكثر. لا يصلح لإجابات تقارير الشركاء.
ytdاستعلاممنطقيلاfalsetrue يجمع من يناير إلى end (الافتراضي: أحدث شهر) من الأشهر المخزّنة، ويكون period_type هو year_to_date. أرسل end وليس start: مع start يُعيد الطلب 400. الشهر المفقود يُعيد 404 period_not_published. محسوب. لا يصلح لإجابات تقارير الشركاء.
changeاستعلاممنطقيلاfalsetrue يضيف change إلى كل صف: الشهر نفسه (أو منذ بداية العام) قبل سنة، مع الفرق وحالة الإصدار للطرفين. الشهر المفقود قبل سنة يُعيد 404 period_not_published. محسوب. يغطي 12 شهرًا على الأكثر. لا يصلح لإجابات تقارير الشركاء.
include_groupsاستعلاممنطقيلاfalsetrue يُعيد أيضًا صفوف المجموعات التي ينشرها الناشر، مثل الاتحاد الأوروبي أو ASEAN. لا يدخل صف المجموعة أبدًا في مجموع أو ترتيب أو حصة.
limitاستعلامعدد صحيحلا500من 1 إلى 1000. أكبر عدد من الصفوف في صفحة واحدة.
cursorاستعلامسلسلة نصيةلالا شيءقيمة next_cursor من الصفحة السابقة، مع بقاء كل المعلمات الأخرى دون تغيير.

الاستجابة

تحتوي الإجابة على حقول مسار الشركاء، المسرودة في تلك الصفحة، وعلى هذه الحقول الثلاثة عن المنتج. تحتوي totals على إجمالي ذلك المنتج، أي مجموع صفوفه في كل الصفحات، مع official_total null.

حقلالمعنى
product_codeرمز HS المطلوب.
product_level2 للفصل، و4 للبند، و6 للبند الفرعي.
product_labelاسم الرمز. null لسطر ليس منتج HS، مثل الرمز المتبقي 999999 الخاص بالناشر في تشيلي، وهو يُجيب مع صفوفه.

كل عنصر في rows هو شريك واحد في شهر واتجاه واحد، بالحقول نفسها كما في مسار الشركاء.

حقلالمعنى
flowexport أو import.
periodالشهر، YYYY-MM. ومنذ بداية العام، آخر شهر فيه.
period_typemonth أو year_to_date.
period_start, period_endأول يوم وآخر يوم يغطيهما الصف، YYYY-MM-DD.
valueوحدات كاملة من currency، كسلسلة عشرية.
net_weight_kgالوزن الصافي بالكيلوغرام، كسلسلة عشرية، حيث يقدّمه الناشر. null خلاف ذلك.
rankمع top: ترتيب الصف، 1 للأكبر. null خلاف ذلك.
shareمع share: حصة الصف من الإجمالي ككسر، بـ6 منازل عشرية. null خلاف ذلك.
changeمع change: كائن يحتوي على previous_period وprevious_value وabsolute (القيمة ناقص القيمة السابقة) وpercent (بالنسبة المئوية بـ4 منازل عشرية، وnull عندما كانت القيمة السابقة 0) وrelease_status وprevious_release_status (preliminary أو revised أو final، أو null عندما لا يذكر الناشر ذلك). null عندما لا يوجد الصف قبل سنة أو لم يُطلب change.
partnerرمز ISO 3166-1 alpha-3 للشريك، أو رمز مجموعة مثل EUU، أو فارغ لسطر لا دولة له.
partner_labelاسم الشريك كما يستخدمه الناشر نفسه.
partner_kindcountry أو group أو unallocated.
unallocated_reasonلصف غير مخصص: not_specified أو confidential أو stores_bunkers أو free_zone أو other أو rest. null خلاف ذلك.

أمثلة إضافية

رمز لا يوجد في الإصدار

رمز HS بلا اسم وبلا صفوف يُعيد 404 وهو مجاني:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/GBR/products/999999?start=2026-06&end=2026-06&flow=export&limit=3"
المملكة المتحدة، الرمز 999999
{
  "type": "https://narwhalapi.com/problems/hs-code-not-found",
  "title": "HS code not found",
  "status": 404,
  "detail": "HS 2022 has no code 999999.",
  "code": "hs_code_not_found",
  "request_id": "16a6db4e-d5d6-45ee-954b-4512cf137e63"
}

المصادر

يُجيب مصدر واحد عن كل طلب، وهو أول مصدر لديه صفوف بهذا الترتيب: مكتب الجمارك أو الإحصاء التابع للدولة نفسها (basis هو own)، ثم إيداع الدولة نفسها لدى UN Comtrade (third_party، إجماليات الشركاء فقط)، ثم تقارير الدول الأخرى عنها مع تبديل الاتجاهين (partner_reported). كانت تقارير الدول الأخرى ستسبق UN Comtrade فقط عندما يكون لدى 200 دولة مُبلِّغة على الأقل صفوف عن الدولة، وهو أكثر مما تحتفظ به Narwhal، لذلك تأتي أخيرًا. بحسب المنتج لا تحتفظ UN Comtrade بشيء، فيكون الترتيب own ثم partner_reported، ولا تصل partner_reported إلا إلى الفصول (من رقمين، 2). يطلب basis مصدرًا واحدًا بالاسم. تبيّن الحقول basis وsource وnote في الإجابة أي مصدر أجاب، ولا تُخلط المصادر أبدًا في إجابة واحدة. إجابة تقارير الشركاء قياس مختلف عن أرقام الدولة نفسها، وليست رقمًا رسميًا أبدًا. تصل إجابات تقارير الشركاء إلى الفصول فقط، لذلك يُعيد الرمز من 4 أو 6 أرقام 404 basis_not_available للدولة التي لا يقدّم مكتبها إلا إجماليات الشركاء.

العملة

القيم وحدات كاملة من العملة المذكورة في currency، مكتوبة كسلاسل عشرية. افتراضيًا تكون عملة النشر الخاصة بالمصدر، مثل GBP لهيئة الإيرادات والجمارك البريطانية (HM Revenue & Customs). يحوّل currency=USD كل شهر بمتوسط أسعار الصرف اليومية لذلك الشهر. يُسرد السعر المستخدم لكل شهر في fx، ويسمّي calculated الحقول المحوَّلة. الشهر بلا سعر يُعيد 404 rate_not_available. وإذا تعذّرت الإجابة من مصدر الأسعار يُعيد الطلب 503 upstream_unavailable. الإجابة التي هي بـUSD أصلًا تعود كما هي.

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

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

السعر

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

الأخطاء

تستخدم هذه الأخطاء بنية تفاصيل الخطأ المشتركة مع request_id. المفتاح المفقود أو غير الصالح (401)، والرصيد الأقل من سعر الاستدعاء (402)، وكثرة الطلبات في الدقيقة (429) هي أخطاء الحساب التي تشترك فيها كل المسارات: راجع أخطاء 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.
404country_not_coveredلا تحتفظ Narwhal بأي صفوف تجارة للدولة في أي مصدر.
404period_not_publishedالشهر المطلوب غير محفوظ (No trade rows for 2026-10.)، أو ينقص شهر يحتاجه ytd أو change.
404basis_not_availableالمصدر المطلوب، أو كل مصدر في الترتيب، لا يحتفظ بشيء للسؤال. يذكر detail السبب: مثلًا أن مكتب الدولة نفسها يوفر إجماليات الشركاء فقط دون المنتجات، أو أن إجابات تقارير الشركاء تصل إلى الفصول (من رقمين، 2) فقط، أو أن بيانات مكتب تايلاند نفسها محفوظة بـ 4 أرقام وطُلبت بـ 6. راجع مسار التغطية.
404hs_code_not_foundإصدار HS لا يحتوي على اسم للرمز، ولا تحتفظ الدولة بصفوف له، مثلًا المملكة المتحدة والرمز 999999 تُجيبان HS 2022 has no code 999999. الرمز الذي لا اسم له لكن ملفات الدولة تحتفظ به (سطور الناشر المتبقية) يُعيد 200 مع product_label null.
404rate_not_availableطُلب currency=USD ولا يوجد سعر صرف لأحد الأشهر.
503upstream_unavailableمصدر أسعار الصرف لا يستطيع الإجابة. يؤثر ذلك في currency=USD وفي إجابات تقارير الشركاء التي تحتاج إلى تحويل. حاول مرة أخرى بعد قليل.
503trade_data_unavailableتعذّرت قراءة ملفات المنتجات الآن. حاول مرة أخرى بعد قليل.

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

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