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

مرجع API للبحث في رموز HS

ابحث في رموز النظام المنسق لإصدار واحد بمستوى 2 و4 و6 أرقام أو اعرضها حسب الاسم أو المستوى أو الأصل.

نظرة عامة

GET /v1/trade/hs-codes

يعرض GET /v1/trade/hs-codes رموز النظام المنسق (HS) لإصدار واحد. تسمّي رموز HS ما يُتاجر به: الفصل برقمين (2)، والبند بـ4 أرقام، والبند الفرعي بـ6 أرقام. تُعيد مسارات التجارة هذه الرموز، ويجد هذا المسار الرمز الذي تحتاجه.

يبحث q في الأسماء. تأتي الفصول أولًا، ثم البنود، ثم البنود الفرعية، وداخل كل مستوى يأتي أفضل تطابق أولًا. يعرض parent الرموز التابعة لرمز، ويُبقي level طولًا واحدًا. الإصدارات الأربعة هي 2007 و2012 و2017 و2022. لا تُحوَّل الإصدارات إلى بعضها أبدًا، لذلك فإن رمزًا ظهر في 2022 غير موجود في قائمة 2017. يحتوي إصدار 2022 على 96 فصلًا و1,228 بندًا و5,612 بندًا فرعيًا. أداة MCP هي trade_list_hs_codes وتأخذ المعلمات نفسها.

طلب

بحث عن «cheese» (الجبن) في إصدار 2022، الصفحة الأولى من ثلاث، والاستجابة الفعلية:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/hs-codes?q=cheese&limit=3"
الرموز المطابقة لـ«cheese»
{
  "classification": "HS",
  "edition": "2022",
  "total": 6,
  "codes": [
    {
      "code": "0406",
      "level": 4,
      "label": "Cheese and curd",
      "parent": "04"
    },
    {
      "code": "040690",
      "level": 6,
      "label": "Cheese (excl. fresh cheese, incl. whey cheese, curd, processed cheese, blue-veined cheese and other cheese containing veins produced by \"Penicillium roqueforti\", and grated or powdered cheese)",
      "parent": "0406"
    }
  ],
  "next_cursor": "eyJiIjoiaHM6MjAyMjpjaGVlc2U6Tm9uZTpOb25lOjMiLCJvIjozfQ"
}

تعرض الصفحة أول رمزين من الرموز الثلاثة. total هو 6، لذا يُضبط next_cursor. يأتي البند 0406 قبل بنده الفرعي 040690 لأن البنود تُرتَّب فوق البنود الفرعية.

المعلمات

معلمةالموضعالنوعمطلوبالافتراضيالقيم المسموح بها ومعناها
qاستعلامسلسلة نصية، من 2 إلى 100 حرفلالا شيءنص يُبحث عنه في أسماء الرموز.
editionاستعلامسلسلة نصيةلا20222007 أو 2012 أو 2017 أو 2022. أي قيمة أخرى تُعيد 400.
levelاستعلامعدد صحيحلاكل المستويات2 أو 4 أو 6. الرموز بهذا الطول فقط.
parentاستعلامسلسلة نصيةلالا شيءرمز HS من 2 أو 4 أو 6 أرقام. الرموز التابعة لهذا الرمز فقط. للفصل والبند رموز تابعة، وليس للبند الفرعي.
limitاستعلامعدد صحيحلا100من 1 إلى 1000. أكبر عدد من الرموز في صفحة واحدة.
cursorاستعلامسلسلة نصيةلالا شيءقيمة next_cursor من الصفحة السابقة، مع بقاء كل المعلمات الأخرى دون تغيير.

الاستجابة

تحتوي الإجابة على هذه الحقول.

حقلالمعنى
classificationHS.
editionإصدار القائمة.
totalعدد الرموز المتطابقة في كل الصفحات.
codesرموز هذه الصفحة. لكل منها code وlevel (2 أو 4 أو 6) وlabel (اسم الرمز بكلمات الإصدار) وparent (الرمز الأعلى بمستوى واحد، وnull للفصل).
next_cursorمؤشر الصفحة التالية. null في الصفحة الأخيرة.

أمثلة إضافية

لا تطابق

البحث الذي لا يطابق شيئًا يُعيد 200 مع قائمة فارغة، وهو مجاني:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/hs-codes?q=zzzzqqq"
لا تطابق
{
  "classification": "HS",
  "edition": "2022",
  "total": 0,
  "codes": [],
  "next_cursor": null
}

المصادر

يعرض هذا المسار الرموز ولا يحتفظ بأرقام تجارة، لذلك لا ينطبق أي مصدر.

العملة

لا يُعيد المسار قيمًا، لذلك لا تنطبق أي عملة.

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

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

السعر

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

الأخطاء

تستخدم هذه الأخطاء بنية تفاصيل الخطأ المشتركة مع request_id. المفتاح المفقود أو غير الصالح (401)، والرصيد الأقل من سعر الاستدعاء (402)، وكثرة الطلبات في الدقيقة (429) هي أخطاء الحساب التي تشترك فيها كل المسارات: راجع أخطاء API والرصيد.

الحالةالرمزمتى يحدث
400invalid_queryedition أو level أو limit خارج قيمه المسموح بها، أو q أقصر من حرفين (2)، أو parent ليس رمزًا من 2 أو 4 أو 6 أرقام.
400invalid_cursorالمؤشر ليس من المؤشرات التي أعادها هذا الطلب، أو تغيّرت معلمة أخرى منذ ذلك.

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

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