مستندات فنی وب‌سرویس مالیتور

۱. شروع سریع و احراز هویت

تمامی درخواست‌ها به وب‌سرویس مالیتور به صورت پروتکل استاندارد REST API و با قالب تبادل داده JSON ارسال می‌شوند. جهت برقراری ارتباط، ارسال کلید دسترسی اختصاصی در هدر درخواست الزامی است.

۲. الزامات امنیتی و محدودیت‌ها

• لیست سفید آی‌پی (IP Whitelist): درخواست‌های ارسالی با API Key شما تنها از آدرس‌های IP تعریف‌شده در پنل کاربری مجاز خواهند بود. در صورت ارسال درخواست از IP ناشناس، خطای 403 Forbidden بازگردانده می‌شود.
• کنترل نرخ درخواست (Rate Limit): جهت حفظ پایداری سرویس، هر مودی مجاز به ارسال نهایتاً ۳۰ درخواست در ثانیه است. در صورت فراتر رفتن، سیستم خطای 429 Too Many Requests صادر می‌کند.

قبل از اقدام به ثبت اسناد، با فراخوانی این متد می توانید سقف مجاز روزانه و شارژ اعتباری باقیمانده را بررسی فرمایید.

curl -X GET "https://api.malitor.ir/api/v1/invoices/quota" \
-H "accept: application/json" \
-H "X-API-KEY: 11111111-2222-3333-4444-555555555555"

نمونه پاسخ موفق (200 OK):

{
  "isSuccess": true,
  "data": {
    "dailyLimit": 1000,
    "todaySentCount": 12,
    "remainingDailyLimit": 988,
    "currentBalance": 4988
  },
  "errorMessage": null,
  "referenceNumber": "MALITOR-20261016183020-A1B2C3D4"
}

این متد برای ارسال صورتحساب های فروش کالا و خدمات با الگوی ۱ به سامانه مودیان استفاده می‌شود. پس از ارسال موفق، یک TrackingCode (کد رهگیری) به شما بازگردانده می‌شود.

نمونه بدنه درخواست (Request Body):

{
  "invoiceDate": "2023-11-25T14:30:00",
  "invoiceNumber": "10052",
  "buyerNationalId": "1234567890",
  "buyerType": 1, 
  "items": [
    {
      "stuffId": "2720000123456",
      "quantity": 2,
      "unitPrice": 1500000,
      "discount": 0,
      "taxRate": 9
    }
  ]
}

نمونه پاسخ موفق (200 OK):

{
  "isSuccess": true,
  "data": {
    "trackingCode": "8f3a5b2c-1d4e-4f7a-8b9c-2d3e4f5a6b7c"
  },
  "errorMessage": null,
  "referenceNumber": "MALITOR-20261016184512-XYZ987"
}

با استفاده از کد رهگیری (TrackingCode) دریافت شده در مرحله قبل، می توانید وضعیت تایید یا خطای فاکتور را از سامانه مودیان استعلام بگیرید.

curl -X GET "https://api.malitor.ir/api/v1/invoices/inquiry/8f3a5b2c-1d4e..." \
-H "accept: application/json" \
-H "X-API-KEY: 11111111-2222-3333-4444-555555555555"

نمونه پاسخ (وضعیت فاکتور):

{
  "isSuccess": true,
  "data": {
    "status": "Success",
    "taxId": "1111111111111111111111",
    "message": "Invoice Sent"
  },
  "errorMessage": null,
  "referenceNumber": "MALITOR-20261016185010-ABC123"
}