مرجع API للبحث في رموز HS
ابحث في رموز النظام المنسق لإصدار واحد بمستوى 2 و4 و6 أرقام أو اعرضها حسب الاسم أو المستوى أو الأصل.
نظرة عامة
GET /
يعرض GET / رموز النظام المنسق (HS) لإصدار واحد. تسمّي رموز HS ما يُتاجر به: الفصل برقمين (2)، والبند بـ4 أرقام، والبند الفرعي بـ6 أرقام. تُعيد مسارات التجارة هذه الرموز، ويجد هذا المسار الرمز الذي تحتاجه.
يبحث q في الأسماء. تأتي الفصول أولًا، ثم البنود، ثم البنود الفرعية، وداخل كل مستوى يأتي أفضل تطابق أولًا. يعرض parent الرموز التابعة لرمز، ويُبقي level طولًا واحدًا. الإصدارات الأربعة هي 2007 و2012 و2017 و2022. لا تُحوَّل الإصدارات إلى بعضها أبدًا، لذلك فإن رمزًا ظهر في 2022 غير موجود في قائمة 2017. يحتوي إصدار 2022 على 96 فصلًا و1,228 بندًا و5,612 بندًا فرعيًا. أداة MCP هي trade_ وتأخذ المعلمات نفسها.
طلب
بحث عن «cheese» (الجبن) في إصدار 2022، الصفحة الأولى من ثلاث، والاستجابة الفعلية:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/hs-codes?q=cheese&limit=3"{
"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_. يأتي البند 0406 قبل بنده الفرعي 040690 لأن البنود تُرتَّب فوق البنود الفرعية.
المعلمات
| معلمة | الموضع | النوع | مطلوب | الافتراضي | القيم المسموح بها ومعناها |
|---|---|---|---|---|---|
q | استعلام | سلسلة نصية، من 2 إلى 100 حرف | لا | لا شيء | نص يُبحث عنه في أسماء الرموز. |
edition | استعلام | سلسلة نصية | لا | 2022 | 2007 أو 2012 أو 2017 أو 2022. أي قيمة أخرى تُعيد 400. |
level | استعلام | عدد صحيح | لا | كل المستويات | 2 أو 4 أو 6. الرموز بهذا الطول فقط. |
parent | استعلام | سلسلة نصية | لا | لا شيء | رمز HS من 2 أو 4 أو 6 أرقام. الرموز التابعة لهذا الرمز فقط. للفصل والبند رموز تابعة، وليس للبند الفرعي. |
limit | استعلام | عدد صحيح | لا | 100 | من 1 إلى 1000. أكبر عدد من الرموز في صفحة واحدة. |
cursor | استعلام | سلسلة نصية | لا | لا شيء | قيمة next_ من الصفحة السابقة، مع بقاء كل المعلمات الأخرى دون تغيير. |
الاستجابة
تحتوي الإجابة على هذه الحقول.
| حقل | المعنى |
|---|---|
classification | HS. |
edition | إصدار القائمة. |
total | عدد الرموز المتطابقة في كل الصفحات. |
codes | رموز هذه الصفحة. لكل منها code وlevel (2 أو 4 أو 6) وlabel (اسم الرمز بكلمات الإصدار) وparent (الرمز الأعلى بمستوى واحد، وnull للفصل). |
next_ | مؤشر الصفحة التالية. 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 مع بقاء كل المعلمات الأخرى دون تغيير. المؤشر المأخوذ من طلب مختلف يُعيد 400 invalid_. يعدّ total الصفوف المتطابقة في كل الصفحات. تُعيد أداة MCP ما لا يزيد على 200 صف في نتيجة واحدة.
السعر
كل طلب يُعيد رمزًا واحدًا على الأقل هو استدعاء واحد، بسعر $2 لكل 1,000 استدعاء، وكل صفحة من قائمة طويلة استدعاء واحد. البحث الذي لا يطابق شيئًا مجاني، وكذلك كل خطأ.
الأخطاء
تستخدم هذه الأخطاء بنية تفاصيل الخطأ المشتركة مع request_. المفتاح المفقود أو غير الصالح (401)، والرصيد الأقل من سعر الاستدعاء (402)، وكثرة الطلبات في الدقيقة (429) هي أخطاء الحساب التي تشترك فيها كل المسارات: راجع أخطاء API والرصيد.
| الحالة | الرمز | متى يحدث |
|---|---|---|
400 | invalid_query | edition أو level أو limit خارج قيمه المسموح بها، أو q أقصر من حرفين (2)، أو parent ليس رمزًا من 2 أو 4 أو 6 أرقام. |
400 | invalid_cursor | المؤشر ليس من المؤشرات التي أعادها هذا الطلب، أو تغيّرت معلمة أخرى منذ ذلك. |
هل كانت هذه الصفحة مفيدة؟