جستجوی شناسهی کالا و خدمات مودیان، داخل نرمافزار خودتان
۴٫۲ میلیون شناسهی رسمی و معتبر stuffid با نرخ مالیات، نوع و منشأ — جستجو از ۲ حرف، پاسخ معمولاً زیر ۱۰۰ میلیثانیه. بدون نگهداری فایلهای چندگیگی و بهروزرسانیشان.
۲۰ جستجوی رایگان در هر ماه — بدون کارت بانکی
{
"ok": true,
"query": "لپ تاپ",
"count": 1,
"items": [
{
"code": "2710000101482",
"title": "لپ تاپ (نوت بوک)",
"vat_rate": 10,
"taxable": "taxable",
"type": "general",
"origin": "import",
"expires_at": null
}
]
}
۱. شروع سریع
- ثبتنام کنید و از منوی پنل به «API توسعهدهندگان» بروید.
- یک کلید بسازید و همان لحظه کپی کنید (دوباره نمایش داده نمیشود).
- کلید را در هدر
Authorization: Bearer ...بفرستید.
۲. سرویسها
GET https://fintaco.ir/api/v1/stuff-codes/search
جستجو با نام کالا/خدمت یا چند رقم اول شناسه. شناسههای عمومی اول میآیند.
| پارامتر | توضیح |
|---|---|
| q | عبارت جستجو؛ حداقل ۲ نویسه (مثلاً «لپ تاپ» یا «2710») |
| limit | تعداد نتیجه، ۱ تا ۵۰ (پیشفرض ۲۰) |
GET https://fintaco.ir/api/v1/stuff-codes/{code}
اطلاعات یک شناسهی ۱۳ رقمی؛ برای بررسی معتبر بودن شناسه و نرخ مالیات پیش از ارسال فاکتور. اگر نباشد found: false برمیگردد.
۳. نمونهکد
curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://fintaco.ir/api/v1/stuff-codes/search?q=%D9%84%D9%BE%20%D8%AA%D8%A7%D9%BE&limit=10"
$ch = curl_init('https://fintaco.ir/api/v1/stuff-codes/search?' . http_build_query(['q' => 'لپ تاپ', 'limit' => 10]));
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('FINTACO_API_KEY')],
]);
$result = json_decode(curl_exec($ch), true);
foreach ($result['items'] as $item) {
echo $item['code'], ' — ', $item['title'], ' (', $item['vat_rate'], "%)\n";
}
import os, requests
r = requests.get(
'https://fintaco.ir/api/v1/stuff-codes/search',
params={'q': 'لپ تاپ', 'limit': 10},
headers={'Authorization': f"Bearer {os.environ['FINTACO_API_KEY']}"},
timeout=10,
)
for item in r.json()['items']:
print(item['code'], item['title'], item['vat_rate'])
const url = new URL('https://fintaco.ir/api/v1/stuff-codes/search');
url.search = new URLSearchParams({ q: 'لپ تاپ', limit: 10 });
const res = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.FINTACO_API_KEY}` },
});
const { items } = await res.json();
items.forEach((i) => console.log(i.code, i.title, i.vat_rate));
۴. فیلدهای پاسخ
| فیلد | توضیح |
|---|---|
| code | شناسهی ۱۳ رقمی |
| title | شرح رسمی کالا/خدمت |
| vat_rate | نرخ مالیات بر ارزش افزوده (درصد)؛ همان نرخی که سامانه مودیان بررسی میکند |
| taxable | taxable مشمول، exempt معاف، not_taxable غیر مشمول |
| type | general شناسهی عمومی، specific شناسهی اختصاصی |
| origin | domestic تولید داخل، import وارداتی، service خدمت |
| expires_at | تاریخ انقضا (شمسی) یا null؛ شناسههای منقضی برگردانده نمیشوند |
۵. سهمیه، سرعت و خطاها
هر پاسخ موفق یک جستجو از سهمیه کم میکند؛ خطای ورودی یا خطای سمت ما حساب نمیشود. وضعیت سهمیه در هدرهای هر پاسخ میآید:
X-Quota-Limit: 5000 X-Quota-Remaining: 4987 X-Quota-Reset: 2026-11-14T10:00:00+03:30 X-RateLimit-Limit: 60 X-RateLimit-Remaining: 59
| کد HTTP | error.code | معنی |
|---|---|---|
| 401 | invalid_key | کلید نامعتبر یا باطلشده |
| 402 | quota_exceeded | سهمیهی این دوره تمام شده |
| 422 | invalid_query | پارامترها نادرستاند |
| 429 | rate_limited | بیش از سقف درخواست در دقیقه (هدر Retry-After) |
| 503 | unavailable | سرویس موقتاً در دسترس نیست |
ساده و قابل پیشبینی
۲۰ جستجوی رایگان در هر ماه برای همه — خرید سالانه با تخفیف
رایگان
۰
۲۰ جستجو در ماه
سقف ۱۰ در دقیقه
پایه
۳٬۰۰۰٬۰۰۰ ریال / ماه
۵٬۰۰۰ جستجو در ماه
هر جستجو ۶۰۰ ریال — سقف ۶۰ در دقیقه
سالانه: ۳۰٬۰۰۰٬۰۰۰ ریال — ۱۷٪ تخفیف
حرفهای
۹٬۰۰۰٬۰۰۰ ریال / ماه
۵۰٬۰۰۰ جستجو در ماه
هر جستجو ۱۸۰ ریال — سقف ۱۲۰ در دقیقه
سالانه: ۹۰٬۰۰۰٬۰۰۰ ریال — ۱۷٪ تخفیف
سازمانی
۲۵٬۰۰۰٬۰۰۰ ریال / ماه
۵۰۰٬۰۰۰ جستجو در ماه
هر جستجو ۵۰ ریال — سقف ۳۰۰ در دقیقه
سالانه: ۲۵۰٬۰۰۰٬۰۰۰ ریال — ۱۷٪ تخفیف
سهمیه زودتر تمام شد؟ بستهی ۱٬۰۰۰ جستجوی اضافه به ۶۰۰٬۰۰۰ ریال تا پایان همان دوره.