سامانه فینتاکو فینتاکو
جستجوی شناسه کالا ویژگی‌ها تعرفه‌ها سؤالات متداول راهنما و مقالات API برنامه‌نویس‌ها درباره ما ساخت کلید و گواهی رایگان
API برای برنامه‌نویس‌ها

جستجوی شناسه‌ی کالا و خدمات مودیان، داخل نرم‌افزار خودتان

۴٫۲ میلیون شناسه‌ی رسمی و معتبر stuffid با نرخ مالیات، نوع و منشأ — جستجو از ۲ حرف، پاسخ معمولاً زیر ۱۰۰ میلی‌ثانیه. بدون نگهداری فایل‌های چندگیگی و به‌روزرسانی‌شان.

۲۰ جستجوی رایگان در هر ماه — بدون کارت بانکی

{
    "ok": true,
    "query": "لپ تاپ",
    "count": 1,
    "items": [
        {
            "code": "2710000101482",
            "title": "لپ تاپ (نوت بوک)",
            "vat_rate": 10,
            "taxable": "taxable",
            "type": "general",
            "origin": "import",
            "expires_at": null
        }
    ]
}

۱. شروع سریع

  1. ثبت‌نام کنید و از منوی پنل به «API توسعه‌دهندگان» بروید.
  2. یک کلید بسازید و همان لحظه کپی کنید (دوباره نمایش داده نمی‌شود).
  3. کلید را در هدر 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نرخ مالیات بر ارزش افزوده (درصد)؛ همان نرخی که سامانه مودیان بررسی می‌کند
taxabletaxable مشمول، exempt معاف، not_taxable غیر مشمول
typegeneral شناسه‌ی عمومی، specific شناسه‌ی اختصاصی
origindomestic تولید داخل، 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
کد HTTPerror.codeمعنی
401invalid_keyکلید نامعتبر یا باطل‌شده
402quota_exceededسهمیه‌ی این دوره تمام شده
422invalid_queryپارامترها نادرست‌اند
429rate_limitedبیش از سقف درخواست در دقیقه (هدر Retry-After)
503unavailableسرویس موقتاً در دسترس نیست
تعرفه‌ی API

ساده و قابل پیش‌بینی

۲۰ جستجوی رایگان در هر ماه برای همه — خرید سالانه با تخفیف

رایگان

۰

۲۰ جستجو در ماه

سقف ۱۰ در دقیقه

پایه

۳٬۰۰۰٬۰۰۰ ریال / ماه

۵٬۰۰۰ جستجو در ماه

هر جستجو ۶۰۰ ریال — سقف ۶۰ در دقیقه

سالانه: ۳۰٬۰۰۰٬۰۰۰ ریال — ۱۷٪ تخفیف

پیشنهادی

حرفه‌ای

۹٬۰۰۰٬۰۰۰ ریال / ماه

۵۰٬۰۰۰ جستجو در ماه

هر جستجو ۱۸۰ ریال — سقف ۱۲۰ در دقیقه

سالانه: ۹۰٬۰۰۰٬۰۰۰ ریال — ۱۷٪ تخفیف

سازمانی

۲۵٬۰۰۰٬۰۰۰ ریال / ماه

۵۰۰٬۰۰۰ جستجو در ماه

هر جستجو ۵۰ ریال — سقف ۳۰۰ در دقیقه

سالانه: ۲۵۰٬۰۰۰٬۰۰۰ ریال — ۱۷٪ تخفیف

سهمیه زودتر تمام شد؟ بسته‌ی ۱٬۰۰۰ جستجوی اضافه به ۶۰۰٬۰۰۰ ریال تا پایان همان دوره.