آیا میتوانم بدون کلید از API استفاده کنم؟

بله، تمام نقاط پایانی داده (آگهیها، شرکتها، اشخاص، فهرست، آمار) بدون کلید باز هستند. کلید فقط برای نقاط پایانی Pro و Enterprise مستند شده لازم است.

چگونه کلید API خود را ارسال کنم؟

در هدر X-API-Key با مقدار sk_bodacc_... یا در Authorization با Bearer sk_bodacc_... یک کلید نامعتبر یا لغو شده، خطای 401 برمیگرداند.

در صورت دریافت خطای 429 چه کنم؟

قبل از تلاش مجدد، به هدر Retry-After پاسخ احترام بگذارید. سهمیه بدون کلید 60 درخواست در دقیقه و 10 000 در روز است. با کلید، 600 در دقیقه و 100 000 در روز.

چرا صفحهبندی محدود است؟

برای جلوگیری از تخلیه کامل پایگاه داده: limit حداکثر 500، offset حداکثر 10 000 و فهرست حداکثر 200 صفحه 100 تایی است. برای مرور نتایج، روی offset تکرار کنید.

API BODACC : احراز هویت و محدودیت‌ها : BODACC.io

دسترسی عمومی رایگان

API BODACC بدون کلید در تمام نقاط پایانی داده باز است: آگهی‌ها، شرکت‌ها، اشخاص، فهرست راهنما، آمار. می‌توانید بلافاصله داده‌های عمومی را جستجو کنید:

curl "https://bodacc.io/api/bodacc/annonces?q=boulangerie&limit=5"

دریافت کلید API

پیشنهادهای Pro و Enterprise کلیدهای API (با پیشوند sk_bodacc_) را از بخش حساب من ← API (/{locale}/mon-compte/api) فراهم می‌کنند. کلید دسترسی به نقاط پایانی مستند شده‌ای را که به آن نیاز دارند باز می‌کند.

ارسال کلید

دو هدر پذیرفته شده:

# هدر X-API-Key
curl "https://bodacc.io/api/bodacc/annonces?q=boulangerie" \
  -H "X-API-Key: sk_bodacc_..."

# یا Authorization Bearer
curl "https://bodacc.io/api/bodacc/annonces?q=boulangerie" \
  -H "Authorization: Bearer sk_bodacc_..."

یک کلید نامعتبر یا لغو شده کد 401 را با بدنه JSON صریح برمی‌گرداند. عدم وجود کلید دسترسی عمومی را باز می‌گذارد (بدون خطا).

کدهای خطا

کد	معنی
`400`	پارامتر نامعتبر (مثلاً نقش ناشناخته فهرست راهنما)
`401`	کلید API نامعتبر یا لغو شده
`404`	منبع یافت نشد (آگهی، SIREN، شخص)
`429`	تعداد درخواست‌ها بیش از حد یا سهمیه تکمیل شده — به `Retry-After` احترام بگذارید

محدودیت‌ها و بهترین روش‌ها

محدودیت نرخ : 60 درخواست در دقیقه به ازای هر IP بدون کلید، 600 با کلید معتبر
سهمیه روزانه : 10,000 درخواست در روز به ازای هر IP بدون کلید، 100,000 با کلید — این کار از تکرار سیستماتیک فیلترها (استخراج کامل پایگاه داده) جلوگیری می‌کند؛ شمارنده هر روز بازنشانی می‌شود
محدودیت‌های ضد-استخراج : limit ≤ 500، offset ≤ 10,000 برای آگهی‌ها/شرکت‌ها/دفاتر؛ فهرست راهنما و بازیگران به 200 صفحه از 100 محدود شده‌اند
صفحه‌بندی سیستماتیک : به جای درخواست حجم‌های بزرگ، روی offset (یا page/per_page برای فهرست راهنما) تکرار کنید
Retry-After : در 429، قبل از تلاش مجدد مدت زمان مشخص شده را صبر کنید
مجموع‌ها : برای داشبوردها به جای COUNT(*) از stats/counts و stats/daily (مادی‌سازی شده) استفاده کنید
داده‌های زمان واقعی : داده‌ها پس از هر انتشار BODACC به‌روزرسانی می‌شوند
حافظه پنهان : جستجوهای رایج توسط حافظه پنهان لبه Cloudflare (300 ثانیه) ارائه می‌شوند — درخواست‌های تکراری شما در سهمیه محاسبه نمی‌شوند

گام‌های بعدی

شروع سریع : اولین فراخوانی
جستجوی آگهی‌ها : پارامترهای جستجو
آمار : شمارنده‌ها و سری‌ها

API BODACC : احراز هویت و محدودیت‌ها