0

معرفی API

  • مستندات API

Rasmio B2B API دسترسی برنامه‌نویسی به داده‌های رسمی شرکت‌ها و اشخاص حقیقی ایران را فراهم می‌کند: اطلاعات ثبتی و تماس، اعضای هیئت مدیره و صاحبان امضا، مجوزها و قراردادها، آگهی‌های روزنامه رسمی و کدال، سهام و اطلاعات بورسی، و محصولات و علائم تجاری.

این مستندات نسخهٔ ۱ API را پوشش می‌دهد. برای دیدن فهرست کامل و آزمودن درخواست‌ها، مستندات تعاملی Swagger را باز کنید.

آدرس پایه و نسخه‌بندی

  • آدرس پایه: https://api.rasmio.com
  • نسخه در مسیر مشخص می‌شود: /api/v1/...
  • جستجو علاوه بر /api/v1/search در /api/v2/search هم در دسترس است. برای پیاده‌سازی جدید نسخهٔ ۲ را انتخاب کنید؛ نسخهٔ ۱ برای سازگاری با کدهای موجود باقی مانده است.
  • همهٔ درخواست‌ها GET و فقط‌خواندنی‌اند.

احراز هویت

هر درخواست باید کلید API را در هدر X-API-Key بفرستد:

X-API-Key: YOUR_API_KEY

اگر هدر را نفرستید، پاسخ ۴۰۱ با این بدنه برمی‌گردد:

{
  "error": "API Key is missing",
  "message": "لطفاً API Key را در Header با نام X-API-Key ارسال کنید"
}

اگر کلید نامعتبر باشد:

{
  "error": "Invalid API Key",
  "message": "API Key نامعتبر است"
}

کلید را در query string یا مسیر URL نگذارید و آن را در کد سمت کلاینت (مرورگر، اپ موبایل) قرار ندهید. درخواست‌ها را از سرور خودتان بفرستید. اگر کلید لو رفت، از پنل سرویس API یا با پشتیبانی برای باطل‌کردن آن اقدام کنید.

اولین درخواست

برای دریافت اطلاعات ثبتی یک شرکت با شناسهٔ ملی:

curl --request GET \
  'https://api.rasmio.com/api/v1/companies/14009396050/registration-info' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Accept: application/json'

همان درخواست با JavaScript:

const response = await fetch(
  "https://api.rasmio.com/api/v1/companies/14009396050/registration-info",
  {
    headers: {
      "X-API-Key": process.env.RASMIO_API_KEY,
      Accept: "application/json",
    },
  },
);

if (!response.ok) {
  throw new Error(`Rasmio API failed: ${response.status}`);
}

const company = await response.json();
console.log(company.title);

قالب پاسخ

پاسخ موفق، خودِ داده است و پوشش اضافه‌ای مثل data ندارد:

{
  "id": 14009396050,
  "title": "پیشگامان رسمی پردازش دانا",
  "registrationDate": "2020-08-31T00:00:00",
  "registrationNo": "564196",
  "taxNumber": "14009396050",
  "registrationType": "سهامی خاص",
  "capital": 1000000000,
  "category": "فناوری اطلاعات",
  "address": "تهران، شهرک قدس (غرب)، خیابان گلستان جنوبی، پلاک 21",
  "postalCode": "1465865159"
}
  • پاسخ‌های لیستی، آرایهٔ JSON هستند.
  • تاریخ‌ها با تقویم میلادی و قالب ISO 8601 برمی‌گردند، مثل 2020-08-31T00:00:00. بخش زمان ممکن است حذف شده باشد؛ آن را به‌عنوان تاریخ/ساعت همان روز تفسیر کنید.
  • مبالغ مالی، مانند سرمایه و مبلغ قرارداد، به ریال هستند.
  • فیلدهای اختیاری می‌توانند null باشند. در کد، null و نبودِ فیلد را جدا از هم مدیریت کنید.

خطاها

کد معنا بدنهٔ معمول
400 پارامتر ورودی نامعتبر است Result یا ErrorResponseDto
401 کلید API وجود ندارد یا معتبر نیست ErrorResponseDto
404 شرکت، شخص یا مورد درخواستی پیدا نشد ErrorResponseDto
429 سهمیه یا محدودیت نرخ تمام شده است ProblemDetails
500 خطای موقت یا پیش‌بینی‌نشده در سرور Result

نمونهٔ پاسخ ۴۲۹:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.29",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "سهمیهٔ درخواست‌های امروز تمام شده است.",
  "instance": "/api/v1/companies/14009396050/news"
}

شکل بدنهٔ خطا بین endpointها یکسان نیست. اول کد وضعیت HTTP را بررسی کنید، بعد پیام را از message یا error (در پاسخ‌های ۴۰۱ و ۴۰۴) و از title یا detail (در ۴۲۹) بخوانید. خطاهای ۴۰۰ تا ۴۹۹ را دوباره نفرستید. برای ۴۲۹ به‌جای تکرار، سهمیه را بررسی و در صورت اتمام شارژ کنید؛ خطاهای ۵۰۰ تا ۵۹۹ را می‌توانید با backoff دوباره امتحان کنید.

سهمیه و هزینه

هر کلید API دو سقف دارد: سقف روزانه و سقف کل تا تاریخ انقضا. هر endpoint هزینهٔ مشخصی دارد که از سهمیهٔ کلید کم می‌شود. جزئیات و روش مدیریت خطای ۴۲۹ در محدودیت‌های درخواست و سهمیه آمده است.

فهرست سرویس‌ها

گروه endpointها راهنما
اطلاعات ثبتی و تماس شرکت registration-info، contact-info اطلاعات ثبتی و تماس شرکت
اعضا و صاحبان امضا members، signature-holders اعضای رسمی و صاحبان امضا
مجوزها، قراردادها و تولید licenses، sajar-licenses، contracts، production مجوزها، قراردادها و تولید
آگهی‌ها news آگهی‌های روزنامه رسمی و کدال
سهام و بورس shares، portfolio، stock-shareholders سهام، پورتفولیو و سهامداران
روابط، محصولات و برند relations، products، trademarks روابط، محصولات و علائم تجاری
اشخاص roles، news، shares سمت‌های شخص و آگهی‌های شخص
جستجو /api/v1/search، /api/v2/search جستجو در اشخاص و شرکت‌ها

پشتیبانی

دسته‌بندی‌ها
  • مستندات API