Birlesa یک پلتفرم B2B است: صفحه‌های شرکت که از سوابق رسمی ساخته می‌شوند، فرصت‌های خریداران که با تأمین‌کنندگان تطبیق داده می‌شوند، پیشنهادهای قیمت، معامله‌ها و پرداخت‌هایی که به‌صورت امانی نگه داشته می‌شوند. این صفحه‌ها توضیح می‌دهند که نرم‌افزار شما چطور با آن کار می‌کند.
| می‌خواهید | از این استفاده کنید |
|---|---|
| داده‌های عمومی را بخوانید: شرکت‌ها، فرصت‌ها، شاخص ماهانه، الزامات صادرات | REST API، بدون کلید، یا با کلید برای سقف مصرف بالاتر |
| از طرف سازمانتان اقدام کنید: فرصت ثبت کنید، از تأمین‌کنندگان استعلام قیمت بگیرید | REST API یا سرور MCP، با کلید APIای که دسترسی لازم را دارد |
| وقتی اتفاقی برای سازمانتان می‌افتد باخبر شوید | وب‌هوک‌ها |
| سوابقی را بخوانید که یک وب‌هوک نام می‌برد (فرصت‌ها، معامله‌ها، پیشنهادهای قیمت، پرداخت‌های امانی، محموله‌ها) | /v1/org/... با کلیدی که org:read دارد |
| ابزارهای Birlesa را در اختیار یک دستیار هوش مصنوعی بگذارید | سرور MCP در /mcp |
| از داده‌های تجمیعی بازار طبق قرارداد استفاده کنید (بانک‌ها، اتحادیه‌ها، نهادهای عمومی) | محصولات داده |
نشانی پایه و قالب‌ها
- محیط اصلی (production):
https://api.birlesa.com. دسترسی به محیط آزمایشی هنوز ارائه نمی‌شود (محیط آزمایشی). - درخواست‌ها و پاسخ‌ها JSON هستند (UTF-8). زمان‌ها در قالب RFC 3339 و به وقت UTC هستند. مبلغ‌ها رشته‌های اعشاری‌اند (
"1250.00")، هرگز عدد ممیز شناور (float). کشورها با کد ISO 3166-1 alpha-2 مشخص می‌شوند (TR،SA)؛ هر جا فیلدی چنین بگوید،EUوGCCنام بلوک‌ها هستند. - مشخصات کامل API همان سند OpenAPI است، در birlesa.com/openapi.json(در زبانه جدید باز می‌شود). همهٔ عملیات‌ها، فیلدها و کدهای خطا آنجا فهرست شده‌اند.
صفحه‌ها
- احراز هویت: کلیدهای API، اعتبارنامه‌های کلاینت OAuth (client credentials)، دسترسی‌ها.
- محدودیت‌ها و سهمیه‌ها: محدودیت‌های نرخ، سهمیه‌های روزانه، مصرف.
- خطاها: قالب problem و کدهایی که با آن‌ها روبه‌رو می‌شوید.
- وب‌هوک‌ها: اندپوینت‌ها، امضاها، تلاش‌های دوباره. فهرست رویدادها همهٔ رویدادها را نام می‌برد.
- نسخه‌بندی و منسوخ‌شدن: چه چیزی در
/v1ممکن است تغییر کند و حذف‌ها چطور اعلام می‌شوند. - سرور MCP: ابزارهایی برای دستیارهای هوش مصنوعی.
- محیط آزمایشی: ساختن و آزمودن با شرکای شبیه‌سازی‌شده و داده‌های آزمایشی (هنوز ارائه نمی‌شود).
- سطح خدمات: هدف ما چیست و وقتی به آن نرسیم، چطور به شما خبر می‌دهیم.
- محصولات داده: مجموعه‌داده‌های تجمیعی طبق قرارداد.
قواعد پایه
- اطلاعات محرمانه (کلیدهای API، کلیدهای محرمانهٔ کلاینت، کلیدهای محرمانهٔ وب‌هوک) را روی سرورهای خودتان نگه دارید. فقط یک بار نمایش داده می‌شوند؛ ما فقط هش یا نسخه‌ای مهروموم‌شده از آن‌ها نگه می‌داریم و نمی‌توانیم دوباره نشانشان دهیم. اگر یکی فاش شد، آن را باطل کنید و یکی تازه بسازید.
- داده‌های شخصی از همان طراحی بیرون از API می‌مانند. وب‌هوک‌ها شناسه می‌فرستند، نه متن یا نام. پیام‌های گفت‌وگوها را افراد در داشبورد می‌خوانند، نه از طریق کلیدها.
- هر کاری که یک اتصال انجام دهد، به نام همان کلید یا کلاینت در سوابق ممیزی سازمان شما ثبت می‌شود.