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

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

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

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

• لیست مجاز آی‌پی (IP Whitelist): درخواست‌ها به منظور جلوگیری از سوءاستفاده، صرفاً از آی‌پی‌های سروری که در پنل مودی ثبت شده‌اند پذیرش می‌شوند. در صورت ارسال درخواست از IP تعریف‌نشده، خطای 403 Forbidden دریافت خواهد شد.
• سقف ارسال هم‌زمان (Rate Limiting): هر کلاینت مجاز به ارسال حداکثر ۳۰ درخواست در ثانیه است تا پایداری خط ارتباطی با سازمان امور مالیاتی حفظ گردد.

پیش از ثبت صورتحساب ها، با فراخوانی این متد سقف مجاز روزانه و موجودی شارژ حساب کاربری را بررسی نمایید.

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

{
  "isSuccess": true,
  "errorMessage": null,
  "referenceNumber": "MALITOR-20261106-112501-A1B2",
  "data": {
    "dailyLimit": 1000,
    "todaySentCount": 15,
    "remainingDailyLimit": 985,
    "currentBalance": 4985
  }
}

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

جدول پارامترهای هدر و اقلام فاکتور:

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

{
  "internalNo": 1050,
  "invoiceDateTime": "2026-11-06T10:30:00",
  "invoiceType": 1,
  "invoiceSubject": 1,
  "referenceTaxId": null,
  "isArticle9": false,
  "buyerType": 1,
  "buyerName": "رضا محمدی",
  "buyerNationalCode": "0012345678",
  "invoicePattern": 1,
  "settlementType": 1,
  "cashPayment": 1100000.0,
  "items": [
    {
      "sstid": "2720000114427",
      "sstt": "خدمات پشتیبانی نرم افزار",
      "am": 1.0,
      "fee": 1000000.0,
      "dis": 0.0,
      "vra": 10.0,
      "unit": "162"
    }
  ]
}

نمونه پاسخ ثبت در صف (200 OK):

{
  "isSuccess": true,
  "errorMessage": null,
  "referenceNumber": "MALITOR-20261106-112502-B3C4",
  "data": {
    "trackingUid": "9a12c456-7890-4abc-def1-23456789abcd",
    "message": "صورتحساب با موفقیت در صف ارسال قرار گرفت و ۱ واحد از اعتبار API شما کسر شد."
  }
}

با استفاده از کد پیگیری (trackingCode یا شناسه trackingUid)، وضعیت تایید در کارپوشه سامانه مودیان و کد ۲۲ رقمی مالیاتی صادرشده را دریافت فرمایید.

نمونه پاسخ استعلام:

{
  "isSuccess": true,
  "errorMessage": null,
  "referenceNumber": "MALITOR-20261106-112503-C5D6",
  "data": {
    "internalNo": 1050,
    "trackingUid": "9a12c456-7890-4abc-def1-23456789abcd",
    "taxId": "A12BC345D678EF90123456",
    "invoiceDate": "2026-11-06T10:30:00",
    "status": 1,
    "createDate": "2026-11-06T10:30:15",
    "inquiryCount": 2,
    "lastInquiryDate": "2026-11-06T10:35:00"
  }
}

دریافت لیست فاکتورهای ثبت‌شده همراه با ردیف اقلام و کنترل صفحه بندی.

مشاهده مشخصات کامل هدر، مبالغ پرداختی، مشخصات خریدار و اقلام ردیف فاکتور بر اساس شناسه پیگیری یکتا.

۸. جدول کدهای استاندارد سامانه مودیان (Schemas)

۹. نمونه کدهای آماده اتصال برای توسعه‌دهندگان

var client = new RestClient("https://apiaddress.ir/api/v1/Invoices/pattern1");
var request = new RestRequest(Method.POST);
request.AddHeader("X-API-KEY", "Your-Api-Key-Here");
request.AddHeader("Content-Type", "application/json");

var payload = new {
    internalNo = 1050,
    invoiceDateTime = DateTime.Now.ToString("s"),
    invoiceType = 1,
    invoiceSubject = 1,
    buyerType = 1,
    buyerName = "رضا محمدی",
    buyerNationalCode = "0012345678",
    invoicePattern = 1,
    settlementType = 1,
    cashPayment = 1100000m,
    items = new[] {
        new { sstid = "2720000114427", sstt = "توسعه نرم‌افزار", am = 1m, fee = 1000000m, vra = 10m, unit = "162" }
    }
};

request.AddJsonBody(payload);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

<?php
$apiKey = "Your-Api-Key-Here";
$url = "https://apiaddress.ir/api/v1/Invoices/pattern1";

$data = [
    "internalNo" => 1050,
    "invoiceDateTime" => date('Y-m-d\TH:i:s'),
    "invoiceType" => 1,
    "invoiceSubject" => 1,
    "buyerType" => 1,
    "buyerName" => "شرکت نمونه",
    "invoicePattern" => 1,
    "settlementType" => 1,
    "cashPayment" => 1100000,
    "items" => [
        [ "sstid" => "2720000114427", "am" => 1, "fee" => 1000000, "vra" => 10, "unit" => "162" ]
    ]
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-KEY: " . $apiKey,
    "Content-Type: application/json"
]);

$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>

Sub SendInvoiceToMalitor()
    Dim http As Object, url As String, apiKey As String, jsonPayload As String
    
    url = "https://apiaddress.ir/api/v1/Invoices/pattern1"
    apiKey = "Your-Api-Key-Here"
    
    jsonPayload = "{""internalNo"": 1050, ""invoiceDateTime"": """ & Format(Now, "yyyy-mm-ddThh:mm:ss") & """, ""invoiceType"": 1, ""invoiceSubject"": 1, ""buyerType"": 1, ""buyerName"": ""خریدار اکسل"", ""invoicePattern"": 1, ""settlementType"": 1, ""cashPayment"": 1100000, ""items"": [{""sstid"": ""2720000114427"", ""am"": 1, ""fee"": 1000000, ""vra"": 10, ""unit"": ""162""}]}"
    
    Set http = CreateObject("MSXML2.ServerXMLHTTP.6.0")
    http.Open "POST", url, False
    http.setRequestHeader "Content-Type", "application/json"
    http.setRequestHeader "X-API-KEY", apiKey
    http.send jsonPayload
    
    MsgBox "پاسخ مالیتور: " & vbCrLf & http.responseText, vbInformation, "سامانه مودیان"
End Sub