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

مستندات API نسخه ۲ آسا

هر آنچه نرم‌افزار شما برای ثبت صورتحساب در سامانهٔ مؤدیان از راه معتمد آسا لازم دارد: مسیر اتصال مشتری مستقیم و کارگزار، توکن، ثبت گروهی با JSON سازمان یا مدل ساده، پیگیری وضعیت و کارپوشهٔ مالیاتی؛ با شماتیک و نمونه‌کد آماده.

نشانی پایه
api-v2.asatsp.ir
احراز هویت
OAuth 2.0 · client credentials
اعتبار توکن
۶۰ دقیقه (پیش‌فرض)
نمونه‌کد
cURL · JavaScript · C# · Python · PHP

مستندات API نسخه ۲ آسا

00شروع

قرارداد عمومی API

API نسخه ۲ صورتحساب را در قالب JSON سازمان امور مالیاتی یا در مدل ساده می‌گیرد، آن را پیش از ثبت با قواعد دستورالعمل سامانه مؤدیان بررسی می‌کند، ثبت می‌کند و به سامانه مؤدیان می‌فرستد. هر خطا با پیامی روشن، مسیر فیلد و شناسه پیگیری برمی‌گردد و جزئیات فنی سرور در پاسخ نمی‌آید.

Base URL https://api-v2.asatsp.ir
Content-Type application/json; charset=utf-8
Authentication Authorization: Bearer <AccessToken>
Batch Size ۱ تا ۲۵۰ صورتحساب
ثبت چند صورتحساب در یک درخواست پاسخ خطای ساخت‌یافته با errors[] نتیجه جداگانه برای هر صورتحساب، به ترتیب درخواست بدون جزئیات فنی سرور در پاسخ
00Aشروع

شروع سریع در محیط آزمایشی

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

۱. اعتبارنامه

در پنل، کسب‌وکار را انتخاب کنید و در «تنظیمات ← اتصال API v2» اعتبارنامه صادر کنید. client_secret فقط همان لحظه نمایش داده می‌شود. جزئیات در بخش احراز هویت است.

۲. شناسه حافظه آزمایشی

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

۳. اجرای نمونه

یکی از نمونه‌های زیر را بردارید، client_id و client_secret را در متغیرهای محیطی بگذارید و اجرا کنید. هر نمونه کامل است و به همین شکل در محیط آزمایشی اجرا و آزموده شده است.

۴. نتیجه

پاسخ ثبت با result: 1 و taxId برمی‌گردد. وضعیت صورتحساب ابتدا 0 (ثبت‌شده و در انتظار ارسال) و سپس 1 (ارسال‌شده و در انتظار پاسخ سامانه) است و معمولاً در چند دقیقه به 2 (موفق) می‌رسد. با send: true ارسال خودکار است؛ صورتحسابی که با send: false ثبت شود در وضعیت 0 می‌ماند تا ارسال دستی شود. معنای هر وضعیت در بخش پیگیری وضعیت است.

نمونه کامل: توکن، ثبت و پیگیری

cURL / سه درخواست پشت سر هم
# ۱. توکن: مقدار access_token پاسخ را برای گام‌های بعد نگه دارید (اعتبار: ۶۰ دقیقه).
curl -X POST "https://api-v2.asatsp.ir/api/auth/v2/token" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"grant_type":"client_credentials","client_id":"<client_id>","client_secret":"<client_secret>"}'

# ۲. ثبت یک صورتحساب نوع ۲ در محیط آزمایشی.
#    uuid را برای هر درخواست تازه بسازید. dateTime تاریخ و ساعت حال به وقت تهران با قالب yyyyMMddHHmmss است.
curl -X POST "https://api-v2.asatsp.ir/api/invoice/salesEndUser" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "uuid": "<uuid>",
    "data": [{
      "internalId": "QS-1001",
      "no": "1001",
      "dateTime": "<yyyyMMddHHmmss>",
      "invoiceSubject": 1,
      "settlement": 1,
      "send": true,
      "sandBox": true,
      "items": [{
        "internalId": "ITEM-1",
        "stuffId": "2720000114542",
        "description": "بسته نرم افزار رایانه ای",
        "qty": 1,
        "unit": "1627",
        "unitPrice": 1000000,
        "discount": 0,
        "vatRate": 10
      }],
      "payments": [{ "type": 2, "dateTime": "<yyyyMMddHHmmss>", "price": 1100000 }]
    }]
  }'

# ۳. پیگیری وضعیت با همان internalId
curl -X POST "https://api-v2.asatsp.ir/api/invoice/inquiryInternalId" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"internalId":"QS-1001"}'
Node.js 18+ / quickstart.mjs
// شروع سریع API نسخه ۲ معتمد آسا: توکن، ثبت یک صورتحساب آزمایشی (Sandbox) و پیگیری وضعیت آن.
// اجرا: node quickstart.mjs   (Node.js 18 یا بالاتر)
// پیش از اجرا: ASA_CLIENT_ID و ASA_CLIENT_SECRET را در متغیرهای محیطی بگذارید.
import { randomUUID } from "node:crypto";

const BASE_URL = process.env.ASA_BASE_URL ?? "https://api-v2.asatsp.ir";

async function post(path, body, token) {
  const response = await fetch(BASE_URL + path, {
    method: "POST",
    headers: {
      "Content-Type": "application/json; charset=utf-8",
      ...(token ? { Authorization: `Bearer ${token}` } : {}),
    },
    body: JSON.stringify(body),
    signal: AbortSignal.timeout(60_000),
  });
  const text = await response.text();
  const json = text ? JSON.parse(text) : null;
  if (!response.ok) {
    throw new Error(`${path} -> HTTP ${response.status}: ${text}`);
  }
  return json;
}

// تاریخ و ساعت به وقت تهران با قالب yyyyMMddHHmmss
function tehranNow() {
  const parts = new Intl.DateTimeFormat("en-GB", {
    timeZone: "Asia/Tehran", hourCycle: "h23",
    year: "numeric", month: "2-digit", day: "2-digit",
    hour: "2-digit", minute: "2-digit", second: "2-digit",
  }).formatToParts(new Date());
  const get = (type) => parts.find((part) => part.type === type).value;
  return get("year") + get("month") + get("day") + get("hour") + get("minute") + get("second");
}

// ۱. توکن: تا نزدیک پایان expires_in برای همه درخواست‌ها همین توکن را به کار ببرید.
const token = (await post("/api/auth/v2/token", {
  grant_type: "client_credentials",
  client_id: process.env.ASA_CLIENT_ID,
  client_secret: process.env.ASA_CLIENT_SECRET,
})).access_token;

// ۲. ثبت یک صورتحساب نوع ۲ در محیط آزمایشی
const now = tehranNow();
const internalId = `QS-${now}`;
const sent = await post("/api/invoice/salesEndUser", {
  uuid: randomUUID(),
  data: [{
    internalId,
    no: now.slice(4),
    dateTime: now,
    invoiceSubject: 1,
    settlement: 1,
    send: true,
    sandBox: true,
    items: [{
      internalId: "ITEM-1",
      stuffId: "2720000114542",
      description: "بسته نرم افزار رایانه ای",
      qty: 1,
      unit: "1627",
      unitPrice: 1000000,
      discount: 0,
      vatRate: 10,
    }],
    payments: [{ type: 2, dateTime: now, price: 1100000 }],
  }],
}, token);

if (sent.result !== 1) {
  // خطاها در errors[] با مسیر دقیق فیلد برمی‌گردند.
  throw new Error("ثبت انجام نشد: " + JSON.stringify(sent.errors ?? sent));
}
console.log("ثبت شد:", sent.data[0].internalId, "taxId:", sent.data[0].taxId, "محیط:", sent.data[0].environment);

// ۳. پیگیری وضعیت با همان internalId
const status = await post("/api/invoice/inquiryInternalId", { internalId }, token);
console.log("وضعیت:", status.status, "شماره پیگیری سازمان:", status.refrenceNumber || "(هنوز صادر نشده)");
.NET 8+ / Program.cs
// شروع سریع API نسخه ۲ معتمد آسا: توکن، ثبت یک صورتحساب آزمایشی (Sandbox) و پیگیری وضعیت آن.
// اجرا: dotnet run   (.NET 8 یا بالاتر)
// پیش از اجرا: ASA_CLIENT_ID و ASA_CLIENT_SECRET را در متغیرهای محیطی بگذارید.
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

Console.OutputEncoding = System.Text.Encoding.UTF8;
var http = new HttpClient
{
    BaseAddress = new Uri(Environment.GetEnvironmentVariable("ASA_BASE_URL") ?? "https://api-v2.asatsp.ir"),
    Timeout = TimeSpan.FromSeconds(60),
};

async Task<JsonElement> Post(string path, object body)
{
    using var response = await http.PostAsJsonAsync(path, body);
    string text = await response.Content.ReadAsStringAsync();
    if (!response.IsSuccessStatusCode)
    {
        throw new InvalidOperationException($"{path} -> HTTP {(int)response.StatusCode}: {text}");
    }
    return JsonDocument.Parse(text).RootElement;
}

// ۱. توکن: تا نزدیک پایان expires_in برای همه درخواست‌ها همین توکن را به کار ببرید.
JsonElement tokenAnswer = await Post("/api/auth/v2/token", new
{
    grant_type = "client_credentials",
    client_id = Environment.GetEnvironmentVariable("ASA_CLIENT_ID"),
    client_secret = Environment.GetEnvironmentVariable("ASA_CLIENT_SECRET"),
});
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", tokenAnswer.GetProperty("access_token").GetString());

// ۲. ثبت یک صورتحساب نوع ۲ در محیط آزمایشی؛ تاریخ و ساعت به وقت تهران با قالب yyyyMMddHHmmss
string now = TimeZoneInfo
    .ConvertTime(DateTimeOffset.UtcNow, TimeZoneInfo.FindSystemTimeZoneById("Asia/Tehran"))
    .ToString("yyyyMMddHHmmss");
string internalId = "QS-" + now;
JsonElement sent = await Post("/api/invoice/salesEndUser", new
{
    uuid = Guid.NewGuid().ToString(),
    data = new[]
    {
        new
        {
            internalId,
            no = now[4..],
            dateTime = now,
            invoiceSubject = 1,
            settlement = 1,
            send = true,
            sandBox = true,
            items = new[]
            {
                new
                {
                    internalId = "ITEM-1",
                    stuffId = "2720000114542",
                    description = "بسته نرم افزار رایانه ای",
                    qty = 1,
                    unit = "1627",
                    unitPrice = 1000000,
                    discount = 0,
                    vatRate = 10,
                },
            },
            payments = new[] { new { type = 2, dateTime = now, price = 1100000 } },
        },
    },
});

if (sent.GetProperty("result").GetInt32() != 1)
{
    // خطاها در errors[] با مسیر دقیق فیلد برمی‌گردند.
    throw new InvalidOperationException("ثبت انجام نشد: " + sent.GetRawText());
}
JsonElement first = sent.GetProperty("data")[0];
Console.WriteLine($"ثبت شد: {first.GetProperty("internalId")} taxId: {first.GetProperty("taxId")} محیط: {first.GetProperty("environment")}");

// ۳. پیگیری وضعیت با همان internalId
JsonElement status = await Post("/api/invoice/inquiryInternalId", new { internalId });
string reference = status.TryGetProperty("refrenceNumber", out JsonElement value) ? value.GetString() ?? "" : "";
Console.WriteLine($"وضعیت: {status.GetProperty("status")} شماره مرجع سازمان: {(reference.Length > 0 ? reference : "(هنوز صادر نشده)")}");
Python 3.9+ / quickstart.py
# شروع سریع API نسخه ۲ معتمد آسا: توکن، ثبت یک صورتحساب آزمایشی (Sandbox) و پیگیری وضعیت آن.
# اجرا: python quickstart.py   (Python 3.9 یا بالاتر، با بسته requests)
# پیش از اجرا: ASA_CLIENT_ID و ASA_CLIENT_SECRET را در متغیرهای محیطی بگذارید.
import os
import sys
import uuid
from datetime import datetime
from zoneinfo import ZoneInfo

import requests

BASE_URL = os.environ.get("ASA_BASE_URL", "https://api-v2.asatsp.ir")
sys.stdout.reconfigure(encoding="utf-8")  # چاپ درست متن فارسی در ترمینال ویندوز


def post(path, body, token=None):
    headers = {"Content-Type": "application/json; charset=utf-8"}
    if token:
        headers["Authorization"] = "Bearer " + token
    response = requests.post(BASE_URL + path, json=body, headers=headers, timeout=60)
    if not response.ok:
        raise RuntimeError(f"{path} -> HTTP {response.status_code}: {response.text}")
    return response.json()


# ۱. توکن: تا نزدیک پایان expires_in برای همه درخواست‌ها همین توکن را به کار ببرید.
token = post("/api/auth/v2/token", {
    "grant_type": "client_credentials",
    "client_id": os.environ["ASA_CLIENT_ID"],
    "client_secret": os.environ["ASA_CLIENT_SECRET"],
})["access_token"]

# ۲. ثبت یک صورتحساب نوع ۲ در محیط آزمایشی؛ تاریخ و ساعت به وقت تهران با قالب yyyyMMddHHmmss
now = datetime.now(ZoneInfo("Asia/Tehran")).strftime("%Y%m%d%H%M%S")
internal_id = "QS-" + now
sent = post("/api/invoice/salesEndUser", {
    "uuid": str(uuid.uuid4()),
    "data": [{
        "internalId": internal_id,
        "no": now[4:],
        "dateTime": now,
        "invoiceSubject": 1,
        "settlement": 1,
        "send": True,
        "sandBox": True,
        "items": [{
            "internalId": "ITEM-1",
            "stuffId": "2720000114542",
            "description": "بسته نرم افزار رایانه ای",
            "qty": 1,
            "unit": "1627",
            "unitPrice": 1000000,
            "discount": 0,
            "vatRate": 10,
        }],
        "payments": [{"type": 2, "dateTime": now, "price": 1100000}],
    }],
}, token)

if sent.get("result") != 1:
    # خطاها در errors[] با مسیر دقیق فیلد برمی‌گردند.
    raise RuntimeError("ثبت انجام نشد: " + str(sent.get("errors") or sent))
print("ثبت شد:", sent["data"][0]["internalId"], "taxId:", sent["data"][0]["taxId"], "محیط:", sent["data"][0]["environment"])

# ۳. پیگیری وضعیت با همان internalId
status = post("/api/invoice/inquiryInternalId", {"internalId": internal_id}, token)
print("وضعیت:", status["status"], "شماره مرجع سازمان:", status.get("refrenceNumber") or "(هنوز صادر نشده)")
PHP 8 / quickstart.php
<?php
// شروع سریع API نسخه ۲ معتمد آسا: توکن، ثبت یک صورتحساب آزمایشی (Sandbox) و پیگیری وضعیت آن.
// اجرا: php quickstart.php   (PHP 8 با افزونه curl)
// پیش از اجرا: ASA_CLIENT_ID و ASA_CLIENT_SECRET را در متغیرهای محیطی بگذارید.
declare(strict_types=1);

$baseUrl = getenv('ASA_BASE_URL') ?: 'https://api-v2.asatsp.ir';

function post(string $url, array $body, ?string $token = null): array
{
    $headers = ['Content-Type: application/json; charset=utf-8'];
    if ($token !== null) {
        $headers[] = 'Authorization: Bearer ' . $token;
    }
    $curl = curl_init($url);
    curl_setopt_array($curl, [
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_POSTFIELDS => json_encode($body, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 60,
    ]);
    $text = curl_exec($curl);
    if ($text === false) {
        throw new RuntimeException('خطای ارتباط: ' . curl_error($curl));
    }
    $status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
    curl_close($curl);
    if ($status < 200 || $status >= 300) {
        throw new RuntimeException("$url -> HTTP $status: $text");
    }
    return json_decode($text, true, 512, JSON_THROW_ON_ERROR);
}

// ۱. توکن: تا نزدیک پایان expires_in برای همه درخواست‌ها همین توکن را به کار ببرید.
$token = post($baseUrl . '/api/auth/v2/token', [
    'grant_type' => 'client_credentials',
    'client_id' => getenv('ASA_CLIENT_ID'),
    'client_secret' => getenv('ASA_CLIENT_SECRET'),
])['access_token'];

// ۲. ثبت یک صورتحساب نوع ۲ در محیط آزمایشی؛ تاریخ و ساعت به وقت تهران با قالب yyyyMMddHHmmss
$now = (new DateTimeImmutable('now', new DateTimeZone('Asia/Tehran')))->format('YmdHis');
$internalId = 'QS-' . $now;
$sent = post($baseUrl . '/api/invoice/salesEndUser', [
    'uuid' => sprintf('%s-%s-%s-%s-%s', bin2hex(random_bytes(4)), bin2hex(random_bytes(2)), bin2hex(random_bytes(2)), bin2hex(random_bytes(2)), bin2hex(random_bytes(6))),
    'data' => [[
        'internalId' => $internalId,
        'no' => substr($now, 4),
        'dateTime' => $now,
        'invoiceSubject' => 1,
        'settlement' => 1,
        'send' => true,
        'sandBox' => true,
        'items' => [[
            'internalId' => 'ITEM-1',
            'stuffId' => '2720000114542',
            'description' => 'بسته نرم افزار رایانه ای',
            'qty' => 1,
            'unit' => '1627',
            'unitPrice' => 1000000,
            'discount' => 0,
            'vatRate' => 10,
        ]],
        'payments' => [['type' => 2, 'dateTime' => $now, 'price' => 1100000]],
    ]],
], $token);

if (($sent['result'] ?? 0) !== 1) {
    // خطاها در errors[] با مسیر دقیق فیلد برمی‌گردند.
    throw new RuntimeException('ثبت انجام نشد: ' . json_encode($sent['errors'] ?? $sent, JSON_UNESCAPED_UNICODE));
}
echo 'ثبت شد: ', $sent['data'][0]['internalId'], ' taxId: ', $sent['data'][0]['taxId'], ' محیط: ', $sent['data'][0]['environment'], PHP_EOL;

// ۳. پیگیری وضعیت با همان internalId
$status = post($baseUrl . '/api/invoice/inquiryInternalId', ['internalId' => $internalId], $token);
echo 'وضعیت: ', $status['status'], ' شماره مرجع سازمان: ', ($status['refrenceNumber'] ?? '') ?: '(هنوز صادر نشده)', PHP_EOL;
پاسخ ثبت (گام ۲)
{
  "result": 1,
  "traceId": "1b737877-2d9b-4eb9-bd0d-8e1437f89cb5",
  "message": "صورتحساب با موفقیت ثبت شد.",
  "data": [
    {
      "asatspId": 12020168,
      "taxId": "A1172Z0512500000F434B2",
      "fiscalMemoryId": 5109,
      "fiscalId": "A1172Z",
      "fiscalMemoryTitle": "معتمد آسا",
      "sandBox": true,
      "environment": "Sandbox",
      "environmentTitle": "سندباکس",
      "isDefaultFiscalMemory": true,
      "status": 0,
      "issue": 1,
      "internalId": "QS-20261117000626"
    }
  ]
}
پس از موفق شدن این آزمایش، همین کد را برای محیط عملیاتی به کار ببرید: sandBox را بردارید یا false بفرستید و شناسه کالا/خدمت، مبلغ و اطلاعات خریدار واقعی را جایگزین کنید. پیش از آن راهنمای آزمایش و چک‌لیست نهایی را ببینید.
00Bشروع

قواعد مشترک همه سرویس‌ها

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

موضوعقاعده
نشانی و رمزنگاریهمه درخواست‌ها با HTTPS به https://api-v2.asatsp.ir فرستاده می‌شوند. درخواست HTTP ساده با پاسخ 301 به HTTPS هدایت می‌شود و بیشتر کتابخانه‌ها بدنه درخواست POST را در این هدایت نمی‌فرستند؛ پس نشانی را از ابتدا با https:// بنویسید.
قالب دادهبدنه درخواست و پاسخ JSON با کدگذاری UTF-8 است. هدر Content-Type: application/json; charset=utf-8 را بفرستید. نام فیلدها را دقیقاً با همان حروف بزرگ و کوچک این مستندات بنویسید.
احراز هویتهدر Authorization: Bearer <AccessToken> در همه درخواست‌ها، جز درخواست توکن. توکن ۶۰ دقیقه اعتبار دارد؛ آن را نگه دارید و چند دقیقه پیش از پایان اعتبار توکن تازه بگیرید (احراز هویت).
تاریخ و ساعتدر مدل ساده، تاریخ و ساعت به وقت تهران و با قالب yyyyMMddHHmmss است، مثل 20261117103000. در JSON سازمان، indatim و دیگر زمان‌ها عدد میلی‌ثانیه Unix هستند، طبق دستورالعمل سازمان امور مالیاتی.
مبلغ‌هامبلغ‌ها به ریال و بدون جداکننده هزارگان فرستاده می‌شوند. تعداد رقم اعشار هر فیلد در جدول همان فیلد آمده است.
شناسه درخواستدر ثبت صورتحساب، uuid هر درخواست تازه را یکتا بسازید و internalId هر صورتحساب را ثابت نگه دارید. درخواست تکراری با همان uuid ثبت نمی‌شود و پاسخ result: -2 با کد INVOICE_DUPLICATE_REQUEST می‌گیرد.
دو شکل پاسخسرویس‌های /api/invoice/* و /api/register معمولاً با HTTP 200 پاسخ می‌دهند و نتیجه را در result، errors[] و وضعیت هر صورتحساب می‌گویند. بیشتر سرویس‌های /api/v2/* نتیجه را با کد وضعیت HTTP واقعی و بدنه status، data، errors[]، fieldErrors[] و correlationId برمی‌گردانند؛ /api/v2/stuffid و /api/v2/client/ip-access وضعیت HTTP واقعی دارند، ولی بدنه آن‌ها result دارد. سرویس‌های توکن (/api/auth/v2/*) قالب OAuth دارند: پاسخ موفق access_token دارد و بیشتر پاسخ‌های خطا فیلد error دارند (احراز هویت). جزئیات هر دو در خطاها و پاسخ‌ها است.
شناسه پیگیریهر پاسخ هدر X-Correlation-ID دارد و پاسخ‌های ثبت صورتحساب traceId هم دارند. اگر خودتان هدر X-Correlation-ID بفرستید، همان مقدار برمی‌گردد. این شناسه را در گزارش‌های سامانه خود ثبت کنید و هنگام پیگیری از پشتیبانی بفرستید.
مهلت پاسخمهلت انتظار هر درخواست را در نرم‌افزار خود دست‌کم ۶۰ ثانیه بگذارید. پس از قطع ارتباط یا پایان مهلت در ثبت صورتحساب، پیش از ارسال دوباره وضعیت را با internalId استعلام کنید (قاعده تکرار امن درخواست).
تکرار خودکارفقط خطای ارتباط و پاسخ‌های 429، 502، 503 و 504 را با فاصله افزایشی (مثلاً ۵، ۱۵ و ۴۵ ثانیه) تکرار کنید. اگر پاسخ هدر Retry-After داشت، دست‌کم همان مدت صبر کنید. خطای اعتبارسنجی، 400، 401، 402 و 403 با تکرار درست نمی‌شود.
سقف‌هادرخواست توکن: به‌طور پیش‌فرض ۳۰ درخواست در دقیقه برای هر client_id و نشانی IP. ثبت صورتحساب: ۱ تا ۲۵۰ صورتحساب در هر درخواست (رفتار ثبت گروهی). حجم بدنه هر درخواست: حدود ۵۰ مگابایت.
تغییرات APIتغییرات API نسخه ۲ افزایشی است: مسیر یا فیلد تازه اضافه می‌شود و فیلدهای موجود حذف نمی‌شوند و معنای آن‌ها تغییر نمی‌کند. فیلد ناشناخته در پاسخ را نادیده بگیرید تا با افزوده شدن فیلدهای تازه، نرم‌افزار شما بدون تغییر کار کند. پایان پشتیبانی هر روش قدیمی از پیش اعلام می‌شود و پاسخ‌های آن روش هدرهای Deprecation و Sunset دارند. فهرست تغییرات در تاریخچه تغییرات است.
00Cشروع

فایل OpenAPI، مجموعه Postman و نمونه‌کدها

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

فایلکاربرد
openapi.jsonتوصیف API به استاندارد OpenAPI 3.0: همه مسیرها، فیلدهای درخواست و پاسخ، scopeها و کدهای خطا. آن را در Swagger Editor، Postman یا Insomnia باز کنید، یا با ابزارهایی مثل OpenAPI Generator برای زبان نرم‌افزار خود کد اتصال بسازید.
asa-api-v2.postman_collection.jsonمجموعه Postman با همه درخواست‌ها و نمونه بدنه‌ها. فقط متغیرهای client_id و client_secret را پر کنید؛ درخواست «دریافت توکن» مقدار توکن را خودش در متغیر access_token می‌گذارد و درخواست‌های دیگر آن را به کار می‌برند.
نمونه‌کد شروع سریعنمونه کامل توکن، ثبت و پیگیری به زبان‌های cURL، JavaScript، C#، Python و PHP که در محیط آزمایشی اجرا و آزموده شده‌اند.
توصیف OpenAPI برای ساختن کد و آزمایش سریع است. قواعد کامل هر فیلد، مثل الزام شرطی فیلدها در هر الگو، در همین مستندات و در اعتبارسنجی JSON آمده است.
01شروع

مسیر اتصال: مشتری مستقیم یا کارگزار

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

مسیر ۱

مشتری مستقیم

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

  1. اعتبارنامه از پنلمدیر کسب‌وکار در «تنظیمات › اتصال API v2» آن را صادر می‌کند: v2-customer-{شناسه} و client_secret.
  2. گرفتن توکنPOST /api/auth/v2/token؛ توکن ۶۰ دقیقه اعتبار دارد.
  3. ثبت صورتحساب/api/invoice/send با JSON سازمان، یا مسیرهای مدل ساده؛ ۱ تا ۲۵۰ صورتحساب در هر درخواست.
  4. پیگیری نتیجهبا internalId، شماره یا taxId از مسیرهای inquiry*.
احراز هویت و گرفتن توکن ←
مسیر ۲

کارگزار

نرم‌افزاری که مشتریان خودش را در معتمد آسا ثبت می‌کند و صورتحساب هر کدام را می‌فرستد.

  1. ثبت در «همکاران API» و اعتبارنامهٔ همکارv2-partner-{شناسه} با scope v2.register، از «پیشخوان همکاری».
  2. ثبت هر مشتریمستقیم با /api/register، یا با لینک موقت ثبت‌نام و رضایت مالک.
  3. اعتبارنامهٔ هر مشتریserviceAuth نخستین ثبت، تحویل در لینک ثبت‌نام (فقط برای کسب‌وکاری که هنوز اعتبارنامه ندارد) یا Client Secret تازه از پنل مالک.
  4. ارسال با توکن همان مشتریمثل مسیر ۱؛ توکن یک مشتری برای مشتری دیگر کار نمی‌کند.
  5. پایش«پیشخوان همکاری»، هشدارها، وبهوک و گزارش‌های API.
راهنمای کارگزاران و شماتیک‌ها ←

هر ارسال در چهار گام

ثبت مشتری (فقط کارگزار) /api/register مشتری را ایجاد یا به‌روزرسانی می‌کند و اعتبارنامهٔ مشتری (serviceAuth) را بازمی‌گرداند.
ساخت درخواست uuid + data[] هر عضو data یک صورتحساب با internalId یکتاست و جدا از بقیه بررسی و ذخیره می‌شود؛ حداکثر ۲۵۰ عضو.
ثبت صورتحساب /api/invoice/send پیش از ذخیره، ساختار JSON، قواعد دستورالعمل و جمع‌های مالی بررسی می‌شوند.
پیگیری وضعیت /api/invoice/inquiry* نتیجهٔ سامانهٔ مؤدیان با internalId، inno یا taxId خوانده می‌شود.

آنچه در این میان بر سر هر صورتحساب می‌آید، و هر خطا کجا دیده می‌شود، در چرخهٔ صورتحساب آمده است.

02شروع

چرخهٔ صورتحساب: از درخواست تا پاسخ سازمان

هر صورتحساب شش مرحله را طی می‌کند و ممکن است در سه مرحله رد شود. این نمودار نشان می‌دهد هر مرحله چیست و نتیجه آن را کجا ببینید.

شش ایستگاه یک صورتحساب، از درخواست تا پاسخ سامانهٔ مؤدیان
  1. درخواست /api/invoice/send یک uuid تازه و ۱ تا ۲۵۰ صورتحساب در data[]، هر کدام با internalId یکتا.
  2. اعتبارسنجی ساختار JSON، قواعد دستورالعمل و جمع‌های مالی؛ هر صورتحساب جدا.
  3. ثبت در معتمد آسا از این لحظه با internalId پیدا می‌شود. پیش‌فاکتور با status: 7 همین‌جا می‌ماند.
  4. بررسی پیش از ارسال کارپوشهٔ فعال، حافظهٔ مالیاتی و قواعد ارسال.
  5. صف و ارسال status: 0 ثبت شده و هنوز به صف ارسال نرفته است؛ status: 1 در صف ارسال یا ارسال‌شده و منتظر پاسخ سامانه مؤدیان.
  6. پاسخ سامانهٔ مؤدیان نتیجهٔ نهایی همان صورتحساب.
اگر…یعنیکار درست
عضوی در پاسخ status: 3 و errors[] داردهمان صورتحساب ثبت نشده است.فیلدی را که path نام برده اصلاح کنید و فقط همان را با uuid تازه دوباره بفرستید (رفتار ثبت گروهی).
پاسخ نرسید (timeout یا قطع ارتباط)معلوم نیست ثبت شده یا نه.اول با internalId استعلام کنید؛ فقط ثبت‌نشده‌ها را دوباره بفرستید.
استعلام status: 1 می‌دهدصورتحساب در صف ارسال است یا سامانه مؤدیان هنوز پاسخ نداده است.چند دقیقه بعد دوباره استعلام کنید و صورتحساب را دوباره نفرستید.
استعلام status: 0 می‌دهدصورتحساب ثبت شده ولی هنوز در صف ارسال قرار نگرفته است. صورتحسابی که با send: false یا با ارسال خودکار خاموش ثبت شده باشد، تا ارسال دستی در همین وضعیت می‌ماند.اگر صورتحساب با send: false یا با ارسال خودکار خاموش ثبت شده است، آن را با /api/invoice/sendInvoice بفرستید؛ ثبت دوباره لازم نیست. در غیر این صورت چند دقیقه بعد دوباره استعلام کنید.
صورتحسابی که سامانهٔ مؤدیان پذیرفته باید تغییر کندخود آن عوض نمی‌شود.صورتحساب اصلاحی، ابطالی یا برگشت از فروش بفرستید (ویرایش و اصلاح، ابطال).

محل دیدن خطای هر مرحله، و جایی که کارگزار همه آن‌ها را یک‌جا می‌بیند، در محل دیدن خطاها آمده است.

03احراز هویت و امنیت

احراز هویت

هر درخواست با یک Access Token کوتاه‌مدت فرستاده می‌شود. توکن را نرم‌افزار شما با client_id و client_secret (الگوی client_credentials) می‌گیرد، تا نزدیک پایان ۶۰ دقیقه برای همهٔ درخواست‌ها به کار می‌برد و بعد توکن تازه می‌گیرد. کلید ثابت قدیمی فقط تا پایان دورهٔ مهاجرت پذیرفته می‌شود.

گرفتن و به‌کاربردن توکنیک توکن برای همهٔ درخواست‌های ۶۰ دقیقه؛ نه یک توکن برای هر درخواست.
  1. سرور شما ← صدور توکندرخواست توکنclient_id + client_secret + scope
  2. صدور توکن ← سرور شماتوکن ۶۰ دقیقه‌ایaccess_token · expires_in: 3600
  3. سرور شما ← سرویس‌های APIهر درخواست با همان توکنAuthorization: Bearer <AccessToken>
  4. سرویس‌های API ← سرور شماپاسختوکن نامعتبر یا scope ناکافی: در /api/invoice/* و /api/register مقدار result: -1، در /api/v2/* پاسخ 401 یا 403
  5. سرور شمانزدیک پایان اعتبارتوکن تازه بگیرید و جایگزین کنید
محل دریافت Client ID و Client Secret: وارد پنل کنترل معتمد آسا شوید، از منوی «کسب‌وکارها» کسب‌وکار موردنظر را انتخاب کنید و در «تنظیمات ← اتصال API v2» اعتبارنامه را صادر کنید. مسیر مستقیم هر کسب‌وکار نیز /apps/taxpayer-management/setting/{companyId}/api-v2 است. مقدار Client Secret فقط هنگام صدور یا چرخش نمایش داده می‌شود؛ همان لحظه آن را در Secret Manager سرور ذخیره کنید. اعتبارنامهٔ همکار (کارگزار) از «پیشخوان همکاری › سلامت اتصال» صادر می‌شود (اعتبارنامه همکار و اعتبارنامه مشتری).
HTTP Header
Authorization: Bearer <AccessToken>
Content-Type: application/json; charset=utf-8
روشمحل استفادهتوضیح
Access Tokenهمه endpointهاتوکن کوتاه‌مدت JWT که با client_id/client_secret گرفته می‌شود و بر اساس scope کنترل می‌شود.
Partner API Key legacy—دیگر پذیرفته نمی‌شود. کارگزار فقط با اعتبارنامهٔ همکار کار می‌کند (راهنمای کارگزاران API).
Customer API Key legacy/api/invoice/*فقط تا پایان ۱۰ آذر ۱۴۰۵ به وقت تهران (2026-12-01T20:30:00Z) فعال است. این مهلت نهایی است و تمدید نمی‌شود.
هشدار پایانی: اگر اتصال شما هنوز با Customer API Key انجام می‌شود، فقط تا پایان ۱۰ آذر ۱۴۰۵ به وقت تهران (2026-12-01T20:30:00Z) کار می‌کند. این مهلت نهایی است و تمدید نمی‌شود. API v1 نیز در همان لحظه غیرفعال می‌شود و از آن پس هر درخواست به آن با خطای 410 رد می‌شود. Partner API Key دیگر در هیچ مسیری پذیرفته نمی‌شود. پاسخ‌های legacy هدرهای Deprecation، Sunset و Warning دارند. پیاده‌سازی جدید باید از Access Token استفاده کند.

دریافت یا چرخش client credentials

روش اصلی این است که مدیر کسب‌وکار از «پنل کنترل معتمد آسا ← کسب‌وکارها ← تنظیمات ← اتصال API v2» اعتبارنامه را صادر یا Client Secret را بچرخاند. Client ID همیشه در همان صفحه قابل مشاهده است، اما client_secret فقط یک‌بار نمایش داده می‌شود؛ آن را در secret store نگه‌داری کنید و در کد، مرورگر یا لاگ ثبت نکنید.

مسیر موقت مهاجرت برای اتصال‌های قدیمی

اگر یک اتصال قدیمی از قبل Customer API Key معتبر دارد، تا پایان مهلت مهاجرت می‌تواند با سرویس زیر اعتبارنامه تازه همان مشتری را بسازد؛ هر فراخوانی با rotate_secret: true یک Client Secret تازه می‌سازد. credential_type: "partner" دیگر پذیرفته نمی‌شود؛ اعتبارنامهٔ همکار فقط از «پیشخوان همکاری» صادر می‌شود. برای راه‌اندازی‌های جدید از پنل کنترل استفاده کنید.

POST /api/auth/v2/client-credentials
curl -X POST "https://api-v2.asatsp.ir/api/auth/v2/client-credentials" \
  -H "Authorization: Bearer <CustomerApiKey>" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "credential_type": "customer",
    "rotate_secret": false
  }'

اگر برای این کسب‌وکار پیش‌تر اعتبارنامه ساخته شده باشد (مثلاً هنگام ثبت با /api/register)، با rotate_secret: false مقدار client_secret در پاسخ null است. برای گرفتن Client Secret تازه rotate_secret: true بفرستید و پیش از آن هشدار مهاجرت از کلید ثابت را بخوانید، چون Client Secret قبلی برای همه نرم‌افزارهای این کسب‌وکار از کار می‌افتد. اگر کلید ثابت شما دو بخش دارد (بخشی در Authorization و بخش دیگر در فیلد token بدنه)، همان token را در بدنه این درخواست هم بفرستید: {"credential_type": "customer", "rotate_secret": true, "token": "<AgencyToken>"}.

پاسخ client-credentials
{
  "credential_type": "customer",
  "client_id": "v2-customer-12345",
  "client_secret": "<shown-only-once>",
  "service_name": "API v2 Customer - 14000000001",
  "allowed_scopes": "v2.invoice.cancel v2.invoice.read v2.invoice.send v2.lookup.read",
  "token_endpoint": "/api/auth/v2/token",
  "expires_in": 3600,
  "created": false,
  "rotated": true,
  "warning": "ClientSecret is shown only once. Store it securely and never log it."
}

پاسخ ممکن است فیلدهای دیگری هم داشته باشد؛ فیلد ناشناخته را نادیده بگیرید. پاسخ‌های خطای این سرویس:

  • HTTP 400 با {"error":"https_required"}: درخواست با http فرستاده شده است.
  • HTTP 400 با {"Message":"invalid_request"}: credential_type فرستاده نشده است؛ با {"Message":"invalid_credential_type"}: مقدار credential_type نامعتبر است.
  • HTTP 401 با {"error":"invalid_legacy_api_key","message":"…"}: کلید ثابت نادرست است، کسب‌وکار غیرفعال است، credential_type: "partner" فرستاده شده یا مهلت کلید ثابت به پایان رسیده است.
  • HTTP 403 با {"error":"ip_not_allowed","code":"IP_NOT_ALLOWED","error_description":"…"}، همان پاسخ دریافت توکن: «محدودیت IP» کسب‌وکار روشن است و نشانی سرور شما در فهرست نیست (محدودیت IP).

دریافت Access Token

توکن‌ها کوتاه‌مدت هستند و مقدار پیش‌فرض انقضا ۶۰ دقیقه است. اگر scope ارسال نشود، همه scopeهای مجاز همان client استفاده می‌شود.

POST /api/auth/v2/token
curl -X POST "https://api-v2.asatsp.ir/api/auth/v2/token" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "v2-customer-12345",
    "client_secret": "<client_secret>",
    "scope": "v2.invoice.send v2.invoice.read"
  }'
پاسخ 200 دریافت توکن
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "v2.invoice.read v2.invoice.send"
}

مقدارهای scope را می‌توانید با فاصله، «,»، «;» یا «|» جدا کنید؛ پاسخ آن‌ها را به ترتیب الفبا و با فاصله برمی‌گرداند.

پاسخ‌های خطای دریافت توکن

HTTPبدنهعلتاقدام
400{"error":"https_required"}درخواست با http فرستاده شده است.فقط به https://api-v2.asatsp.ir بفرستید.
400{"Message":"invalid_request"}بدنه خالی است، grant_type دقیقاً client_credentials با حروف کوچک نیست، یا client_id یا client_secret خالی است.بدنه را اصلاح کنید.
401بدون بدنهclient_id ناشناخته، client_secret نادرست، اعتبارنامه باطل یا غیرفعال، یا کسب‌وکار غیرفعال.درخواست را تکرار نکنید؛ اعتبارنامه را در پنل بررسی کنید.
403{"error":"ip_not_allowed","code":"IP_NOT_ALLOWED",…}«محدودیت IP» روشن است و نشانی سرور شما در فهرست نیست.نشانی را در پنل اضافه کنید (محدودیت IP).
403{"error":"invalid_scope"}scope خواسته‌شده در اعتبارنامه نیست (مثلاً v2.invoice.send با اعتبارنامه همکار) یا قالب آن نادرست است.scope را اصلاح یا حذف کنید.
429{"error":"rate_limited"}بیش از ۳۰ درخواست توکن در یک دقیقه از یک client_id و یک نشانی IP؛ این سقف پیش از بررسی اعتبارنامه سنجیده می‌شود و درخواست‌های ناموفق را هم می‌شمارد.۶۰ ثانیه صبر کنید (پاسخ سرآیند Retry-After ندارد) و توکن را تا نزدیک پایان اعتبار نگه دارید.
Scopeکاربرد
v2.registerفقط اعتبارنامه همکار: ثبت یا به‌روزرسانی مشتری (/api/register)، لینک موقت ثبت‌نام، رویدادها و گزارش‌های همکار (/api/v2/partner/*) و دریافت شناسه یکتای حافظه برای مؤدی تازه (/api/v2/tax-workspace/onboarding/*).
v2.invoice.sendثبت صورتحساب (JSON سازمان و مدل ساده)، ارسال دستی، ویرایش، ثبت پرداخت، ثبت وضعیت اعلامیه فروش بورس و کارهای کارپوشه مالیاتی که چیزی را تغییر می‌دهند، مانند گرفتن دسترسی کارپوشه و شناسه یکتای حافظه.
v2.invoice.cancelابطال صورتحساب.
v2.invoice.readپیگیری وضعیت (با internalId، شماره یا taxId)، استعلام پرداخت، استعلام وضعیت اعلامیه فروش بورس و خواندن کارپوشه مالیاتی.
v2.lookup.readفهرست واحدها و ارزها، مشخصات شناسه کالا/خدمت (/api/v2/stuffid/{code}) و استعلام پرونده مالیاتی (/api/v2/tax-file-inquiry).

/api/v2/client/ip-access با هر توکن معتبر مشتری کار می‌کند و scope خاصی نمی‌خواهد.

04احراز هویت و امنیت

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

اتصال به API نسخه ۲ با استاندارد OAuth 2.0 و اعتبارنامه‌ای انجام می‌شود که از پنل برای کسب‌وکار خود صادر می‌کنید. در این بخش می‌بینید آسا چگونه از اعتبارنامه و درخواست‌های شما محافظت می‌کند و تیم فنی شما برای امن ماندن اتصال چه کارهایی باید انجام دهد.

  • احراز هویت استاندارد OAuth 2.0

    نرم‌افزار شما با client_id و client_secret از مسیر POST /api/auth/v2/token یک Access Token از نوع JWT می‌گیرد که به‌طور پیش‌فرض ۶۰ دقیقه اعتبار دارد. هر فراخوانی این توکن را در هدر Authorization: Bearer می‌فرستد و هر سرویس فقط با scope لازم خودش پذیرفته می‌شود.

  • Client Secret قوی که یک بار نمایش داده می‌شود

    Client Secret یک مقدار تصادفی ۲۵۶ بیتی است و فقط یک بار، هنگام صدور یا چرخش، نمایش داده می‌شود؛ در پنل: تنظیمات کسب‌وکار ← زبانه «اتصال API v2». همان لحظه آن را در جای امنی روی سرور ذخیره کنید.

  • نزد آسا فقط هش آن می‌ماند

    آسا خود Client Secret را ذخیره نمی‌کند؛ فقط هش آن با PBKDF2-SHA256 (۱۵۰٬۰۰۰ تکرار و salt تصادفی ۳۲ بایتی) نگه‌داری می‌شود و مقایسه در زمان ثابت انجام می‌شود. بنابراین هیچ‌کس در معتمد آسا نمی‌تواند Client Secret را بخواند. اگر Client Secret را در اختیار ندارید، Client Secret تازه بسازید.

  • چرخش فوری Client Secret

    با دکمه «چرخش Client Secret» در همان زبانه، مقدار تازه صادر می‌شود و مقدار قبلی از همان لحظه دیگر توکن تازه نمی‌گیرد. توکن‌هایی که پیش از چرخش گرفته شده‌اند تا پایان اعتبارشان کار می‌کنند. هر کسب‌وکار یک اعتبارنامه مشتری دارد؛ پس مقدار قبلی برای همه نرم‌افزارهای این کسب‌وکار، از جمله نرم‌افزار کارگزار، از کار می‌افتد.

  • سقف درخواست توکن

    درخواست توکن به‌طور پیش‌فرض برای هر Client ID و نشانی IP حداکثر ۳۰ بار در دقیقه پذیرفته می‌شود و درخواست‌های بیشتر با HTTP 429 رد می‌شوند.

  • اعتبارنامه باطل‌شده کار نمی‌کند

    اعتبارنامه‌ای که باطل یا غیرفعال شده باشد نه توکن تازه می‌گیرد و نه توکن‌هایی که پیش‌تر گرفته است در فراخوانی سرویس‌ها پذیرفته می‌شوند. ثبت مشتری (/api/register) و مسیرهای دیگر آن را دوباره فعال نمی‌کنند: پاسخ ثبت مشتری در serviceAuth مقدار active: false را با توضیح برمی‌گرداند و مسیر client-credentials پاسخ 409 با کد client_revoked می‌دهد. فقط مدیر کسب‌وکار در پنل («تنظیمات ← اتصال API v2») آن را دوباره فعال می‌کند و در این حالت همیشه Client Secret تازه صادر می‌شود.

  • گزارش‌ها بدون اطلاعات محرمانه

    در گزارش‌هایی که آسا از درخواست‌ها نگه می‌دارد، مقدار فیلدهای محرمانه مانند Client Secret، توکن، API Key و رمز عبور پیش از ذخیره پوشانده می‌شود.

  • آزمایش جدا در Sandbox

    صورتحسابی که با sandBox: true ثبت شود فقط با شناسه حافظه مالیاتی Sandbox پذیرفته و به محیط آزمایشی سازمان امور مالیاتی فرستاده می‌شود؛ شناسه Production در درخواست Sandbox پذیرفته نمی‌شود. بنابراین آزمایش‌ها به محیط عملیاتی نمی‌رسند.

  • محدودیت IP

    در همان زبانه «اتصال API v2» می‌توانید «محدودیت IP» را روشن کنید تا اعتبارنامه کسب‌وکار فقط از نشانی‌های سرور خودتان پذیرفته شود (IPv4، IPv6 یا بازه CIDR؛ حداکثر ۲۰ مورد). از نشانی دیگر نه توکن صادر می‌شود و نه توکن قبلی پذیرفته می‌شود؛ پاسخ HTTP 403 با کد IP_NOT_ALLOWED است (جزئیات).

توصیه‌های امنیتی برای تیم فنی شما

  • Client Secret را فقط در سمت سرور نگه دارید؛ هرگز آن را در کد مرورگر، اپلیکیشن موبایل یا نرم‌افزاری که روی دستگاه کاربر نصب می‌شود قرار ندهید.
  • Client Secret را در Secret Store یا متغیر محیطی سرور ذخیره کنید؛ نه در کد منبع، مخزن Git، فایل تنظیمات مشترک یا لاگ.
  • همه درخواست‌ها را فقط با HTTPS و به نشانی https://api-v2.asatsp.ir بفرستید.
  • اگر احتمال می‌دهید Client Secret لو رفته است، بی‌درنگ آن را در پنل بچرخانید و مقدار تازه را در سرور جایگزین کنید.
  • توکن را تا نزدیک پایان اعتبارش نگه دارید و دوباره به کار ببرید و فقط scopeهایی را بخواهید که واقعاً لازم دارید.
  • آزمایش‌ها را در Sandbox و با شناسه حافظه مالیاتی Sandbox انجام دهید.
  • Client Secret یا توکن را برای هیچ‌کس، حتی پشتیبانی آسا، نفرستید؛ برای پیگیری، traceId و uuid درخواست کافی است.
مهلت نهایی API v1 و کلیدهای ثابت قدیمی: API v1 و Customer API Key فقط تا پایان ۱۰ آذر ۱۴۰۵ به وقت تهران (2026-12-01T20:30:00Z) کار می‌کنند و این مهلت تمدید نمی‌شود. Partner API Key دیگر پذیرفته نمی‌شود. اگر اتصال شما هنوز با API v1 یا کلید ثابت است، پیش از این تاریخ آن را به Access Token منتقل کنید (احراز هویت).

جزئیات بیشتر درباره نگه‌داری اطلاعات در حریم خصوصی و محرمانگی اطلاعات آمده است.

05کارگزاران API

راهنمای کارگزاران API

کارگزار نرم‌افزاری است (حسابداری، فروشگاهی یا ERP) که مشتریان خودش را در معتمد آسا ثبت می‌کند و صورتحساب هر کدام را از راه API نسخه ۲ می‌فرستد. همهٔ کار کارگزار در همین بخش است: دو شماتیک اتصال، راه‌اندازی، دو اعتبارنامه، مهاجرت از کلید ثابت، جای هر خطا، و پایش در «پیشخوان همکاری».

فقط روش این راهنما: کارگزار فقط با اعتبارنامهٔ همکار و اعتبارنامهٔ هر مشتری کار می‌کند. Partner API Key دیگر در هیچ مسیری پذیرفته نمی‌شود و پاسخ ثبت مشتری هم کلید ثابت (customerApiKey) نمی‌دهد. Customer API Keyهایی که پیش‌تر گرفته‌اید فقط تا پایان ۱۰ آذر ۱۴۰۵ به وقت تهران (2026-12-01T20:30:00Z) کار می‌کنند و این مهلت تمدید نمی‌شود؛ پس از آن هر درخواستی که با آن‌ها بیاید با خطای احراز هویت رد می‌شود (در مسیرهای صورتحساب result: -1) و ثبت نمی‌شود. راه مهاجرت در مهاجرت از کلید ثابت آمده است.

شماتیک اتصال کارگزار

اتصال خود کارگزار یک بار انجام می‌شود: ثبت همکاری، صدور اعتبارنامهٔ همکار و یک آزمایش. از آن پس هر مشتری با یکی از دو مسیر اتصال مشتری اضافه می‌شود.

اتصال کارگزار به معتمد آسایک بار برای هر کارگزار.
  1. کارگزار ← پشتیبانیدرخواست همکاریکسب‌وکار کارگزار در معتمد آسا ثبت شده است
  2. پشتیبانیثبت در «همکاران API»دسترسی‌ها و دامنه‌های مجاز بازگشت
  3. کارگزار ← پنلصدور اعتبارنامهٔ همکارکاربر با دسترسی کامل، «سلامت اتصال › صدور اعتبارنامه»
  4. پنل ← کارگزاراعتبارنامهٔ همکارv2-partner-{شناسه} + client_secretclient_secret فقط همین یک بار نمایش داده می‌شود
  5. کارگزار ← APIگرفتن توکن همکارPOST /api/auth/v2/token · scope: v2.register
  6. API ← کارگزارتوکن ۶۰ دقیقه‌ایaccess_token
  7. کارگزار ← APIآزمایش اتصالGET /api/v2/partner/profile · POST /api/v2/partner/webhook/test

شماتیک اتصال مشتری از طریق کارگزار

هر مشتری از یکی از دو مسیر به معتمد آسا وصل می‌شود. نتیجهٔ هر دو یکی است: کسب‌وکار مشتری با حافظهٔ مالیاتی‌اش ثبت می‌شود و کارگزار اعتبارنامهٔ همان مشتری را برای ارسال صورتحساب دارد.

مسیرکیمؤدی چه می‌کند
الف. ثبت مستقیم با /api/registerکارگزار اطلاعات مشتری و شناسهٔ حافظهٔ مالیاتی را دارد و کسب‌وکار پیش‌تر در معتمد آسا ثبت نشده است.کاری لازم نیست.
ب. لینک موقت ثبت‌نامپاسخ ثبت مستقیم business_registered_elsewhere است، یا می‌خواهید خود مالک با تأیید سامانهٔ مؤدیان اجازه بدهد.با موبایل وارد می‌شود و مالکیت را با رمز سامانهٔ مؤدیان تأیید می‌کند.
مسیر الف: ثبت مستقیم مشتریاز ثبت مشتری تا پاسخ سازمان به نخستین صورتحساب.
  1. کارگزار ← APIثبت مشتری با توکن همکارPOST /api/register
  2. API ← سامانهٔ مؤدیانبررسی حافظهٔ مالیاتی و کارپوشهکسب‌وکار مشتری ساخته یا به‌روز می‌شود
  3. API ← کارگزاراعتبارنامهٔ مشتریserviceAuth: v2-customer-{شناسه} + client_secretفقط وقتی کسب‌وکار پیش‌تر اعتبارنامه نداشته باشد؛ در Secret Manager نگه دارید
  4. کارگزار ← APIتوکن مشتری، سپس ارسال صورتحسابPOST /api/invoice/send
  5. API ← کارگزارنتیجهٔ هر صورتحساب در همان پاسخdata[] · errors[]ثبت‌شده، یا ردشده پیش از ثبت با مسیر فیلد
  6. API ← صف ارسالصورتحساب ثبت‌شده به صف می‌رودبا send یا تنظیم ارسال خودکار کسب‌وکار
  7. صف ارسال ← سامانهٔ مؤدیانارسال به سامانهٔ مؤدیان
  8. سامانهٔ مؤدیان ← صف ارسالپاسخ سازمانپذیرفته، یا رد با کد خطای سازمان
  9. کارگزار ← APIپیگیری نتیجهPOST /api/invoice/inquiry*یا در «پیشخوان همکاری»
مسیر ب: لینک موقت ثبت‌نام با رضایت مالککارگزار هیچ رمز یا اطلاعات هویتی را خودش جمع نمی‌کند.
  1. کارگزار ← APIساخت لینک با توکن همکارPOST /api/v2/partner/onboarding-sessionsبا requestCredentials: true، اگر اعتبارنامهٔ مشتری را می‌خواهید
  2. API ← کارگزارلینک موقت201 · url
  3. کارگزار ← مؤدیرساندن لینک به مؤدیمثل یک رمز؛ لینک به نخستین کاربری که وارد شود گره می‌خورد
  4. مؤدی ← سامانهٔ مؤدیانورود با موبایل و تأیید مالکیتبا رمزی که سامانهٔ مؤدیان به موبایل ثبت‌شده در کارپوشه می‌فرستد
  5. مؤدیساخت پنل و شناسهٔ یکتای حافظهو رضایت برای تحویل اعتبارنامه
  6. مؤدی ← کارگزاربازگشت به نشانی کارگزارreturnUrl?session_id=…&status=completed
  7. API ← کارگزاروبهوک یا فهرست رویدادهاonboarding.session.business_ready
  8. کارگزار ← APIتحویل یک‌بارهٔ اعتبارنامهٔ مشتریPOST …/onboarding-sessions/{sessionId}/credentials
  9. API ← کارگزاراعتبارنامهٔ مشتریclientId + clientSecretاز اینجا مثل مسیر الف: توکن مشتری و ارسال صورتحساب

جزئیات هر قدم در ادامه آمده است؛ لینک موقت ثبت‌نام در بخش خودش با همهٔ فیلدها، وضعیت‌ها و امضای وبهوک توضیح داده شده است.

راه‌اندازی در هفت قدم

ثبت در «همکاران API» پشتیبانی معتمد آسا کسب‌وکار شما را به‌عنوان همکار ثبت می‌کند و دسترسی‌های لازم را روشن می‌کند: ثبت مستقیم مشتری با /api/register، لینک موقت ثبت‌نام، و تحویل اعتبارنامهٔ مشتری پس از رضایت مالک. دامنه‌های مجاز نشانی بازگشت را پشتیبانی ثبت می‌کند؛ نشانی وبهوک و کلید امضای آن را کاربر با دسترسی کامل در «پیشخوان همکاری» هم می‌تواند تنظیم کند.
اعتبارنامهٔ همکار کاربری با دسترسی کامل کسب‌وکار همکار در پنل معتمد آسا، «پیشخوان همکاری › سلامت اتصال» را باز می‌کند و «صدور اعتبارنامه» را می‌زند. client_id به شکل v2-partner-{شناسه کسب‌وکار همکار} است و client_secret فقط همان لحظه نمایش داده می‌شود. اگر کاربری با دسترسی کامل ندارید، پشتیبانی معتمد آسا اعتبارنامه را در «همکاران API» صادر می‌کند. اعتبارنامهٔ همکار از راه دیگری (مثلاً با کلید ثابت قدیمی) گرفته نمی‌شود.
توکن همکار با POST /api/auth/v2/token و scope v2.register توکن ۶۰ دقیقه‌ای بگیرید و تا نزدیک پایان اعتبارش دوباره به کار ببرید (احراز هویت).
ثبت مشتری مشتری را با توکن همکار و /api/register ثبت کنید. اگر کسب‌وکار را خود مالک یا همکار دیگری ثبت کرده باشد، پاسخ business_registered_elsewhere است؛ در این حالت، یا وقتی می‌خواهید مالک خودش با رمز سامانهٔ مؤدیان اجازه بدهد، لینک موقت ثبت‌نام بسازید.
اعتبارنامهٔ هر مشتری پاسخ نخستین ثبت هر مشتری، serviceAuth را با client_id به شکل v2-customer-{شناسه کسب‌وکار} و client_secret دارد. اگر کسب‌وکار پیش‌تر اعتبارنامه داشته باشد، در همان ثبت نخست و در همه ثبت‌های بعدی client_secret برابر null است. اگر Client Secret را نگه نداشته‌اید و Customer API Key همان مشتری را دارید، تا پایان مهلت کلید ثابت می‌توانید آن را از مسیر مهاجرت دوباره بسازید؛ پس از آن، مالک کسب‌وکار در «تنظیمات › اتصال API v2» پنل خود Client Secret تازه می‌سازد و به شما می‌دهد. لینک ثبت‌نام با requestCredentials فقط برای کسب‌وکاری Client Secret تحویل می‌دهد که هنوز اعتبارنامه ندارد.
ارسال صورتحساب صورتحساب‌های هر مشتری را با توکن همان مشتری (scope v2.invoice.send) به /api/invoice/send یا مسیرهای مدل ساده بفرستید. توکن هر کسب‌وکار فقط برای همان کسب‌وکار کار می‌کند.
پیگیری و پایش نتیجهٔ هر صورتحساب را با پیگیری وضعیت بگیرید، رویدادها را از وبهوک یا فهرست رویدادها بخوانید و کار همهٔ مشتریان را در «پیشخوان همکاری» یا گزارش‌های API همکار ببینید.

اعتبارنامه همکار و اعتبارنامه مشتری

اعتبارنامهclient_idscopeبرایاز کجا
همکار (Partner)v2-partner-{شناسه کسب‌وکار همکار}v2.registerثبت مشتری، لینک موقت ثبت‌نام، فهرست رویدادها، وبهوک آزمایشی و گزارش‌های همکاری (/api/v2/partner/*)«پیشخوان همکاری › سلامت اتصال» یا پشتیبانی معتمد آسا
مشتری (Customer)v2-customer-{شناسه کسب‌وکار مشتری}v2.invoice.send، v2.invoice.cancel، v2.invoice.read، v2.lookup.readثبت، ارسال، ابطال و پیگیری صورتحساب‌های همان مشتریserviceAuth نخستین ثبت؛ تحویل در لینک ثبت‌نام (فقط برای کسب‌وکاری که هنوز اعتبارنامه ندارد)؛ «اتصال API v2» پنل مالک؛ تا پایان مهلت، با Customer API Key همان مشتری

توکن همکار برای ثبت صورتحساب پذیرفته نمی‌شود و توکن مشتری برای مسیرهای همکار؛ هر کدام را برای کار خودش بگیرید. هر دو client_secret را مثل رمز، فقط در Secret Manager سرور نگه دارید. هر کسب‌وکار فقط یک اعتبارنامه مشتری دارد؛ اگر Client Secret آن را بچرخانید، مقدار قبلی برای همه نرم‌افزارهایی که با همین اعتبارنامه کار می‌کنند، از جمله نرم‌افزار خود مالک، از کار می‌افتد.

مهاجرت از کلید ثابت

Partner API Key دیگر در هیچ مسیری پذیرفته نمی‌شود. Customer API Keyهایی که پیش‌تر برای مشتریان گرفته‌اید تا پایان مهلت کار می‌کنند و پاسخ‌ها هدرهای Deprecation، Sunset و Warning دارند. پیش از پایان مهلت، این چهار کار را انجام دهید:

  1. اعتبارنامهٔ همکار را از «پیشخوان همکاری › سلامت اتصال» صادر کنید (قدم دوم راه‌اندازی) و ثبت مشتری و مسیرهای همکار را با توکن آن بفرستید.
  2. برای هر مشتری، با Customer API Key همان مشتری، POST /api/auth/v2/client-credentials را با {"credential_type": "customer", "rotate_secret": true} بفرستید. rotate_secret لازم است چون اعتبارنامهٔ بیشتر مشتریان هنگام ثبت ساخته شده و client_secret آن دوباره نمایش داده نمی‌شود؛ با آن، client_secret تازه صادر و قبلی باطل می‌شود (توکن‌های صادرشده تا پایان ۶۰ دقیقه خودشان معتبر می‌مانند). هشدار: هر کسب‌وکار فقط یک اعتبارنامه مشتری دارد (v2-customer-{شناسه کسب‌وکار}) و همه نرم‌افزارهای آن کسب‌وکار، از جمله نرم‌افزار خود مالک یا کارگزار دیگر، همان را به کار می‌برند. با rotate_secret: true، Client Secret قبلی برای همه آن‌ها از کار می‌افتد. پیش از چرخش با مالک هماهنگ کنید و چرخش را فقط برای کسب‌وکارهایی انجام دهید که هنوز با کلید ثابت کار می‌کنند؛ فهرست آن‌ها در data.legacyKeys.businesses پاسخ GET /api/v2/partner/reports/overview است.
  3. هر client_id و client_secret را کنار شناسهٔ کسب‌وکار در Secret Manager نگه دارید.
  4. در کد، به‌جای کلید ثابت، توکن هر اعتبارنامه را در Authorization: Bearer بفرستید. بدنهٔ هیچ درخواستی عوض نمی‌شود.
دریافت اعتبارنامهٔ یک مشتری با Customer API Key آن (فقط تا پایان مهلت)
curl -X POST "https://api-v2.asatsp.ir/api/auth/v2/client-credentials" \
  -H "Authorization: Bearer <CustomerApiKey>" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{ "credential_type": "customer", "rotate_secret": true }'

تا وقتی کسب‌وکاری از شما در هفت روز گذشته بدون Access Token صورتحساب فرستاده باشد، «پیشخوان همکاری › نمای کلی» یافتهٔ «کلید ثابت قدیمی مشتریان تا پایان … کار می‌کند» را با تعداد آن کسب‌وکارها نشان می‌دهد. پس از پایان مهلت، این مسیر بسته می‌شود و Client Secret تازه مشتری را فقط مالک کسب‌وکار در «اتصال API v2» پنل خود می‌سازد. لینک ثبت‌نام فقط برای کسب‌وکاری اعتبارنامه می‌سازد که هنوز اعتبارنامه ندارد.

همین فهرست را از API هم می‌گیرید: پاسخ GET /api/v2/partner/reports/overview (و /reports/health) در data.legacyKeys برای هر کسب‌وکاری که در هفت روز گذشته بدون Access Token درخواست فرستاده است، این موارد را دارد:

data.legacyKeys در پاسخ گزارش نمای کلی
"legacyKeys": {
  "sunsetUtc": "…",
  "lastDay": "…",
  "partnerKeyRefused": false,
  "businesses": [
    { "companyId": 50123, "name": "فروشگاه نمونه", "calls": 412, "lastCallAt": "…", "hasCredentials": true }
  ]
}

hasCredentials: true یعنی کسب‌وکار اعتبارنامه API نسخه ۲ دارد ولی درخواست‌ها هنوز با کلید ثابت می‌آیند.

محل دیدن خطاها

یک صورتحساب در سه مرحله ممکن است رد شود و هر مرحله جای خودش را دارد:

مرحلهکجا دیده می‌شودچه باید کرد
۱. ردشده پیش از ثبت (اعتبارسنجی درخواست)در پاسخ همان درخواست: errors[] با path و message، و status: 3 برای عضو ردشده. این صورتحساب ثبت نشده و استعلامی ندارد. همه را در «پیشخوان همکاری › خطاها › ردشده پیش از ثبت» و GET /api/v2/partner/reports/rejections هم می‌بینید و هشدار rejected_requests هم برایش باز می‌شود.فیلدی را که path نام برده اصلاح کنید و همان عضو را با همان internalId دوباره بفرستید؛ چون ثبت نشده، تکراری نیست.
۲. ثبت‌شده، ردشده پیش از ارسالصورتحساب ثبت شده ولی بررسی پیش از ارسال آن را نپذیرفته است: در پیگیری وضعیت، در «خطاها» (منشأ «بررسی پیش از ارسال») و /api/v2/partner/reports/errors.با ویرایش صورتحساب یا از پنل اصلاح و دوباره ارسال کنید.
۳. پاسخ سامانهٔ مؤدیانسازمان صورتحساب را با کد خطا رد کرده است: در پیگیری وضعیت، در «خطاها» با کد رسمی، در /api/v2/partner/reports/errors و هشدار error_rate.طبق کد خطا اصلاح کنید؛ برای صورتحساب پذیرفته‌شده، اصلاح و ابطال فقط با صورتحساب اصلاحی یا ابطالی است.
ارسال تکراری ردشده نیست: پیام «internalId ارسالی قبلاً برای این شرکت ثبت شده است» یعنی این صورتحساب پیش‌تر ثبت شده است. این پاسخ‌ها جزو ردشده‌ها شمرده نمی‌شوند و جدا در duplicates می‌آیند. به‌جای ارسال دوباره، وضعیت آن را با internalId استعلام کنید (قاعده تکرار امن درخواست).
پشتیبانی آسا هم باخبر می‌شود: هر صورتحسابی که از کسب‌وکارهای همکار پیش از ثبت رد شود، اعتبارنامه‌ای که به کسب‌وکاری واقعی برمی‌گردد ولی پذیرفته نشود (کلید ثابت پس از مهلت، client_secret نادرست یا باطل‌شده، کسب‌وکار غیرفعال) و قطع شدن ارسال‌های همیشگی یک همکار، در چند دقیقه به پشتیبانی آسا هم خبر داده می‌شود. پاسخ شما همان پاسخ همیشگی است (برای اعتبارنامه فقط 401)؛ هیچ کلید، رمز یا توکنی جایی نوشته نمی‌شود.

پایش و گزارش در «پیشخوان همکاری»

کاربران کسب‌وکار همکار در پنل معتمد آسا (my.asatsp.ir) که کسب‌وکار همکار را انتخاب کنند، مستقیم به «پیشخوان همکاری» می‌رسند؛ این بخش در منوی کناری هم هست. دیدن همهٔ بخش‌ها برای همهٔ کاربران آن کسب‌وکار باز است و تغییر وبهوک، کلید امضا و اعتبارنامه فقط برای کاربر با دسترسی کامل. بازه هر بخش فصل، ماه، سال یا بازه دلخواه شمسی است. اعداد دوره جاری (و فصل قبل تا ۱۵ روز پس از پایان آن) حداکثر دو دقیقه و دوره‌های قدیمی‌تر حداکثر ۳۰ دقیقه پس از هر تغییر به‌روز می‌شوند.

بخشچه نشان می‌دهد
نمای کلیکسب‌وکارها، ثبت‌نام‌ها، صورتحساب‌های API به تفکیک وضعیت، درصد پذیرش، مقایسه با دورهٔ قبل، وبهوک، اعتبارنامه، صورتحساب‌های منتظر پاسخ، تعداد ردشده‌های پیش از ثبت و یافته‌ها؛ هر یافته (مثلاً ردشده‌ها یا کلید ثابت) به بخش مربوط می‌رود.
ثبت‌نام‌هاقیف لینک‌های ثبت‌نام و ثبت‌نام‌های نیمه‌کاره.
کسب‌وکارهاهر کسب‌وکار با صورتحساب‌های بازه، نرخ پذیرش، پرتکرارترین خطا و وضعیت؛ با خروجی Excel.
پیگیری صورتحسابیک صورتحساب با شمارهٔ مالیاتی، UUID یا شماره، با تاریخچهٔ ارسال‌ها.
خطاهادو بخش: خطاهای صورتحساب‌های ثبت‌شده به تفکیک کد رسمی یا متن بررسی پیش از ارسال؛ و «ردشده پیش از ثبت» با علت هر فیلد، کسب‌وکارهای درگیر و ۵۰ مورد آخر با traceId و internalId. هر دو خروجی Excel دارند.
سلامت اتصالصدور و چرخش اعتبارنامهٔ همکار، وبهوک (نشانی، رویداد آزمایشی، کلید امضا، تحویل‌ها و ارسال دوباره)، هشدارهای باز و صورتحساب‌های منتظر پاسخ.
گزارش‌ها و خروجیگزارش ماهانهٔ چندبرگه (Excel و PDF) و کارکرد ماهانهٔ هر کسب‌وکار.
پورسانتپورسانت زیرمجموعه‌ها، پرداخت‌ها و مانده.
سابقهکارهایی که روی همکاری انجام شده است.

چهار هشدار خودکار (error_rate، rejected_requests، result_delay و webhook) هر پنج دقیقه سنجیده می‌شوند و در مرکز اعلان پنل و تلگرام (و طبق تنظیم هر کاربر، پیامک) می‌آیند؛ رویداد باز و بسته شدن آن‌ها هم به وبهوک و فهرست رویدادها فرستاده می‌شود. قاعدهٔ هر هشدار و همهٔ این اعداد از راه API در گزارش‌ها و پایش همکاری آمده است.

چک‌لیست کارگزار

  • اعتبارنامهٔ همکار و اعتبارنامهٔ هر مشتری در Secret Manager، کنار شناسهٔ کسب‌وکار.
  • توکن هر اعتبارنامه تا نزدیک پایان اعتبارش دوباره به کار می‌رود؛ توکن یک مشتری برای مشتری دیگر فرستاده نمی‌شود.
  • internalId هر صورتحساب یکتا و ثابت است و uuid هر درخواست تازه (رفتار ثبت گروهی).
  • errors[] هر پاسخ با traceId در سامانهٔ شما ثبت و به کاربر نشان داده می‌شود؛ اعضای ثبت‌شده دوباره فرستاده نمی‌شوند.
  • امضای وبهوک بررسی و رویداد تکراری با webhook-id کنار گذاشته می‌شود.
  • هشدارهای «پیشخوان همکاری» برای تیم فنی در تلگرام روشن است.
  • آزمایش‌ها با sandBox: true و حافظهٔ Sandbox انجام می‌شود (حافظه مالیاتی و Sandbox).
06کارگزاران API

لینک موقت ثبت‌نام برای نرم‌افزار همکار

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

پیش‌نیاز: کسب‌وکار همکار باید در فهرست همکاران معتمد آسا ثبت و فعال باشد و «لینک موقت ثبت‌نام» برایش روشن باشد. دامنه‌های مجاز نشانی بازگشت را پشتیبانی معتمد آسا ثبت می‌کند. نشانی وبهوک را کاربر با دسترسی کامل در «پیشخوان همکاری › سلامت اتصال» تنظیم می‌کند و کلید امضای آن همان‌جا ساخته و فقط یک بار نمایش داده می‌شود. همه درخواست‌ها با اعتبارنامه همکار و scope v2.register فرستاده می‌شوند. همکاری که معلق شود، در مسیرهای /api/v2/partner/* و /api/v2/tax-workspace/onboarding/* پاسخ HTTP 403 با کد partner_suspended می‌گیرد و در /api/register پاسخ result: -1 با error: "partner_suspended".

روش‌های دریافت نتیجه ثبت‌نام

روشکاربرداعتماد
نشانی بازگشت (returnUrl)برگرداندن مؤدی به صفحه شما با session_id و status.فقط برای نمایش؛ امضا را بررسی کنید و نتیجه را از وبهوک یا خواندن جلسه تأیید کنید.
وبهوک (سرور به سرور)خبر هر مرحله، بی‌درنگ و با تلاش مجدد.امضای HMAC-SHA256 به روش Standard Webhooks.
فهرست رویدادها (GET /api/v2/partner/events)برای همکاری که نشانی عمومی برای وبهوک ندارد، یا برای جبران وبهوک ازدست‌رفته.پاسخ احرازشده API.
خواندن جلسه (GET …/onboarding-sessions/{sessionId})وضعیت لحظه‌ای یک مؤدی، پیش از تحویل خدمت.پاسخ احرازشده API.

Endpointها

MethodEndpointکاربرد
POST/api/v2/partner/onboarding-sessionsساخت لینک موقت برای یک مؤدی؛ پاسخ 201 با url.
GET/api/v2/partner/onboarding-sessionsفهرست جلسه‌ها: status، reference، from، to (ISO-8601)، page، pageSize (حداکثر ۱۰۰).
GET/api/v2/partner/onboarding-sessions/{sessionId}وضعیت یک جلسه، کسب‌وکار ساخته‌شده، شناسه یکتا و آخرین خطای مؤدی.
POST/api/v2/partner/onboarding-sessions/{sessionId}/linkلینک تازه (لینک قبلی همان لحظه باطل می‌شود). بدنه اختیاری: {"expiresInMinutes": 1440}.
POST/api/v2/partner/onboarding-sessions/{sessionId}/cancelلغو جلسه‌ای که پنلش هنوز ساخته نشده است.
POST/api/v2/partner/onboarding-sessions/{sessionId}/credentialsتحویل یک‌باره اعتبارنامه API کسب‌وکار، پس از رضایت مالک.
GET/api/v2/partner/events?after=0&limit=50رویدادهای همکار به ترتیب sequence؛ limit حداکثر ۱۰۰ و پیش‌فرض ۵۰. اگر hasMore برابر true است، صفحه بعد را با after برابر nextAfter بخوانید. وقتی رویداد تازه‌ای نیست، nextAfter برابر null است؛ در این حالت همان after قبلی را نگه دارید.
POST/api/v2/partner/webhook/testرویداد آزمایشی ping به وبهوک (و فهرست رویدادها).
GET/api/v2/partner/profileتنظیمات همکار: دسترسی‌ها، دامنه‌های مجاز، وبهوک و سقف‌ها.
پاسخ GET /api/v2/partner/events
{
  "status": "OK",
  "data": {
    "items": [
      {
        "id": "evt_…",
        "sequence": 1842,
        "type": "onboarding.session.opened",
        "createdAt": "2026-10-18T06:05:00Z",
        "sessionId": "6f1c2d3e-8a4b-4c5d-9e6f-0a1b2c3d4e5f",
        "data": { "…": "…" },
        "delivery": { "status": "delivered", "attempts": 1, "lastStatusCode": 200, "deliveredAt": "2026-10-18T06:05:12Z", "nextAttemptAt": null }
      }
    ],
    "nextAfter": 1842,
    "hasMore": false
  },
  "errors": [],
  "fieldErrors": [],
  "correlationId": "…"
}

delivery.status یکی از no_endpoint، pending، delivered، failed یا cancelled است.

ساخت لینک

POST /api/v2/partner/onboarding-sessions
{
  "economicCode": "14000000001",
  "businessName": "فروشگاه نمونه",
  "mobile": "09120000000",
  "reference": "order-1024",
  "returnUrl": "https://partner.example/onboarding/done",
  "expiresInMinutes": 1440,
  "issueMemoryUniqueId": true,
  "requestCredentials": true,
  "idempotencyKey": "order-1024-onboarding"
}
  • همه فیلدها اختیاری‌اند. با economicCode مؤدی فقط همان کسب‌وکار را می‌تواند ثبت کند؛ با nationalId (۱۰، ۱۱ یا ۱۲ رقم) پرونده‌های او فهرست می‌شود؛ بدون هیچ‌کدام، مؤدی خودش شماره را وارد می‌کند.
  • returnUrl باید https و روی یکی از دامنه‌های مجاز همکار باشد. اگر خالی بماند، نشانی بازگشت پیش‌فرض همکار به کار می‌رود.
  • اعتبار لینک از ۱۰ دقیقه تا ۷ روز است و پیش‌فرض آن را پشتیبانی برای همکار تعیین می‌کند. وقتی مؤدی وارد شود، لینک دست‌کم یک ساعت دیگر باز می‌ماند.
  • idempotencyKey (۸ تا ۶۴ نویسه، یا سرآیند Idempotency-Key): درخواست تکراری همان جلسه را برمی‌گرداند. اگر لینک هنوز باز نشده باشد، لینک تازه می‌دهد و لینک قبلی باطل می‌شود. همان کلید با اطلاعات دیگر پاسخ 409 idempotency_conflict می‌گیرد.
  • mobile فقط در مرحله ورود پیشنهاد می‌شود. ورود و تأیید مالکیت همیشه با خود مؤدی است.
پاسخ 201
{
  "status": "OK",
  "data": {
    "sessionId": "6f1c2d3e-8a4b-4c5d-9e6f-0a1b2c3d4e5f",
    "status": "created",
    "statusTitle": "ساخته شده",
    "reference": "order-1024",
    "url": "https://my.asatsp.ir/join/AbCdEfGhJkMnPqRsTuVwXyZ234567892",
    "createdAt": "2026-10-18T06:00:00Z",
    "expiresAt": "2026-10-19T06:00:00Z",
    "prefill": { "economicCode": "14000000001", "nationalId": null, "businessName": "فروشگاه نمونه", "mobile": "0912•••0000" },
    "issueMemoryUniqueId": true,
    "requestCredentials": true,
    "returnUrl": "https://partner.example/onboarding/done",
    "business": null,
    "memory": null,
    "lastError": null,
    "credentials": { "available": false, "claimed": false, "clientId": null, "claimedAt": null }
  },
  "errors": [],
  "fieldErrors": [],
  "correlationId": "3f2c1d7e9b8a4c6d8e1f0a2b3c4d5e6f"
}

url فقط در همین پاسخ و پاسخ «لینک تازه» می‌آید؛ آن را مثل یک رمز با مؤدی در میان بگذارید. لینک به اولین کاربری که با آن وارد شود گره می‌خورد.

وضعیت جلسه

statusمعنا
createdساخته شده و هنوز باز نشده است.
openedمؤدی لینک را باز کرده است.
in_progressمؤدی وارد شده و در حال ثبت‌نام است. اگر مرحله‌ای رد شود، دلیلش در lastError می‌آید.
business_readyمالکیت تأیید و پنل ساخته شد (یا پنل موجود خود مؤدی کامل شد). اطلاعات آن در business است.
completedکار تمام است: شناسه یکتا گرفته شد، یا مؤدی آن را به بعد گذاشت، یا کسب‌وکار پیش‌تر حافظه داشت، یا همکار شناسه نخواسته بود. پنلی که ساخته شده و مؤدی تا پایان اعتبار لینک برنگشته، خودکار به این وضعیت می‌رود.
expiredاعتبار لینک پیش از ساخت پنل تمام شد.
cancelledهمکار، مؤدی یا پشتیبانی آن را لغو کرد (cancelledBy: partner، taxpayer، administrator).

نشانی بازگشت

در پایان یا هنگام انصراف مؤدی، مرورگر او به returnUrl فرستاده می‌شود و این پارامترها به آن افزوده می‌شوند: session_id، status (completed یا cancelled)، reference، timestamp (ثانیه یونیکس) و signature (فقط وقتی کلید وبهوک ثبت شده باشد). امضا v1, و پس از آن Base64 مقدار HMAC-SHA256 با کلید وبهوک روی رشته {session_id}.{status}.{reference}.{timestamp} است. کلید، بخش پس از whsec_ است که Base64-decode می‌شود. امضا را بررسی کنید، timestamp را بیش از ۵ دقیقه کهنه نپذیرید و نتیجه را با خواندن جلسه تأیید کنید.

وبهوک

هر رویداد با POST و بدنه JSON به نشانی وبهوک همکار فرستاده می‌شود. سرآیندها به روش Standard Webhooks است، پس کتابخانه‌های آماده آن را هم می‌توانید به کار ببرید:

  • webhook-id: شناسه یکتای رویداد (evt_…). رویداد تکراری را با همین شناسه کنار بگذارید.
  • webhook-timestamp: زمان ارسال به ثانیه یونیکس.
  • webhook-signature: v1, و Base64 مقدار HMAC-SHA256 با کلید وبهوک روی {webhook-id}.{webhook-timestamp}.{body}.
  • X-Event-Type: نوع رویداد.
typeزمان
onboarding.session.openedاولین باز شدن لینک.
onboarding.session.business_readyپنل ساخته شد یا پنل موجود مؤدی کامل شد.
onboarding.session.completedجلسه کامل شد؛ اگر شناسه یکتا گرفته شده باشد، در memory می‌آید.
onboarding.session.expiredلینک بی‌آنکه پنلی ساخته شود منقضی شد.
onboarding.session.cancelledجلسه لغو شد.
pingرویداد آزمایشی.
بدنه وبهوک
{
  "type": "onboarding.session.completed",
  "timestamp": "2026-10-18T06:12:30.000Z",
  "data": {
    "sessionId": "6f1c2d3e-8a4b-4c5d-9e6f-0a1b2c3d4e5f",
    "reference": "order-1024",
    "status": "completed",
    "business": { "companyId": 50123, "economicCode": "14000000001", "name": "فروشگاه نمونه", "created": true },
    "memory": { "memoryUniqueId": "A1B2C3", "issued": true },
    "credentialsAvailable": true,
    "cancelledBy": null,
    "expiresAt": "2026-10-19T06:00:00.000Z"
  }
}
بررسی امضای وبهوک و نشانی بازگشت (C#، .NET Framework و .NET)
using System;
using System.Linq;
using System.Security.Cryptography;
using System.Text;

static class AsaWebhook
{
    static byte[] KeyOf(string secret)
    {
        return Convert.FromBase64String(secret.Substring("whsec_".Length));
    }

    static bool FixedTimeEquals(string left, string right)
    {
        byte[] a = Encoding.UTF8.GetBytes(left ?? "");
        byte[] b = Encoding.UTF8.GetBytes(right ?? "");
        int difference = a.Length ^ b.Length;
        for (int i = 0; i < a.Length && i < b.Length; i++)
            difference |= a[i] ^ b[i];
        return difference == 0;
    }

    // webhook-timestamp (یا timestamp نشانی بازگشت) حداکثر پنج دقیقه با زمان حال فاصله داشته باشد.
    public static bool IsFresh(string timestamp)
    {
        long seconds;
        if (!long.TryParse(timestamp, out seconds)) return false;
        long now = (long)(DateTime.UtcNow - new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc)).TotalSeconds;
        return Math.Abs(now - seconds) <= 300;
    }

    // rawBody: بدنه درخواست دقیقاً همان‌طور که رسیده است، پیش از هر پردازش JSON.
    public static bool IsValidWebhook(string secret, string id, string timestamp, byte[] rawBody, string signatureHeader)
    {
        byte[] prefix = Encoding.UTF8.GetBytes(id + "." + timestamp + ".");
        byte[] content = new byte[prefix.Length + rawBody.Length];
        Buffer.BlockCopy(prefix, 0, content, 0, prefix.Length);
        Buffer.BlockCopy(rawBody, 0, content, prefix.Length, rawBody.Length);
        using (var hmac = new HMACSHA256(KeyOf(secret)))
        {
            string expected = "v1," + Convert.ToBase64String(hmac.ComputeHash(content));
            return IsFresh(timestamp) && (signatureHeader ?? "").Split(' ').Any(c => FixedTimeEquals(c, expected));
        }
    }

    // نشانی بازگشت؛ اگر جلسه بدون reference ساخته شده باشد، reference رشته خالی است.
    public static bool IsValidReturn(string secret, string sessionId, string status, string reference, string timestamp, string signature)
    {
        string content = sessionId + "." + status + "." + (reference ?? "") + "." + timestamp;
        using (var hmac = new HMACSHA256(KeyOf(secret)))
        {
            string expected = "v1," + Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(content)));
            return IsFresh(timestamp) && FixedTimeEquals(signature, expected);
        }
    }
}
بررسی امضای وبهوک و نشانی بازگشت (PHP)
function asa_webhook_is_valid(string $secret, string $id, string $timestamp, string $rawBody, string $signatureHeader): bool
{
    if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
        return false;
    }
    $key = base64_decode(substr($secret, strlen('whsec_')), true);
    $expected = 'v1,' . base64_encode(hash_hmac('sha256', $id . '.' . $timestamp . '.' . $rawBody, $key, true));
    foreach (explode(' ', $signatureHeader) as $candidate) {
        if (hash_equals($expected, $candidate)) {
            return true;
        }
    }
    return false;
}
// $rawBody = file_get_contents('php://input')؛ سرآیندها: $_SERVER['HTTP_WEBHOOK_ID']، $_SERVER['HTTP_WEBHOOK_TIMESTAMP'] و $_SERVER['HTTP_WEBHOOK_SIGNATURE']

function asa_return_is_valid(string $secret, array $query): bool
{
    $key = base64_decode(substr($secret, strlen('whsec_')), true);
    $content = $query['session_id'] . '.' . $query['status'] . '.' . ($query['reference'] ?? '') . '.' . $query['timestamp'];
    $expected = 'v1,' . base64_encode(hash_hmac('sha256', $content, $key, true));
    return abs(time() - (int) $query['timestamp']) <= 300 && hash_equals($expected, $query['signature'] ?? '');
}
بررسی امضای وبهوک (Node.js)
// Node.js 18 یا بالاتر؛ rawBody بدنه دریافتی بی‌تغییر است (مثلاً با express.raw({ type: 'application/json' })).
const crypto = require('crypto');
function isValidWebhook(secret, headers, rawBody) {
  const key = Buffer.from(secret.slice('whsec_'.length), 'base64');
  const id = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  if (!id || !timestamp || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = Buffer.from('v1,' + crypto.createHmac('sha256', key)
    .update(id + '.' + timestamp + '.').update(rawBody).digest('base64'));
  return String(headers['webhook-signature'] || '').split(' ').some((candidate) => {
    const given = Buffer.from(candidate);
    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}

امضا روی بایت‌های بدنه همان‌طور که رسیده ساخته می‌شود؛ بدنه را پیش از بررسی امضا پردازش یا دوباره سریال نکنید. برای آزمودن کد خود این مقدارها را به کار ببرید: کلید whsec_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=، webhook-id برابر evt_0123456789abcdef0123456789abcdef، webhook-timestamp برابر 1792303950 و بدنه زیر؛ webhook-signature درست v1,vS8uMOi7OMZyURA/y1KSMx3jGMWtYTFg6CZRqTqWT34= است. برای نشانی بازگشت با session_id=6f1c2d3e-8a4b-4c5d-9e6f-0a1b2c3d4e5f، status=completed، reference=order-1024 و timestamp=1792303950، امضای درست v1,ogAzMf63I8XZHAFPrW9hd9do+rkiRRwRjwHw25F2qw0= و بدون reference برابر v1,SVT4bC/UiD1/eVOLtFQp3sG03BTrZVBE1JY5gvV80qo= است. زمان این نمونه عمداً قدیمی است؛ هنگام آزمودن با آن، بررسی پنج‌دقیقه‌ای را کنار بگذارید.

بدنه نمونه برای آزمودن امضا
{"type":"ping","timestamp":"2026-10-18T06:12:30.000Z","data":{"message":"پیام آزمایشی معتمد آسا","partnerCompanyId":50001}}
  • ظرف ۱۰ ثانیه با کد 2xx پاسخ دهید و پردازش را پس از پاسخ انجام دهید. هدایت (3xx) دنبال نمی‌شود.
  • هر پاسخ دیگر یا نبود پاسخ، تلاش دوباره را در پی دارد: ۳۰ ثانیه، ۲، ۱۰ و ۳۰ دقیقه، ۱، ۳، ۶ و ۱۲ ساعت پس از هر شکست (حداکثر ۹ بار). پس از آن رویداد «ناموفق» می‌ماند و در فهرست رویدادها همیشه خواندنی است. پشتیبانی هم می‌تواند آن را دوباره بفرستد.
  • نشانی وبهوک باید https و روی اینترنت در دسترس باشد. نشانی‌ای که به آدرس داخلی برسد فراخوانی نمی‌شود.
  • وبهوک فقط وقتی فرستاده می‌شود که روشن باشد، نشانی و کلید امضا داشته باشد و همکاری فعال باشد. رویدادی که در زمان خاموش بودن وبهوک ساخته شود، بعداً هم به وبهوک فرستاده نمی‌شود و فقط در فهرست رویدادها می‌ماند (delivery.status: "no_endpoint"). پس از روشن کردن وبهوک، فهرست رویدادها را از آخرین sequence خوانده‌شده بخوانید.

تحویل اعتبارنامه کسب‌وکار

اگر جلسه با "requestCredentials": true ساخته شود و این دسترسی برای همکار فعال باشد، مؤدی در صفحه ثبت‌نام اجازه می‌دهد همکار از طرف کسب‌وکار صورتحساب صادر و ارسال کند. پس از business_ready، POST …/{sessionId}/credentials فقط یک بار پاسخ می‌دهد: clientId و clientSecret با scopeهای Customer (v2.invoice.send، v2.invoice.cancel، v2.invoice.read، v2.lookup.read). اگر کسب‌وکار پیش‌تر اعتبارنامه داشته باشد، Secret آن عوض یا تحویل نمی‌شود (secretIssued: false). مالک می‌تواند در «تنظیمات › اتصال API v2» پنل خود Client ID را ببیند و Client Secret تازه بسازد؛ ساخت Client Secret تازه اجازه همکار را پس می‌گیرد و هر نرم‌افزار دیگری را هم که با همین اعتبارنامه کار می‌کند، قطع می‌کند.

پاسخ POST …/onboarding-sessions/{sessionId}/credentials
{
  "status": "OK",
  "data": {
    "companyId": 50123,
    "clientId": "v2-customer-50123",
    "clientSecret": "<shown-only-once>",
    "secretIssued": true,
    "scopes": "v2.invoice.cancel v2.invoice.read v2.invoice.send v2.lookup.read",
    "tokenEndpoint": "https://api-v2.asatsp.ir/api/auth/v2/token",
    "apiBaseUrl": "https://api-v2.asatsp.ir",
    "message": "این Secret فقط همین یک بار نمایش داده می‌شود؛ آن را امن نگه دارید."
  },
  "errors": [],
  "fieldErrors": [],
  "correlationId": "…"
}

اگر secretIssued برابر false باشد، clientSecret برابر null است و تحویل این جلسه انجام‌شده به حساب می‌آید؛ درخواست دوباره پاسخ 409 با کد credentials_already_claimed می‌گیرد.

خطاها

HTTPcodeمعنا
400validation_failedفیلدی نادرست است؛ نام فیلد در fieldErrors می‌آید (مثلاً returnUrl بیرون از دامنه‌های مجاز).
401 / 403unauthorized / forbiddenتوکن نیست یا توکن همکار با v2.register نیست.
403partner_not_registered / partner_suspended / capability_disabledهمکار در «همکاران API» ثبت نشده، معلق است، یا این دسترسی برایش فعال نیست.
403consent_missing / credentials_not_requestedمالک اجازه نداده است، یا اعتبارنامه در ساخت جلسه خواسته نشده بود.
404not_foundجلسه‌ای با این شناسه برای این همکار نیست.
409idempotency_conflict / session_closed / session_business_ready / business_not_ready / credentials_already_claimedتعارض با وضعیت جلسه.
409credentials_withdrawnاعتبارنامه API کسب‌وکار باطل یا غیرفعال شده است و تحویل داده نمی‌شود. تحویل این جلسه باز می‌ماند و پس از آنکه مالک اعتبارنامه را در پنل دوباره صادر کند، ممکن می‌شود.
429rate_limitedسقف ساعتی ساخت لینک همکار پر است.

قالب پاسخ همان Envelope بخش کارپوشه است. کسب‌وکارهایی که هر همکار از این راه آورده، در «همکاران API» معتمد آسا دیده می‌شوند.

07کارگزاران API

گزارش‌ها و پایش همکاری

همکار هر عددی را که در «پیشخوان همکاری» پنل معتمد آسا می‌بیند، از همین API هم می‌گیرد تا در داشبورد یا سامانهٔ گزارش‌گیری خودش به کار ببرد. این اعداد شامل کسب‌وکارهایی است که آورده، قیف ثبت‌نام، صورتحساب‌هایی که این کسب‌وکارها از راه API ثبت کرده‌اند، خطاها، سلامت وبهوک و کارکرد ماهانه. همهٔ گزارش‌ها فقط‌خواندنی‌اند و با همان اعتبارنامهٔ Partner و scope v2.register خوانده می‌شوند.

دامنه داده: گزارش‌ها کسب‌وکارهایی را در بر می‌گیرند که معتمد آسا به این همکار نسبت داده و نمایش آن‌ها را برای همکار فعال کرده است؛ معمولاً همان کسب‌وکارهایی که با لینک ثبت‌نام یا /api/register آمده‌اند. نحوه آمدن هر کسب‌وکار در source پاسخ /reports/businesses آمده است (link، register، administrator، log یا crm). کسب‌وکار خود همکار در این فهرست نیست. اگر کسب‌وکاری را که آورده‌اید در گزارش‌ها نمی‌بینید، با پشتیبانی معتمد آسا تماس بگیرید. از صورتحساب‌ها فقط آن‌هایی شمرده می‌شوند که از راه API ثبت شده‌اند (API نسخه ۱ و ۲). جمع‌ها مثل فهرست صورتحساب‌های پنل حساب می‌شوند: صورتحساب ابطالی و ابطال‌شده جزو جمع نیست و صورتحساب آزمایشی (Sandbox) جداگانه در sandbox می‌آید. اعداد دوره جاری (و فصل قبل تا ۱۵ روز پس از پایان آن) حداکثر دو دقیقه و دوره‌های قدیمی‌تر حداکثر ۳۰ دقیقه پس از هر تغییر به‌روز می‌شوند.

بازهٔ گزارش

پارامترمقدارنمونه
periodseason (پیش‌فرض)، month، year یا rangeperiod=month
keyفصل، ماه یا سال شمسی؛ بدون آن، فصل جاری1405-3، 1405-07، 1405
from / toبرای range: روز شمسی، حداکثر ۳۶۶ روزfrom=1405/07/01&to=1405/07/26

بازه‌ای که هنوز شروع نشده یا پیش از ۱۳۹۸ است، پاسخ 400 period_invalid می‌گیرد. روز هر صورتحساب، تاریخ خود صورتحساب است، نه زمان ارسال آن.

Endpointها

MethodEndpointکاربرد
GET/api/v2/partner/reports/overviewنمای کلی بازه: کسب‌وکارها (کل، تازه، فعال، بی‌صورتحساب)، ثبت‌نام‌ها، جمع صورتحساب‌ها به تفکیک وضعیت، acceptancePercent، روند روزانه، مقایسه با دورهٔ قبل، سلامت وبهوک، اعتبارنامه، صورتحساب‌های منتظر پاسخ و یافته‌ها (findings).
GET/api/v2/partner/reports/businessesکسب‌وکارهای همکار با صورتحساب‌های بازه، نرخ پذیرش، پرتکرارترین خطا و وضعیت (ok، attention، idle، inactive). فیلترها: q (نام، شماره اقتصادی یا شناسه)، health، sort (invoices، amount، errors، recent، name)، page، pageSize (حداکثر ۱۰۰).
GET/api/v2/partner/reports/errorsخطاهای صورتحساب‌های API به تفکیک کد رسمی سامانهٔ مؤدیان یا متن خطای پیش از ارسال (origin)، با تعداد، مبلغ، کسب‌وکارهای درگیر و روند روزانهٔ سهم خطا. فقط صورتحساب‌هایی را دارد که ثبت شده‌اند.
GET/api/v2/partner/reports/rejectionsصورتحساب‌هایی که API پیش از ثبت رد کرده و اصلاً صورتحساب نشده‌اند (محل دیدن خطاها): جمع (total، بدون Sandbox)، sandbox و duplicates جدا، علت‌ها به تفکیک فیلد (field مانند Header.cap یا Body[].fee) با تعداد صورتحساب، درخواست و کسب‌وکارهای درگیر، روند روزانه و ۵۰ مورد آخر با traceId، internalId و ردیف data.
GET/api/v2/partner/reports/onboardingقیف ثبت‌نام: ساخت لینک، باز شدن، ورود و تأیید مالک، ساخت پنل، پایان ثبت‌نام؛ با ریزش هر مرحله، میانهٔ زمان تا پایان، خطاهای پرتکرار و ثبت‌نام‌های نیمه‌کاره.
GET/api/v2/partner/reports/usage?fromMonth=1405-02&toMonth=1405-07کارکرد ماهانهٔ هر کسب‌وکار (حداکثر ۱۲ ماه): تعداد صورتحساب، تعداد ثبت‌شده و مبلغ؛ مبنای محاسبات مالی همکاری.
GET/api/v2/partner/reports/monthly?month=1405-07گزارش ماهانهٔ کامل: نمای کلی، قیف، همهٔ کسب‌وکارها و خطاها. بدون month، در سه روز اول ماه گزارش ماه قبل و پس از آن ماه جاری.
GET/api/v2/partner/reports/invoices?q=…پیگیری یک صورتحساب با شمارهٔ مالیاتی ۲۲ کاراکتری؛ یا با UUID یا شمارهٔ صورتحساب همراه businessId. وضعیت، خطا و تاریخچهٔ ارسال‌ها را برمی‌گرداند.
GET/api/v2/partner/reports/healthسلامت اتصال: تحویل وبهوک در ۲۴ ساعت و ۷ روز (درصد موفقیت، میانگین و صدک ۹۵ زمان پاسخ)، اعتبارنامه، صورتحساب‌های API هر ساعت در ۲۴ ساعت گذشته، صورتحساب‌های منتظر پاسخ و هشدارهای باز.
GET /api/v2/partner/reports/overview?period=month&key=1405-07 — بخشی از پاسخ
{
  "status": "OK",
  "data": {
    "readDay": "1405/07/26",
    "readClock": "09:30",
    "period": { "kind": "month", "key": "1405-07", "title": "مهر 1405", "fromDay": "1405/07/01", "toDay": "1405/07/30", "isOpen": true },
    "businesses": { "total": 120, "added": 14, "active": 97, "idle": 23 },
    "onboarding": { "created": 40, "opened": 33, "completed": 25, "conversionPercent": 62.5 },
    "invoices": { "invoices": 18250, "amount": 9120000000, "vat": 820800000, "registered": 17990, "inFlight": 120, "needsAction": 140 },
    "acceptancePercent": 99.2,
    "sandbox": { "invoices": 35, "amount": 0 },
    "comparison": { "title": "شهریور 1405", "isPartial": true, "acceptancePercent": 98.7 },
    "webhook": { "state": "ok", "last24Hours": { "events": 18, "delivered": 18, "failed": 0, "successPercent": 100, "averageMs": 140, "p95Ms": 320 } },
    "resultDelay": { "waiting": 120, "late": 0, "thresholdMinutes": 120 },
    "findings": [ { "code": "signups_stalled", "severity": "info", "title": "ثبت‌نام نیمه‌کاره", "tab": "onboarding" } ]
  },
  "errors": [],
  "fieldErrors": [],
  "correlationId": "…"
}

هشدارهای خودکار

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

هشدارباز می‌شود وقتیبسته می‌شود وقتی
error_rateاز صورتحساب‌های API سه ساعت گذشته که نتیجه گرفته‌اند (دست‌کم ۲۰ صورتحساب)، ۲۰٪ یا بیشتر رد شده باشد.سهم خطا زیر ۱۰٪ برگردد.
rejected_requestsدر سه ساعت گذشته دست‌کم ۳ صورتحساب (غیر از Sandbox و ارسال تکراری) پیش از ثبت رد شده باشد. متن هشدار پرتکرارترین علت را هم می‌گوید.سه ساعت هیچ صورتحسابی پیش از ثبت رد نشود.
result_delayدست‌کم ۱۰ صورتحساب API بیش از دو ساعت منتظر پاسخ سامانهٔ مؤدیان مانده باشد.کمتر از ۳ صورتحساب منتظر بماند.
webhookرویدادی دو بار یا بیشتر بی‌پاسخ موفق مانده باشد، یا تلاش‌های رویدادی در ساعت گذشته تمام شده باشد.تحویل دوباره موفق شود. (این هشدار فقط در پنل و اعلان‌ها می‌آید، نه در خود وبهوک.)
رویدادداده
partner.alert.opened{ "alert": "error_rate", "title", "detail", "figures": { "registered", "errored", "errorPercent", "windowHours" } }؛ برای rejected_requests: "figures": { "refused", "requests", "businesses", "windowHours" }.
partner.alert.resolvedهمان شکل، با متن بسته شدن هشدار.
partner.report.monthly_ready{ "month": "1405-07", "title": "مهر 1405" }؛ سه روز اول هر ماه، یک بار.

خطاها

HTTPcodeشرح
400period_invalid / validation_failedبازه، ماه یا فیلتر معتبر نیست؛ نام پارامتر در fieldErrors می‌آید.
401 / 403unauthorized / forbiddenتوکن نیست یا توکن همکار با v2.register نیست.
403business_not_yoursbusinessId از کسب‌وکارهای این همکار نیست.
404partner_not_foundاین اعتبارنامه به همکار ثبت‌شده در «همکاران API» تعلق ندارد.

همین گزارش‌ها در پنل معتمد آسا، بخش «پیشخوان همکاری»، با نمودار و خروجی Excel (از جمله گزارش ماهانهٔ چندبرگه) در دسترس کاربران کسب‌وکار همکار است.

08ثبت و پیگیری صورتحساب

ثبت یا به‌روزرسانی مشتری

POST /api/register

این سرویس با Access Token دارای scope v2.register فراخوانی می‌شود و پس از اعتبارسنجی شناسه حافظه مالیاتی، مشتری را ایجاد یا به‌روزرسانی می‌کند. توکن را با اعتبارنامهٔ همکار بگیرید؛ Partner API Key قدیمی دیگر پذیرفته نمی‌شود (راهنمای کارگزاران). customerApiKey در پاسخ برای سازگاری می‌ماند ولی همیشه null است و اعتبارنامهٔ مشتری فقط در serviceAuth می‌آید.

فیلدنوعالزامیتوضیح
typenumberبله1 حقیقی، 2 حقوقی، 3 مشارکت مدنی، 4 اتباع غیر ایرانی. در ثبت مشتری تازه این فیلد را بفرستید؛ مقدار آن بررسی نمی‌شود و اگر فرستاده نشود، صفر ذخیره می‌شود. در به‌روزرسانی مشتری، ارسال‌نشدن این فیلد مقدار فعلی را تغییر نمی‌دهد.
fiscalIdstring(6)بلهشناسه حافظه مالیاتی مشتری که باید در همان محیط درخواست اخذ و قابل استعلام باشد.
sandBoxbooleanخیرtrue برای ثبت و استعلام در Sandbox؛ مقدار پیش‌فرض false و به معنی محیط عملیاتی است.
economicCodestringبلهشماره اقتصادی مشتری؛ با شناسه حافظه مالیاتی کنترل می‌شود.
namestringخیرنام شخص یا شرکت.
nationalCodestringخیرکد ملی یا شناسه ملی. در به‌روزرسانی مشتری، ارسال‌نشدن این فیلد (یا مقدار null) کد ملی ثبت‌شده را تغییر نمی‌دهد؛ مقدار ارسال‌شده، حتی رشته خالی، جای مقدار قبلی را می‌گیرد.
mobilestringخیرشماره تلفن همراه مالک. فقط وقتی همین درخواست کسب‌وکار را تازه ثبت می‌کند، به‌عنوان شماره ورود او به پنل ثبت می‌شود. برای کسب‌وکاری که پیش‌تر ثبت شده، شماره ورود کاربران از این سرویس تغییر نمی‌کند و message پاسخ این را می‌گوید؛ هر کاربر شماره خود را در پنل با کد تأیید عوض می‌کند.
autoSendbooleanخیرتنظیم عمومی ارسال خودکار کسب‌وکار. اگر در پنل برای «API نسخه ۲» تنظیم جداگانه‌ای ثبت شده باشد، همان تنظیم مبناست. در ثبت مشتری تازه، نبودن این فیلد یعنی true؛ در به‌روزرسانی مشتری، ارسال‌نشدن آن مقدار فعلی را تغییر نمی‌دهد.
valueAddedNotCalledbooleanخیرمعادل گزینه «مشمول فراخوان مالیات بر ارزش افزوده نیست» در پنل است. با مقدار true، نرخ مالیات بر ارزش افزوده همه ردیف‌ها باید ۰ باشد و ردیفی با نرخ بیشتر از صفر رد می‌شود. در به‌روزرسانی مشتری، ارسال‌نشدن این فیلد مقدار فعلی را تغییر نمی‌دهد.
کسب‌وکاری که پیش‌تر ثبت شده: اگر شماره اقتصادی از قبل در معتمد آسا باشد، به‌روزرسانی و برگرداندن اعتبارنامه (serviceAuth) فقط برای همکاری انجام می‌شود که خودش آن کسب‌وکار را آورده باشد: با همین سرویس، با لینک موقت ثبت‌نام، یا با ثبت پشتیبانی. برای کسب‌وکاری که خود مالک یا همکار دیگری ثبت کرده، هیچ چیز تغییر نمی‌کند و پاسخ result: -2 با error: "business_registered_elsewhere" است. برای اتصال به چنین کسب‌وکاری، لینک موقت ثبت‌نام بسازید تا مالک با رمز سامانه مؤدیان اجازه دهد، یا مالک اعتبارنامه API را از پنل خود به شما بدهد.

نتیجه و پاسخ

resultمعنا
1مشتری ایجاد شد.
3مشتری به‌روزرسانی شد.
2مشتری از قبل ثبت شده بود و تغییری لازم نبود.
0داده نامعتبر است، شناسه حافظه مالیاتی معتبر نیست (error: "FISCAL_ID_INVALID") یا استعلام آن از سامانه مؤدیان انجام نشد (error: "FISCAL_ID_INQUIRY_UNAVAILABLE"؛ جزئیات).
-1احراز هویت ناموفق است یا همکار اجازه این کار را ندارد؛ کد رد همکار در error می‌آید، مثلاً partner_suspended یا capability_disabled.
-2کسب‌وکار را مالک یا همکار دیگری ثبت کرده است (error: "business_registered_elsewhere").

فیلدهای data در پاسخ موفق: companyId، fiscalId، fiscalMemoryId، sandBox، environment، environmentTitle، economicCode، valueAddedNotCalled، فیلدهای وضعیت کارپوشه (taxFileState، taxFileStatus، taxFileStatusTitle و taxFileMessage)، customerApiKey (همیشه null)، serviceAuth، created و updated. نمونه کامل در نمونه کد ثبت مشتری آمده است.

Client Secret مشتری فقط یک بار برمی‌گردد: serviceAuth.client_secret فقط در پاسخی می‌آید که اعتبارنامه مشتری در همان ثبت ساخته شود. اگر کسب‌وکار پیش‌تر اعتبارنامه داشته باشد، و در همه فراخوانی‌های بعدی، مقدار آن null است؛ پس آن را همان بار اول در جای امن نگه دارید. در این حالت serviceAuth.warning می‌گوید که Client Secret تازه را مدیر کسب‌وکار در پنل، بخش «تنظیمات کسب‌وکار › اتصال API v2»، صادر می‌کند؛ راه‌های دیگر در راه‌اندازی کارگزار آمده است.
09ثبت و پیگیری صورتحساب

ثبت صورتحساب با JSON استاندارد سازمان امور مالیاتی

POST /api/invoice/send

این سرویس با Access Token دارای scope v2.invoice.send فراخوانی می‌شود و برای ثبت صورتحساب با ساختار رسمی سازمان امور مالیاتی به‌کار می‌رود. ورودی یک object شامل uuid و آرایه data با حداقل ۱ و حداکثر ۲۵۰ عضو است. فیلد uuid در ریشه بدنه، شناسه کل درخواست گروهی است و همه اعضای data[] همان درخواست، همین مقدار را به اشتراک می‌گذارند؛ برای هر درخواست جدید یک GUID تازه تولید کنید. هر عضو مستقل اعتبارسنجی و پردازش می‌شود؛ خطای یک صورتحساب مانع ثبت سایر صورتحساب‌های سالم نیست.

نتیجه هر عضو به همان ترتیب ورودی در data[] بازگردانده می‌شود. عضو ناموفق دارای status: 3 (hasError) و آرایه error است و مسیرهای ساخت‌یافته خطا نیز در errors[].path قرار می‌گیرند.
فیلد send اختیاری است. اگر این فیلد را ارسال نکنید، مقدار آن null باقی می‌ماند و تنظیم ارسال خودکار «API نسخه ۲» کسب‌وکار تصمیم نهایی را تعیین می‌کند؛ فقط true یا false صریح این تنظیم را برای همان عضو بازنویسی می‌کند.
پیش‌فاکتور: فیلد اختیاری proforma (boolean) کنار send و sandBox می‌آید. با proforma: true همان صورتحساب به‌عنوان پیش‌فاکتور ثبت می‌شود: به سامانه مؤدیان ارسال نمی‌شود، حافظه مالیاتی و شماره منحصربه‌فرد مالیاتی (taxId) ندارد، شماره‌گذاری آن از صورتحساب‌ها جداست و اعتبار آن مدت پیش‌فرض کسب‌وکار (در «تنظیمات کسب‌وکار ← پیش‌فاکتور»، پیش‌فرض ۷ روز) است. پیش‌فاکتور در پنل به صورتحساب تبدیل می‌شود و حافظه مالیاتی همان‌جا انتخاب می‌شود. نبودن این فیلد یا false رفتار قبلی را حفظ می‌کند و صورتحساب ثبت می‌شود.
  • فقط موضوع اصلی (Header.ins=1) و بدون Header.irtaxid پذیرفته می‌شود؛ اصلاحی، ابطالی و برگشت از فروش صورتحساب‌اند.
  • send: true همراه proforma: true با خطا رد می‌شود؛ fiscalId و sandBox برای پیش‌فاکتور به کار نمی‌روند و Payments ذخیره نمی‌شود (پرداخت روی صورتحساب حاصل از تبدیل ثبت می‌شود).
  • در پیش‌فاکتور نوع ۱ هم فیلدهای پایه خریدار لازم است: در /send فیلد tob و یکی از tinb یا bid (برای خریدار حقوقی tinb)، و در مدل ساده شیء buyer با nationalCode یا economicCode. فقط ثبت خریدار در «خریداران» و کنترل‌های تکمیلی آن تا زمان تبدیل به صورتحساب انجام نمی‌شود.
  • پاسخ و پیگیری پیش‌فاکتور با internalId وضعیت status: 7 و شیء proforma (validUntil، state، stateTitle و پس از تبدیل convertedInvoiceNo) برمی‌گرداند. پیگیری با شماره (inquiryNo) فقط خط شماره‌گذاری صورتحساب‌ها را جست‌وجو می‌کند.
صورتحساب موضوع ماده ۹: فیلد Header.insr «قاعده ارسال صورتحساب» است و برای ماده ۹ فقط مقدار عددی 1 دارد. فیلد Header.indati2m «تاریخ و زمان ثبت صورتحساب» و یک Unix timestamp عددی با دقت میلی‌ثانیه و حداکثر ۱۳ رقم است. مهلت فعلی سیستم ۱۵ روز کامل (۱۵ × ۲۴ ساعت) است و اعتبار نهایی هنگام ارسال بررسی می‌شود. اگر فاصله indatim تا زمان ارسال کمتر یا مساوی ۱۵ روز باشد، صورتحساب عادی است؛ حتی در صورت دریافت insr: 1، دو فیلد ماده ۹ در payload نهایی اعمال نمی‌شوند. برای صورتحساب خارج از این مهلت، insr: 1 و indati2m باید هم‌زمان ارسال شوند، تاریخ ثبت نباید از indatim کوچک‌تر یا از زمان ارسال بزرگ‌تر باشد و فاصله تاریخ ثبت تا ارسال نیز نباید بیش از ۱۵ روز باشد. این قابلیت برای صورتحساب‌های نوع ۱ و ۲، همه الگوهای مجاز آن‌ها و موضوع‌های اصلی، اصلاحی، برگشت از فروش و ابطالی قابل استفاده است.
indati2m از تاریخ صدور indatim مستقل است و تاریخ صدور، TaxId، سریال یا FiscalId را تغییر نمی‌دهد. در صورتحساب عادی این دو فیلد را نفرستید؛ درخواست‌های قدیمی که این دو فیلد را ندارند بدون تغییر پشتیبانی می‌شوند. indati2m بدون insr: 1 با خطای ARTICLE9_REGISTER_WITHOUT_SEND_RULE رد می‌شود.

کدهای خطای ماده ۹ (مسیرها زیر $.data[i].data.Header):

codepathمعنا
ARTICLE9_FEATURE_DISABLED.insrقابلیت صورتحساب موضوع ماده ۹ برای این کسب‌وکار فعال نیست.
ARTICLE9_REGISTER_WITHOUT_SEND_RULE.indati2mindati2m فقط همراه insr=1 پذیرفته می‌شود.
ARTICLE9_REGISTER_REQUIRED.indati2mبا insr=1، تاریخ و زمان ثبت صورتحساب الزامی است.
ARTICLE9_REGISTER_BEFORE_ISSUE.indati2mزمان ثبت پیش از زمان صدور (indatim) است.
ARTICLE9_REGISTER_IN_FUTURE.indati2mزمان ثبت از زمان حال جلوتر است.
ARTICLE9_INVOICE_TYPE_NOT_ALLOWED.intyماده ۹ فقط برای صورتحساب‌های نوع ۱ و ۲ مجاز است.
ARTICLE9_REQUIREDهنگام ارسالمهلت ارسال صورتحساب گذشته است و ماده ۹ برای آن فرستاده نشده است.
ARTICLE9_REGISTER_TO_SEND_EXCEEDEDهنگام ارسالبیش از ۱۵ روز از زمان ثبت (indati2m) گذشته است.
نمونه کامل درخواست صورتحساب موضوع ماده ۹
{
  "uuid": "2e4f2ce6-cc0e-447b-a697-204dc96ea6e8",
  "data": [{
    "internalId": "ARTICLE9-1001",
    "send": true,
    "fiscalId": "PRD123",
    "sandBox": false,
    "data": {
      "Header": {
        "indatim": 1782940800000,
        "indati2m": 1784146800000,
        "insr": 1,
        "inty": 1,
        "inp": 1,
        "ins": 1,
        "inno": "A000000009",
        "tins": "12345678901234",
        "tob": 2,
        "tinb": "10987654321000",
        "bpc": "1234567890",
        "setm": 1,
        "tprdis": 10000000,
        "tdis": 0,
        "tadis": 10000000,
        "tvam": 1000000,
        "todam": 0,
        "tbill": 11000000,
        "cap": 11000000,
        "insp": 0,
        "tvop": 1000000
      },
      "Body": [{
        "sstid": "1234567890123",
        "sstt": "کالای نمونه",
        "mu": "1627",
        "am": 2,
        "fee": 5000000,
        "prdis": 10000000,
        "dis": 0,
        "adis": 10000000,
        "vra": 10,
        "vam": 1000000,
        "odam": 0,
        "olam": 0,
        "tsstam": 11000000
      }],
      "Payments": []
    }
  }]
}

تاریخ‌ها و شناسه‌های نمونه‌های این صفحه فقط قالب را نشان می‌دهند و صورتحسابی که با تاریخ نمونه‌ها فرستاده شود، خارج از مهلت ۱۵ روزه ارسال است. پیش از ارسال، indatim را زمان واقعی صدور به میلی‌ثانیه بگذارید، مثلاً Date.now() در JavaScript یا DateTimeOffset.UtcNow.ToUnixTimeMilliseconds() در C#. در مدل ساده، dateTime را با قالب yyyyMMddHHmmss و به وقت تهران بفرستید.

الگوی بورس اوراق بهادار مبتنی بر کالا (inp=11)

این الگو فقط در صورتحساب نوع ۱ (inty=1) و با دقیقاً یک ردیف در Body پذیرفته می‌شود. در Header، فیلدهای asn (شماره اعلامیه فروش بورس، فقط رقم و حداکثر ۳۰ رقم) و asd (تاریخ اعلامیه به روز Unix، حداکثر برابر روز تاریخ صدور) الزامی‌اند. در ردیف، mu، adis، vra، vam و tsstam الزامی‌اند؛ adis باید عیناً ارزش معامله در اعلامیه فروش بورس (ریال، عدد صحیح) باشد و vra و vam باید 0 باشند؛ بنابراین tsstam و tbill برابر adis است. در Header، tadis هم الزامی است و باید برابر adis تنها ردیف باشد. مبلغ واحد (fee) در این الگو خارج از الگوست؛ جزئیات در مبلغ واحد در الگوی ۱۱. cui (عیار) اختیاری است.
prdis، dis، Header.tprdis، Header.tdis، Header.todam و Payments در این الگو خارج از الگو هستند و نباید ارسال شوند؛ قاعده fee جداگانه در مبلغ واحد در الگوی ۱۱ آمده است. برای سازگاری، هر فیلد خارج از الگو با مقدار صفر یا رشته خالی (مانند dis، odam، olam، odr، cfee، odt، tdis، todam، tax17 یا crn)، آرایه خالی Payments، cui=0 و مقدار prdis/tprdis برابر با adis/tadis حذف می‌شود. مقدار غیرصفر یا غیرخالی فیلدهای خارج از الگو (تخفیف، سایر مالیات، فیلدهای ارزی، bsrn، crn، billid، tax17 و پرداخت‌ها) با خطای V79_OUT_OF_PATTERN رد می‌شوند. صورتحساب برگشت از فروش (ins=4) در این الگو مجاز نیست و در روش setm=3 جمع cap و insp باید برابر tbill باشد.
مبلغ واحد در الگوی ۱۱: طبق دستورالعمل RC_IITP.IS_V7.9، در الگوی بورس اوراق بهادار مبتنی بر کالا (inp=11) فیلد fee (مبلغ واحد) خارج از الگو است؛ نه الزامی است و نه اختیاری، و هرگز به سامانه مؤدیان ارسال نمی‌شود. مبلغ تعیین‌کننده و الزامی این الگو adis (مبلغ بعد از تخفیف) است که باید دقیقاً برابر ارزش معامله در اعلامیه فروش بورس، به ریال و عدد صحیح بزرگ‌تر از صفر باشد؛ لازم نیست بر am بخش‌پذیر باشد و گرد نمی‌شود.
  • fee را ارسال نکنید. اگر کلاینت قدیمی آن را بفرستد، فعلاً برای سازگاری، مقدار صحیح و غیرمنفی آن (حتی 0 یا مقداری ناهمخوان با adis و am) در مبلغ‌گذاری نادیده گرفته می‌شود و ذخیره نمی‌شود؛ ولی قالب آن همچنان کنترل می‌شود: مقدار اعشاری (مثلاً 333333.67 یعنی adis/am)، منفی یا غیرعددی خطای Body[i].fee می‌گیرد و همان عضو data[] ثبت نمی‌شود. با فعال شدن کنترل کامل Rule Matrix نسخه ۷.۹ برای الگوی ۱۱، هر مقدار fee (حتی 0) با خطای V79_OUT_OF_PATTERN رد خواهد شد.
  • adis را نمی‌توان حذف کرد: نبود یا null بودن adis خطای الزامی‌بودن می‌گیرد و سامانه آن را از fee × am یا prdis - dis محاسبه نمی‌کند. Header.tadis هم الزامی و برابر adis است.
  • مبلغ واحد ذخیره‌شده فقط نمایشی است: برای نمایش در پنل، چاپ و خروجی‌ها و سازگاری با ساختار ردیف، سامانه یک مبلغ واحد را از روی adis محاسبه و ذخیره می‌کند: کوتاه‌ترین عدد با حداکثر ۸ رقم اعشار که floor(مبلغ واحد × am) دقیقاً برابر adis شود؛ برای adis=1000001 و am=3 این مقدار 333333.7 است. این مقدار به سامانه مؤدیان ارسال نمی‌شود و در پاسخ سرویس‌های ثبت و پیگیری API نسخه ۲ هم برنمی‌گردد.
  • تخفیف: prdis، dis، Header.tprdis و Header.tdis خارج از الگو هستند؛ مقدار صفر (و prdis/tprdis برابر adis/tadis) حذف و هر مقدار دیگر با V79_OUT_OF_PATTERN رد می‌شود. جزئیات در جدول اعتبارسنجی JSON.

خلاصه رفتار مبلغ واحد و مبلغ بعد از تخفیف الگوی ۱۱ در مسیرهای API:

مسیرمبلغ واحد (fee / unitPrice)مبلغ بعد از تخفیف (adis / amountAfterDiscount)ارسال به سامانه مؤدیان
JSON استاندارد: /api/invoice/sendfee خارج از الگوست؛ ارسال نکنید. اگر ارسال شود باید عدد صحیح غیرمنفی باشد (مقدار اعشاری یا منفی خطا می‌گیرد)؛ سپس نادیده گرفته می‌شود و ذخیره نمی‌شود.adis الزامی: عدد صحیح بزرگ‌تر از صفر برابر ارزش معامله در اعلامیه فروش بورس؛ از fee یا prdis محاسبه نمی‌شود. Header.tadis برابر آن است.adis و am عیناً؛ fee، prdis و dis ارسال نمی‌شوند.
مدل ساده: /api/invoice/commoditySecurities و /api/invoice/simple/type/1/template/11unitPrice فقط در نبود amountAfterDiscount لازم است و به‌کار می‌رود؛ floor(qty × unitPrice) باید بزرگ‌تر از صفر باشد (اعشار مجاز است). در کنار amountAfterDiscount نادیده گرفته می‌شود ولی نباید منفی باشد.amountAfterDiscount (روش توصیه‌شده): عدد صحیح بزرگ‌تر از صفر برابر ارزش معامله در اعلامیه فروش بورس؛ بر unitPrice مقدم است و عیناً adis می‌شود.همان adis به‌دست‌آمده و am؛ unitPrice ارسال نمی‌شود.
پاسخ پیگیری: inquiryInternalId، inquiryNo، inquiryTaxId و نسخه‌های آرایه‌ایبرنمی‌گردد؛ پاسخ پیگیری فیلد ردیف ندارد و مبلغ واحد نمایشی (مثلاً 333333.7) فقط در پنل، چاپ و خروجی دیده می‌شود.فقط در status: 2 و در json.Body[0].adis.json همان payload ارسال‌شده است: در json.Body[0] adis و am مقدار دارند ولی fee، prdis و dis مقداری ندارند (برابر null هستند یا اصلاً نمی‌آیند).
اصلاحی الگوی ۱۱ و اعلامیه فروش بورس: طبق دستورالعمل RC_IITP.IS_V7.9، صدور صورتحساب اصلاحی (ins=2) برای زنجیره الگوی ۱۱ فقط تا زمانی مجاز است که اعلامیه فروش بورس تأیید نشده باشد؛ پس از تأیید فقط ابطال (ins=3) مجاز است. سامانه راهی برای دریافت خودکار این تأیید ندارد؛ وضعیت آن را با /api/invoice/exchangeAnnouncement یا در پنل ثبت کنید. تا وقتی وضعیتی ثبت نشده، اصلاحی مانند گذشته پذیرفته می‌شود. پس از ثبت «تأیید شده»، اصلاحی همان زنجیره (حتی اگر inp اصلاحی ۱۱ نباشد) با کد EXCHANGE_ANNOUNCEMENT_CONFIRMED، و اگر وضعیت موقتاً قابل خواندن نباشد با کد EXCHANGE_ANNOUNCEMENT_STATUS_UNAVAILABLE، رد می‌شود. مسیر خطا $.data[i].data.Header.irtaxid (در مدل ساده $.data[i].sourceInternalId یا $.data[i].sourceTaxId) یا $.data[i] است؛ عضو را با شماره داخل data[i] پیدا کنید. ابطال، برگشت از فروش و سایر اعضای درخواست گروهی تحت تأثیر قرار نمی‌گیرند.
نمونه کامل درخواست الگوی بورس اوراق بهادار مبتنی بر کالا
{
  "uuid": "6b1f0f3e-3c8a-4c61-9f7e-3f2d7a5b9c11",
  "data": [{
    "internalId": "IME-1001",
    "send": true,
    "fiscalId": "PRD123",
    "sandBox": false,
    "data": {
      "Header": {
        "indatim": 1788271140000,
        "inty": 1,
        "inp": 11,
        "ins": 1,
        "inno": "A000000011",
        "tins": "12345678901234",
        "tob": 2,
        "tinb": "10987654321000",
        "setm": 3,
        "tadis": 1000001,
        "tvam": 0,
        "tbill": 1000001,
        "cap": 400000,
        "insp": 600001,
        "asn": "1405012345",
        "asd": 20697
      },
      "Body": [{
        "sstid": "1234567890123",
        "sstt": "کالای معامله‌شده در بورس کالا",
        "mu": "1627",
        "am": 3,
        "adis": 1000001,
        "vra": 0,
        "vam": 0,
        "tsstam": 1000001
      }]
    }
  }]
}

در این نمونه adis=1000001 بر am=3 بخش‌پذیر نیست و همان مبلغ بدون گرد شدن به‌عنوان مبلغ بعد از تخفیف ذخیره و ارسال می‌شود. fee ارسال نشده است؛ مبلغ واحد نمایشی که سامانه ذخیره می‌کند 333333.7 است (floor(333333.7 × 3) = 1000001) و به سامانه مؤدیان ارسال نمی‌شود. asd=20697 همان روز 2026/09/01 است که با روز تاریخ صدور برابر است.

برای اصلاحی الگوی ۱۱ (فقط پیش از تأیید اعلامیه فروش بورس؛ قاعده اصلاحی) همین ساختار را با ins=2، شماره مالیاتی صورتحساب مرجع در irtaxid، asn و asd اعلامیه و adis جدید بفرستید. fiscalId و sandBox باید همان صورتحساب مرجع باشد (حافظه مالیاتی) و فیلدهای خریدار (tob، tinb و bid) را نفرستید؛ در اصلاحی هم fee، prdis و dis خارج از الگو هستند و نباید ارسال شوند.

نمونه اصلاحی الگوی بورس اوراق بهادار مبتنی بر کالا
{
  "uuid": "9a3e7c21-54b0-4f8e-a1d6-2c7b9e0f4a13",
  "data": [{
    "internalId": "IME-1001-EDIT",
    "send": true,
    "fiscalId": "PRD123",
    "sandBox": false,
    "data": {
      "Header": {
        "indatim": 1788274740000,
        "inty": 1,
        "inp": 11,
        "ins": 2,
        "irtaxid": "PRD12304E7900000F42410",
        "inno": "A000000012",
        "tins": "12345678901234",
        "setm": 3,
        "tadis": 1000500,
        "tvam": 0,
        "tbill": 1000500,
        "cap": 400000,
        "insp": 600500,
        "asn": "1405012345",
        "asd": 20697
      },
      "Body": [{
        "sstid": "1234567890123",
        "sstt": "کالای معامله‌شده در بورس کالا",
        "mu": "1627",
        "am": 3,
        "adis": 1000500,
        "vra": 0,
        "vam": 0,
        "tsstam": 1000500
      }]
    }
  }]
}

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

ساختار کلی درخواست ثبت با JSON رسمی (طرح کلی؛ قابل ارسال نیست)
{
  "uuid": "GUID یکتای درخواست",
  "data": [
    {
      "internalId": "کد داخلی یکتای صورتحساب",
      "send": true,
      "fiscalId": "SND123",
      "sandBox": true,
      "description": "توضیحات اختیاری",
      "data": {
        "Header": {},
        "Body": [],
        "Payments": []
      }
    }
  ]
}

فیلدهای درخواست

فیلدنوع و الزامتوضیح
uuidریشه؛ رشته GUID، الزامی، حداکثر ۶۴ نویسهشناسه کل درخواست؛ برای هر درخواست تازه مقدار تازه بسازید.
dataریشه؛ آرایه ۱ تا ۲۵۰ عضو، الزامیهر عضو یک صورتحساب است.
checkTypeTwoBuyersریشه؛ boolean، اختیاریبررسی پرونده مالیاتی خریدار حقیقی در صورتحساب نوع ۲ را در درخواست چندصورتحسابی روشن می‌کند (جزئیات).
data[].internalIdرشته JSON، الزامی، حداکثر ۲۵۵ نویسهکد داخلی یکتای صورتحساب در کسب‌وکار.
data[].sendboolean، اختیاریtrue ارسال پس از ثبت و false فقط ثبت؛ در نبود آن، تنظیم ارسال خودکار «API نسخه ۲» کسب‌وکار اعمال می‌شود.
data[].fiscalIdرشته شش‌نویسه‌ای از حروف انگلیسی و رقم، اختیاریشناسه حافظه مالیاتی (حافظه مالیاتی و Sandbox).
data[].sandBoxboolean، اختیاریtrue برای محیط آزمایشی؛ پیش‌فرض false.
data[].proformaboolean، اختیاریثبت به‌صورت پیش‌فاکتور (پیش‌فاکتور).
data[].descriptionرشته، اختیاری، حداکثر ۱۰۰۰ نویسهتوضیح صورتحساب.
data[].returnRowsremaining یا returned، فقط با ins=4معنای ردیف‌های برگشت از فروش (برگشت از فروش).
data[].dataشیء، الزامیHeader و Body الزامی‌اند (جز Body در صورتحساب ابطالی) و Payments اختیاری است.

مقدار هر فیلد باید از همان نوع JSON باشد: رشته در گیومه، عدد بدون گیومه و boolean به‌صورت true یا false. برای نمونه، internalId عددی بدون گیومه با خطای «فیلد internalId باید رشته باشد.» رد می‌شود. نام تکراری در یک شیء، کل بدنه را نامعتبر می‌کند («ساختار JSON معتبر نیست»).

درخواست گروهی

آرایه data باید بین ۱ تا ۲۵۰ عضو داشته باشد و هر عضو مستقل اعتبارسنجی و ذخیره می‌شود.

شناسه درخواست و جلوگیری از تکرار

uuid به کل درخواست تعلق دارد، نه به یک شرکت یا یک صورتحساب. کنترل تکراری‌بودن آن فقط در محدوده شرکت احراز هویت‌شده انجام می‌شود؛ بنابراین همان شرکت نباید uuid یک درخواست قبلی را دوباره استفاده کند. internalId نیز باید برای هر صورتحساب آن شرکت یکتا بماند. کد داخلی عددی با مقدار عددی‌اش مقایسه می‌شود؛ برای نمونه "001" و "1" یک صورتحساب حساب می‌شوند. uuid فقط وقتی مصرف می‌شود که دست‌کم یک صورتحساب ثبت شود؛ درخواستی که هیچ عضوی از آن ثبت نشده، با همان uuid هم پذیرفته می‌شود.

مالکیت صورتحساب

Header.tins باید شماره اقتصادی همان کسب‌وکاری باشد که توکن به نام آن صادر شده است.

10ثبت و پیگیری صورتحساب

چند شناسه حافظه مالیاتی و محیط Sandbox

هر کسب‌وکار می‌تواند چند شناسه حافظه مالیاتی داشته باشد. هر شناسه دقیقاً متعلق به یکی از محیط‌های Production یا Sandbox است و هر صورتحساب هنگام ثبت به همان شناسه متصل می‌شود. Serial و TaxId بر اساس همان شناسه تولید می‌شوند؛ تغییر Default شرکت، شناسه یا اطلاعات صورتحساب‌های قبلی را تغییر نمی‌دهد.

فیلدهای درخواست

فیلدنوعالزامقاعده
fiscalIdstring(6)اختیاریشناسه یکتای شش‌کاراکتری حافظه مالیاتی؛ باید متعلق به همان کسب‌وکار، فعال و با محیط درخواست سازگار باشد. در صورت ارسال، همان شناسه روی Invoice تثبیت می‌شود.
sandBoxbooleanاختیاریtrue برای Sandbox و false برای Production. مقدار پیش‌فرض false است؛ در صورت ارسال‌نشدن، درخواست عملیاتی محسوب می‌شود.
شناسه Sandbox باید مستقلاً از محیط https://sandboxrc.tax.gov.ir اخذ و در همان محیط استعلام شود. حتی اگر مقدار شش‌کاراکتری آن با شناسه عملیاتی یکسان باشد، ثبت Production و Sandbox دو رکورد مستقل هستند و انجام مراحل اخذ/فعال‌سازی در یک محیط، جایگزین محیط دیگر نیست.

انتخاب خودکار در نبود fiscalId

۱. محیط درخواستProduction یا Sandbox مشخص می‌شود؛ fallback بین دو محیط مجاز نیست.
۲. Default فعال همان محیطDefault محیط دیگر در انتخاب شرکت نمی‌کند.
۳. تنها شناسه فعال همان محیطاگر فقط یک شناسه قابل استفاده باشد، خودکار انتخاب می‌شود.
۴. انتخاب صریحدر صورت وجود چند شناسه فعال بدون Default، ارسال fiscalId شش‌کاراکتری الزامی است.
صورتحساب ارجاعی: صورتحساب اصلاحی، ابطالی و برگشت از فروش همیشه با حافظه مالیاتی صورتحساب مرجع ثبت می‌شود. اگر در این صورتحساب‌ها fiscalId را نفرستید، حافظه مالیاتی صورتحساب مرجع به کار می‌رود، همان‌طور که cancelInvoice عمل می‌کند؛ به شرط آنکه sandBox همان محیط مرجع را نشان دهد (اگر sandBox را نفرستید، محیط اصلی در نظر گرفته می‌شود). صورتحساب ارجاعی هیچ‌گاه از محیط آزمایشی به محیط اصلی یا برعکس نمی‌رود. اگر fiscalId را بفرستید، باید همان شناسه صورتحساب مرجع (شش کاراکتر نخست شماره مالیاتی آن) باشد و sandBox هم همان محیط مرجع را نشان دهد. در غیر این صورت صورتحساب ثبت نمی‌شود.

نمونه درخواست‌ها

Production با شناسه صریح
{
  "uuid": "0df9e8c6-07ba-4dc6-93f2-c20f5f4aef08",
  "data": [{
    "internalId": "PROD-1001",
    "send": true,
    "fiscalId": "PRD123",
    "sandBox": false,
    "data": { "Header": {}, "Body": [], "Payments": [] }
  }]
}
Sandbox با شناسه صریح
{
  "uuid": "8fd4439c-7964-4ac4-aee0-f6fd2dfadff8",
  "data": [{
    "internalId": "SANDBOX-1001",
    "send": false,
    "fiscalId": "SND123",
    "sandBox": true,
    "data": { "Header": {}, "Body": [], "Payments": [] }
  }]
}
استفاده از Default محیط و تنظیم ارسال API نسخه ۲
{
  "uuid": "5ec152a0-a8e8-4ee1-9bbf-73f7954b38ee",
  "data": [{
    "internalId": "SANDBOX-1002",
    "sandBox": true,
    "data": { "Header": {}, "Body": [], "Payments": [] }
  }]
}
کلاینت قدیمی بدون فیلدهای جدید
{
  "uuid": "17c0f06d-5bf1-40dc-b3cc-61b76677d26e",
  "data": [{
    "internalId": "LEGACY-1001",
    "send": true,
    "data": { "Header": {}, "Body": [], "Payments": [] }
  }]
}

فیلدهای پاسخ

Fiscal memory binding
{
  "fiscalMemoryId": 31,
  "fiscalId": "ABC123",
  "fiscalMemoryTitle": "شناسه تست API",
  "sandBox": true,
  "environment": "Sandbox",
  "environmentTitle": "سندباکس",
  "isDefaultFiscalMemory": true
}

خطاهای انتخاب شناسه

این پیام‌ها عین پیام‌های Validator مرکزی هستند و در خطای عضو مربوطه بازگردانده می‌شوند. برای جلوگیری از افشای مالکیت، «یافت نشدن» و «متعلق‌بودن به شرکت دیگر» یک پیام امن مشترک دارند.

وضعیتپیام واقعی APIاقدام اصلاحی
شناسه یافت نشد یا متعلق به شرکت دیگر استFiscalId حافظه مالیاتی انتخاب‌شده متعلق به این کسب‌وکار نیست.یک fiscalId شش‌کاراکتری متعلق به شرکت احراز هویت‌شده ارسال کنید.
شناسه غیرفعال استشناسه حافظه مالیاتی انتخاب‌شده غیرفعال است و برای صورتحساب جدید قابل استفاده نیست.شناسه‌ای را انتخاب کنید که در پنل فعال است.
محیط ناسازگار استFiscalId حافظه مالیاتی انتخاب‌شده در محیط عملیاتی/سندباکس این کسب‌وکار ثبت نشده است.مقدار sandBox یا شناسه را اصلاح کنید؛ fallback بین محیط‌ها انجام نمی‌شود.
چند شناسه بدون Defaultدر محیط عملیاتی/سندباکس چند شناسه حافظه مالیاتی فعال وجود دارد و هیچ شناسه پیش‌فرضی تعیین نشده است؛ شناسه حافظه مالیاتی باید صریح انتخاب شود.Default همان محیط را تعیین یا fiscalId را صریح ارسال کنید.
شناسه فعالی در این محیط نیستبرای محیط عملیاتی/سندباکس این کسب‌وکار شناسه حافظه مالیاتی فعال تعریف نشده است.یک شناسه حافظه مالیاتی برای همین محیط در پنل تعریف و فعال کنید.
بیش از یک شناسه پیش‌فرضبرای محیط عملیاتی/سندباکس این کسب‌وکار بیش از یک شناسه حافظه مالیاتی پیش‌فرض ثبت شده است.فقط یک شناسه را پیش‌فرض کنید.
قالب fiscalId نادرست است (مسیر $.data[i].fiscalId)فیلد fiscalId باید دقیقاً ۶ کاراکتر و فقط شامل حروف انگلیسی یا عدد باشد.شش کاراکتر حرف انگلیسی یا رقم بفرستید؛ حروف بزرگ و کوچک یکسان حساب می‌شوند.
حافظه صورتحساب ارجاعی با حافظه مرجع یکی نیستصورتحساب اصلاحی، ابطالی یا برگشت از فروش با همان حافظه مالیاتی صورتحساب مرجع صادر می‌شود. حافظه مالیاتی صورتحساب مرجع را انتخاب کنید.fiscalId را نفرستید تا حافظه صورتحساب مرجع به کار رود، یا fiscalId و sandBox صورتحساب مرجع را بفرستید.

نمونه‌های خطا

در ثبت گروهی، خطای انتخاب شناسه در همان عضو data[] برمی‌گردد: پیام در errors[] ریشه با مسیر $.data[i] و در error[] همان عضو با status: 3 می‌آید. این خطاها کد ثابت (errors[].code) ندارند و فقط با متن پیام شناخته می‌شوند.

پاسخ: شناسه متعلق به کسب‌وکار دیگر یا ناموجود
{
  "result": 0,
  "traceId": "3b2f6c1a-8d4e-4f0b-9a7c-1e2d3f4a5b6c",
  "message": "هیچ صورتحسابی ثبت نشد. 1 مورد دارای خطا بود.",
  "errors": [
    { "path": "$.data[0]", "message": "FiscalId حافظه مالیاتی انتخاب‌شده متعلق به این کسب‌وکار نیست." }
  ],
  "data": [
    {
      "isDefaultFiscalMemory": false,
      "status": 3,
      "error": ["$.data[0]: FiscalId حافظه مالیاتی انتخاب‌شده متعلق به این کسب‌وکار نیست."],
      "internalId": "PROD-1001"
    }
  ]
}
شناسه Sandbox غیرفعال حساب نمی‌شود. صورتحساب Sandbox فقط با شناسه Sandbox ثبت و به سامانه آزمایشی ارسال می‌شود؛ شناسه عملیاتی در درخواست Sandbox و شناسه Sandbox در درخواست عملیاتی پذیرفته نمی‌شود.
11ثبت و پیگیری صورتحساب

رفتار ثبت گروهی، خطای جزئی و محدودیت درخواست

قواعد این بخش برای /api/invoice/send و همه Endpointهای مدل ساده آرایه‌ای، از جمله /api/invoice/salesWithBuyerData، یکسان است.

موضوعرفتار APIاقدام پیشنهادی مصرف‌کننده
خطای اعتبارسنجی یک یا چند عضوهر عضو مستقل اعتبارسنجی می‌شود. صورتحساب‌های سالم ثبت می‌شوند و فقط اعضای نامعتبر با status: 3 و جزئیات error[] برمی‌گردند.فقط اعضای ناموفق را پس از اصلاح، با uuid جدید دوباره ارسال کنید.
ترتیب پاسخآرایه پاسخ data دقیقاً با ترتیب آرایه ورودی متناظر است؛ هر ورودی یک نتیجه موفق یا ناموفق دارد.برای تطبیق قطعی علاوه بر index، از internalId استفاده کنید.
خطای غیرمنتظره هنگام ذخیرهخطای اجرایی یک عضو ثبت اعضای بعدی را متوقف نمی‌کند و همان عضو با خطا برمی‌گردد. چون ذخیره هر صورتحساب مستقل است، نتیجه تک‌تک اعضا را بررسی کنید.در timeout یا قطع ارتباط، پیش از retry وضعیت internalIdها را استعلام کنید.
خطای گذرای پایگاه دادهاگر ثبت یک عضو به‌دلیل ازدحام یا بن‌بست پایگاه داده کامل نشود، همان عضو با status: 3 و خطایی با code: "INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE" در errors[].path = $.data[i] برمی‌گردد. این خطا رد صورتحساب نیست و اعضای دیگر تحت تأثیر قرار نمی‌گیرند.وضعیت همان internalId را با inquiryInternalId استعلام کنید و اگر ثبت نشده بود، فقط همان صورتحساب را در یک درخواست جدید با uuid جدید دوباره ارسال کنید.
تعداد اعضای dataحداقل ۱ و حداکثر ۲۵۰ صورتحساب در هر درخواست مجاز است. درخواست دارای ۲۵۱ عضو یا بیشتر، پیش از پردازش کل آرایه رد می‌شود.برای بیش از ۲۵۰ صورتحساب چند درخواست با uuidهای مستقل بسازید.
حجم و زمان درخواستعلاوه بر سقف ۲۵۰ عضو، محدودیت حجم JSON، وب‌سرور، پراکسی و timeout محیط استقرار نیز اعمال می‌شود.حجم serialized JSON و timeout کلاینت را کنترل کنید.
مقدار resultresult: 1 یعنی حداقل یک صورتحساب ثبت شده است؛ حتی اگر تعدادی عضو خطا داشته باشند. result: 0 یعنی هیچ صورتحسابی ثبت نشده یا ساختار کلی درخواست رد شده است.برای تشخیص موفقیت کامل، علاوه بر result، تمام اعضای data[] و errors[] را بررسی کنید.
مثال: اگر آرایه شامل ۲۵۰ صورتحساب باشد و ۳ مورد خطا داشته باشند، ۲۴۷ مورد سالم ثبت می‌شوند و همان ۳ عضو با وضعیت خطا در پاسخ برمی‌گردند. ارسال ۱۰۰۰ صورتحساب در یک درخواست مجاز نیست و باید حداقل به ۴ درخواست تقسیم شود.
برای سازگاری با کلاینت‌های قدیمی، اگر Rule Matrix نسخه ۷.۹ فیلدهای Header.tonw، Header.sg یا Body.nw را در صورتحساب نوع ۱ یا ۲ خارج از الگو بداند، API آن‌ها را پیش از اعتبارسنجی نادیده می‌گیرد. در صورتحساب نوع ۲ همین رفتار برای Header.setm، Header.cap، Header.insp، Header.tvop، Body.cop و Body.vop نیز اعمال می‌شود. این سازگاری فقط به همین فیلدهای امن محدود است و سایر فیلدهای خارج از الگو همچنان با خطای ساخت‌یافته رد می‌شوند. فیلد Header.bbc نادیده گرفته نمی‌شود و در صورت ارسال باید کد واقعی شعبه خریدار با دقیقاً ۴ رقم باشد.

قاعده تکرار امن درخواست

  1. uuid را برای هر درخواست جدید یکتا تولید کنید و internalId هر صورتحساب را ثابت و یکتا نگه دارید.
  2. اگر پاسخ شامل نتیجه جزئی بود، اعضای دارای status: 3 را اصلاح کنید؛ اعضای موفق را دوباره نفرستید.
  3. اگر result: 0 دریافت شد، هیچ عضوی ثبت نشده است؛ خطاهای ریشه یا تمام اعضای ناموفق را بررسی کنید.
  4. اگر timeout، قطع ارتباط یا خطای اجرایی رخ داد، ابتدا با Endpointهای استعلام، وضعیت تک‌تک internalIdها را بررسی کنید.
  5. فقط صورتحساب‌های ثبت‌نشده را با uuid جدید دوباره ارسال کنید.
12ثبت و پیگیری صورتحساب

ثبت صورتحساب با مدل ساده و آرایه‌ای

برای سامانه‌هایی که نیاز ندارند JSON رسمی سامانه مؤدیان را به‌صورت مستقیم تولید کنند، Endpointهای زیر مدل ورودی ساده و سازگار با نسخه ۱ را دریافت می‌کنند. بدنه همه این مسیرها یک object شامل uuid در ریشه و آرایه data با حداکثر ۲۵۰ عضو است. در این مدل نیز uuid شناسه کل درخواست است، بین همه اعضای data[] همان درخواست مشترک است و باید برای هر درخواست جدید مقدار تازه‌ای داشته باشد. هر عضو باید internalId یکتا داشته باشد و مستقل پردازش می‌شود؛ خطای یک عضو مانع ثبت اعضای سالم نیست.

در تمام Endpointهای ساده، هر عضو data[] همانند مسیر /api/invoice/send فیلدهای send، fiscalId، sandBox و proforma (پیش‌فاکتور؛ فقط با invoiceSubject اصلی) را می‌پذیرد. اگر send حذف شود، مقدار آن null می‌ماند و تنظیم ارسال خودکار «API نسخه ۲» کسب‌وکار اعمال می‌شود. برای ثبت سندباکس، sandBox: true و شناسه شش‌کاراکتری همان محیط را کنار send ارسال کنید؛ این انتخاب برای هر عضو جداگانه اعمال می‌شود. فیلدهای اختیاری isArticle9 و invoiceRegistrationDateTime نیز ماده ۹ و تاریخ ثبت Unix میلی‌ثانیه‌ای آن را مشخص می‌کنند.

ترکیب‌های مجاز نوع و الگو از طریق مسیر عمومی /api/invoice/simple/type/{invoiceType}/template/{template} نیز قابل ثبت هستند. طبق دستورالعمل RC_IITP.IS_V7.9، صورتحساب نوع ۱ الگوهای 1، 2، 3، 4، 5، 6، 7، 8، 9، 11، 13 و 14 را می‌پذیرد؛ نوع ۲ فقط برای الگوهای 1، 3، 9 و 13 مجاز است.

فهرست فنی سامانه مؤدیان از نوع صورتحساب ۵ و الگوهای ۹۸ (خرید از بورس کالا) و ۹۹ (واردات) هم نام می‌برد، ولی دستورالعمل رسمی آن‌ها منتشر نشده و در RC_IITP.IS_V7.9 نیامده است. این API تا انتشار دستورالعمل آن‌ها را نمی‌پذیرد: نوع ۵ خطای «نوع صورتحساب باید یکی از مقادیر 1 یا 2 باشد.» و الگوهای ۹۸ و ۹۹ خطای «الگوی صورتحساب معتبر نیست…» می‌گیرند.

الگونوع ۱نوع ۲
inp=1 فروش کالا و خدمات/api/invoice/salesWithBuyerData/api/invoice/salesEndUser
inp=2 فروش ارز/api/invoice/exchangeدر نوع ۲ مجاز نیست
inp=3 طلا، جواهر و پلاتین/api/invoice/jewelry/api/invoice/jewelryEndUser
inp=4 قرارداد پیمانکاری/api/invoice/contractingدر نوع ۲ مجاز نیست
inp=5 قبوض خدماتی/api/invoice/utilityBillدر نوع ۲ مجاز نیست
inp=6 بلیت هواپیما/api/invoice/flightTicketدر نوع ۲ مجاز نیست
inp=7 صادرات/api/invoice/exportدر نوع ۲ مجاز نیست
inp=8 بارنامه/api/invoice/billOfLadingدر نوع ۲ مجاز نیست
inp=9 فروش فرآورده‌های نفتی پالایش و پخش/api/invoice/oilProducts/api/invoice/oilProductsEndUser
inp=11 بورس اوراق بهادار مبتنی بر کالا/api/invoice/commoditySecuritiesدر نوع ۲ مجاز نیست
inp=13 بیمه/api/invoice/insurance/api/invoice/insuranceEndUser
inp=14 فروش زنجیره/api/invoice/chainSaleدر نوع ۲ مجاز نیست

در مسیرهای نوع ۱، شیء buyer الزامی است؛ فقط الگوهای صادرات (inp=7) و بورس اوراق بهادار مبتنی بر کالا (inp=11) مستثنی هستند. در مسیرهای نوع ۲، buyer اختیاری است. اگر آن را در صورتحساب اصلی بفرستید، خریدار در «خریداران» ثبت و روی صورتحساب نگه داشته می‌شود. مشخصات او فقط وقتی به سامانه مؤدیان ارسال می‌شود که برای همان خریدار در پنل «ارسال مشخصات در صورتحساب نوع ۲» روشن باشد. اگر ثبت خریدار ممکن نباشد، صورتحساب بدون خریدار ثبت می‌شود و علت در warnings همان عضو می‌آید.

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

هر عضو data[] در مسیرهای مدل ساده این فیلدها را دارد. فیلدهای خریدار در قرارداد اطلاعات خریدار، فیلدهای شناسایی کالا/خدمت در کالا/خدمت هر قلم و فیلدهای هر الگو در جدول «فیلدهای اختصاصی هر الگو» آمده‌اند.

فیلدنوع و الزامتوضیح
internalIdرشته، الزامی، حداکثر ۲۵۵ نویسهکد داخلی یکتای صورتحساب در کسب‌وکار.
noرشته، الزامی، حداکثر ۱۰ نویسه، فقط حروف انگلیسی و رقمشماره صورتحساب؛ به inno تبدیل می‌شود.
dateTimeاختیاریتاریخ و زمان صدور: Unix time به میلی‌ثانیه (حداکثر ۱۳ رقم)، تاریخ میلادی با قالب yyyyMMddHHmmss به وقت تهران، یا تاریخ شمسی مانند 1405/04/14 11:30. اگر این فیلد را نفرستید یا خالی بفرستید، زمان فعلی به وقت تهران تاریخ صدور می‌شود.
descriptionرشته، اختیاریتوضیح صورتحساب.
invoiceSubjectاختیاری، پیش‌فرض 1موضوع صورتحساب (جدول «مقادیر شمارشی مدل ساده»). نام قدیمی invoiceIssue هم پذیرفته می‌شود.
sourceInternalId / sourceTaxIdدر موضوع ۲، ۳ و ۴ یکی از این دو الزامی استکد داخلی یا شماره مالیاتی صورتحساب مرجع. اگر هر دو را بفرستید، sourceTaxId مبناست؛ صورتحساب مرجع باید شماره مالیاتی داشته باشد.
settlementاختیاری، پیش‌فرض 1روش تسویه: 1 نقدی، 2 نسیه، 3 نقدی/نسیه.
paymentعدد، در روش تسویه 3سهم نقدی؛ در JSON سازمان cap برابر floor(payment) (حداکثر tbill) و insp برابر tbill − cap می‌شود.
payments[]اختیاریردیف‌های پرداخت. اگر type را نفرستید، روش پرداخت «چک» (1) ثبت و به سامانه مؤدیان ارسال می‌شود؛ این فیلد را همیشه صریح بفرستید. اگر dateTime ردیف را نفرستید، تاریخ صدور صورتحساب تاریخ پرداخت می‌شود.
tax17عدد، اختیاریمالیات موضوع ماده ۱۷.
items[].qtyعدد مثبت، الزامیتعداد یا مقدار.
items[].unitPriceعدد غیرمنفی، الزامی جز در الگوی ۱۱مبلغ واحد. در الگوی فروش ارز (inp=2) هم الزامی است، با اینکه fee در آن الگو ارسال نمی‌شود.
items[].discountعدد غیرمنفی، اختیاریمبلغ تخفیف ردیف (درصد نیست)؛ نباید از qty × unitPrice بیشتر باشد.
items[].vatRateعدد ۰ تا ۱۰۰، الزامینرخ مالیات بر ارزش افزوده؛ در الگوهای صادرات، بورس و فروش زنجیره (inp برابر ۷، ۱۱ و ۱۴) باید 0 باشد.
items[].otherTaxRate، items[].otherTaxDescriptionاختیارینرخ و موضوع سایر مالیات و عوارض.
items[].govTaxRate، items[].govTaxDescriptionاختیارینرخ و موضوع سایر وجوه قانونی.
items[].contractNoاختیاریشناسه قرارداد حق‌العمل‌کاری (bsrn).

API مبالغ هر ردیف را با حذف اعشار (بدون گرد کردن) می‌سازد: prdis = floor(qty × unitPrice)، dis = floor(discount)، adis = prdis − dis، vam = floor(مبنا × vatRate / 100)، odam = floor(adis × otherTaxRate / 100) و olam = floor(adis × govTaxRate / 100). مبنای مالیات بر ارزش افزوده adis است، جز در الگوی ۹ که اگر vatBaseAmount بزرگ‌تر از صفر باشد، همان مبناست.

نام فیلدهای مدل ساده در JSON سازمان

مدل ساده پیش از ثبت به JSON رسمی سامانه مؤدیان تبدیل و با همان قواعد /send کنترل می‌شود. خطای این مرحله با نام فیلد رسمی و مسیر همان JSON برمی‌گردد، مثلاً $.data[0].data.Header.tbill یا $.data[0].data.Body[1].vra؛ Body[j] همان items[j] درخواست شماست. نام فیلد مدل ساده را از جدول زیر پیدا کنید.

مدل سادهJSON سازمان
noHeader.inno
dateTimeHeader.indatim
invoiceSubjectHeader.ins
sourceTaxId / sourceInternalIdHeader.irtaxid
settlementHeader.setm
paymentHeader.cap
contractCodeHeader.crn
billNoHeader.billid
tax17Header.tax17
cottageNoHeader.cdcn
cottageDateHeader.cdcd
saleAnnNoHeader.asn
saleAnnDateHeader.asd
insPolicyNoHeader.in
extInsPolicyNoHeader.an
declarationNoHeader.scln
officeCodeHeader.scc
buyer.typeHeader.tob
buyer.economicCodeHeader.tinb
buyer.nationalCodeHeader.bid
buyer.zipCodeHeader.bpc
buyer.branchCodeHeader.bbc
buyer.passportNumberHeader.bpn
items[].stuffIdBody[].sstid
items[].descriptionBody[].sstt
items[].unitBody[].mu
items[].qtyBody[].am
items[].unitPriceBody[].fee
items[].discountBody[].dis
items[].vatRateBody[].vra
items[].otherTaxDescriptionBody[].odt
items[].otherTaxRateBody[].odr
items[].govTaxDescriptionBody[].olt
items[].govTaxRateBody[].olr
items[].contractNoBody[].bsrn
items[].currencyCodeBody[].cut
items[].amountCurrencyBody[].cfee
items[].currencyRateBody[].exr
items[].currencyValueBody[].sscv
items[].currencyPurchaseRateBody[].cpr
items[].vatBaseAmountBody[].sovat (الگوی ۲) یا Body[].vba (الگوی ۹)
items[].netWeightBody[].nw
items[].wageBody[].consfee
items[].profitBody[].spro
items[].commissionBody[].bros
items[].caratBody[].cui
payments[].typePayments[].pmt
payments[].dateTimePayments[].pdt
payments[].pricePayments[].pv
payments[].traceNoPayments[].trn
payments[].cardNoPayments[].pcn
payments[].payerNationalCodePayments[].pid
payments[].terminalNumberPayments[].trmn
payments[].acquirerNumberPayments[].acn
payments[].switchNumberPayments[].iinn

قرارداد کامل اطلاعات خریدار (buyer)

شیء buyer در هر عضو data قرار می‌گیرد. نام فیلدها را مطابق جدول زیر ارسال کنید. همه شناسه‌ها و شماره‌های تماس باید از نوع JSON string باشند تا صفر ابتدای مقدار حذف نشود.

فیلدنوعالزامقالب و توضیح
typenumberخیر؛ پیش‌فرض 11 حقیقی، 2 حقوقی، 3 مشارکت مدنی، 4 اتباع غیر ایرانی. برای جلوگیری از برداشت نادرست، ارسال صریح آن توصیه می‌شود.
nationalCodestringشرطیفقط رقم؛ در قرارداد ورودی 5 تا 14 رقم. برای شخص حقیقی ایرانی کد ملی معتبر 10 رقمی و برای شخص حقوقی شناسه ملی 11 رقمی ارسال شود. در صورت نداشتن economicCode الزامی است.
economicCodestringبرای نوع 2 الزامیفقط رقم، 11 تا 14 رقم. حداقل یکی از nationalCode یا economicCode باید موجود باشد.
zipCodestringخیرکد پستی 10 رقمی؛ بدون خط تیره یا فاصله.
namestringخیرنام شخص یا عنوان خریدار. حداکثر ظرفیت ذخیره‌سازی 4000 کاراکتر است.
mobilestringخیرشماره همراه ایران با قالب پیشنهادی 09xxxxxxxxx و 11 رقم. مقدار معتبر به همین قالب نرمال می‌شود.
addressstringخیرنشانی پستی به‌صورت متن Unicode، حداکثر 4000 کاراکتر.
phonestringخیرشماره تلفن ثابت همراه پیش‌شماره؛ الگوی عددی جداگانه‌ای در endpoint اعمال نمی‌شود و حداکثر ظرفیت ذخیره‌سازی 1024 کاراکتر است.
branchCodenumberخیرکد شعبه خریدار به‌صورت عدد صحیح.
passportNumberstringشرطیشماره گذرنامه خریدار غیرایرانی که کد فراگیر ندارد؛ حداکثر ۹ حرف و رقم لاتین. فقط با type=4 در الگوی فروش ارز (template=2) پذیرفته می‌شود و به‌جای nationalCode به‌عنوان header.bpn ارسال می‌شود.
فیلدهای mobile، address و phone اطلاعات تکمیلی هستند و جایگزین شناسه‌های هویتی خریدار نمی‌شوند. برای خریدار حقوقی، economicCode حتی در صورت ارسال nationalCode همچنان الزامی است.

نمونه کامل buyer

buyer object
"buyer": {
  "type": 2,
  "nationalCode": "10100000000",
  "economicCode": "10987654321000",
  "zipCode": "1234567890",
  "name": "شرکت خریدار نمونه",
  "mobile": "09120000000",
  "address": "تهران، خیابان نمونه، پلاک ۱",
  "phone": "02188770000",
  "branchCode": 1
}

کالا/خدمت هر قلم: کد داخلی، شرح، واحد و شناسه

هر قلم آرایه items کالا یا خدمت را با فیلدهای زیر معرفی می‌کند. مبالغ، تخفیف و مالیات‌های قلم در فیلدهای صورتحساب در مدل ساده و فیلدهای هر الگو در جدول «فیلدهای اختصاصی هر الگو» آمده‌اند.

فیلدنوعالزامقالب و توضیح
items[].internalIdstringخیرکد یا شناسه کالا/خدمت در سامانه مبدأ شما، حداکثر ۲۵۴ کاراکتر. API کالا/خدمت را با این کد شناسایی یا ایجاد می‌کند و مقدار را به‌عنوان کد داخلی آن ذخیره می‌کند. برای حفظ صفرهای ابتدایی باید به‌صورت JSON string ارسال شود. رفتار کد تکراری در کالا/خدمتِ از قبل ثبت‌شده آمده است.
items[].descriptionstringخیرشرح همین قلم روی صورتحساب. همین متن به‌عنوان شرح کالا/خدمت (Body[].sstt) به سامانه مؤدیان می‌رود و نام کالا/خدمت در پنل هم می‌شود. سامانه مؤدیان حداکثر ۴۰۰ کاراکتر می‌پذیرد و بیش از آن کوتاه می‌شود.
items[].unitstringبله، جز الگوی فروش ارز (template=2)کد رسمی واحد اندازه‌گیری، یعنی مقدار code از GET /api/InvoiceItemUnit/codes؛ برای «عدد» "1627" و برای «کیلوگرم» "164". همین کد در Body[].mu به سامانه مؤدیان می‌رود. جزئیات در واحد اندازه‌گیری در مدل ساده.
items[].stuffIdstringبله، مگر از internalId برداشته شودشناسه رسمی ۱۳رقمی کالا/خدمت (Body[].sstid). اعتبار شناسه را فهرست رسمی سازمان تعیین می‌کند؛ اعتبار شناسه کالا/خدمت را ببینید.
items[].internalId با data[].internalId (کد داخلی صورتحساب) و items[].stuffId تفاوت دارد. فیلد stuffId شناسه رسمی ۱۳رقمی کالا/خدمت است و به Body[].sstid نگاشت می‌شود؛ کد داخلی کالا/خدمت جایگزین آن نیست و در payload ارسالی به سامانه مؤدیان قرار نمی‌گیرد. برابر بودن اختیاری مقدار internalId و stuffId مجاز است. اگر internalId ارسال نشود، رفتار موجود سامانه برای تولید کد داخلی حفظ می‌شود.

کالا/خدمتِ از قبل ثبت‌شده با همان items[].internalId

  • روی صورتحساب: همیشه شرح، شناسه و واحدی می‌آید که در همین درخواست فرستاده‌اید، و همان‌ها به سامانه مؤدیان می‌روند. اطلاعات ذخیره‌شده‌ی کالا/خدمت جای آن‌ها را نمی‌گیرد.
  • در «کالاها و خدمات» پنل: اگر description، stuffId یا unit با کالا/خدمت ثبت‌شده فرق داشته باشد، نسخه‌ی تازه‌ای از آن با مقادیر جدید جای نسخه‌ی قبلی را می‌گیرد. نسخه‌ی قبلی بایگانی می‌ماند و صورتحساب‌های قبلی تغییری نمی‌کنند. اگر شرح هر بار فرق کند (مثلاً دوره یا شماره قرارداد در آن باشد)، هر بار نسخه‌ی تازه‌ای ثبت می‌شود؛ این روی صورتحساب‌ها اثری ندارد.
  • بدون stuffId: اگر کالا/خدمت ثبت‌شده با همین کد داخلی شناسه دارد، همان شناسه استفاده می‌شود و صورتحساب با هشدار در warnings ثبت می‌شود.

واحد اندازه‌گیری در مدل ساده (items[].unit)

در unit کد رسمی واحد را بفرستید؛ فهرست کامل را GET /api/InvoiceItemUnit/codes می‌دهد (سند واحدهای اندازه‌گیری سازمان، RC_UMGS_ST_V1_18). در نمونه‌های این صفحه "1627" کد رسمی «عدد» است.

برای سازگاری با کلاینت‌های قدیمی، unit نام واحد (مثلاً "عدد") و شناسه داخلی آن در GET /api/InvoiceItemUnit را هم می‌پذیرد. مقدار به این ترتیب خوانده می‌شود:

  1. کد رسمی یا نام واحد؛
  2. اگر هیچ‌کدام نبود، شناسه داخلی واحد. در این حالت صورتحساب ثبت می‌شود و هشداری با کد رسمی همان واحد در warnings برمی‌گردد.
شناسه داخلی واحد نفرستید. هشت شناسه داخلی هم‌زمان کد رسمی واحد دیگری هستند. چون کد رسمی مقدم است، با فرستادن آن‌ها بدون هیچ خطا یا هشداری واحد دیگری ثبت می‌شود. برای نمونه، برای «گرم» کد رسمی "1622" را بفرستید، نه "163".
مقدار ارسالیشناسه داخلیِ واحدواحدی که ثبت می‌شودکد رسمی درست
161چلیکبرگ1659
162جامتیوب1636
163گرمقالب1622
164نخکیلوگرم1616
165شعلهمتر1652
166قیراطصفحه1678
168میلی‌مترحلب16101
169میلی‌گرمتن16102

واحدی که کد رسمی ندارد (مانند «کادر») پذیرفته می‌شود، ولی آن ردیف بدون Body[].mu به سامانه مؤدیان می‌رود و هشدار آن در warnings برمی‌گردد. مقداری که نه کد رسمی است، نه نام و نه شناسه داخلی، با خطای «واحد اندازه‌گیری در جدول واحدهای سامانه مؤدیان یافت نشد.» در مسیر $.data[i].items[j].unit رد می‌شود.

اعتبار شناسه کالا/خدمت (items[].stuffId)

اعتبار هر شناسه را فهرست رسمی «سامانه شناسه کالا و خدمات» سازمان امور مالیاتی (stuffid.tax.gov.ir) تعیین می‌کند: وضعیت، تاریخ اجرا و تاریخ انقضای همان فهرست. معتمد آسا این فهرست را هر شب از سامانه سازمان دریافت می‌کند و شناسه‌ای که در آن نباشد ثبت نمی‌شود. متن عنوان شناسه، حتی اگر عبارتی مانند «اعتبار تا تاریخ …» داشته باشد، ملاک اعتبار نیست؛ شناسه‌ای که در فهرست رسمی تاریخ انقضا ندارد معتبر است. وضعیت روز هر شناسه را در stuffid.asatsp.ir ببینید؛ برای نمونه https://stuffid.asatsp.ir/?q=2330001423026.

مقادیر شمارشی مدل ساده

فیلدمقادیر مجازنکته
invoiceSubject1 اصلی، 2 اصلاحی، 3 ابطالی، 4 برگشت از فروشبرای موضوع‌های غیر اصلی، ارسال sourceInternalId یا sourceTaxId الزامی است. در برگشت از فروش، items اقلام باقی‌مانده پس از برگشت است (برگشت از فروش).
isArticle9true یا false (اختیاری)در حالت true، فیلد invoiceRegistrationDateTime اجباری است؛ حذف فیلد یا false رفتار قبلی را حفظ می‌کند.
invoiceRegistrationDateTimeUnix Time میلی‌ثانیه‌ای، حداکثر ۱۳ رقمتاریخ و زمان ثبت صورتحساب موضوع ماده ۹؛ با تاریخ صدور dateTime متفاوت است.
settlement1 نقدی، 2 نسیه، 3 نقدی/نسیهدر حالت 3، مقدار payment سهم نقدی تسویه است.
buyer.type1 حقیقی، 2 حقوقی، 3 مشارکت مدنی، 4 اتباع غیر ایرانیبرای خریدار حقوقی، economicCode الزامی است.
payments[].type1 چک، 2 تهاتر، 3 وجه نقد، 4 کارت‌خوان (POS)، 5 درگاه پرداخت اینترنتی، 6 کارت‌به‌کارت، 7 انتقال به حساب، 8 سایراین مقدار به Payments[].pmt نگاشت می‌شود. برای پرداخت کارت‌خوانی نوع 4، شماره پذیرنده، پایانه و کارت الزامی است.

فیلدهای اختصاصی هر الگو

الگوفیلدهای سادهتوضیح
inp=1 فروشdeclarationNo, officeCodeاختیاری و فقط برای صورتحساب نوع ۱: شماره پروانه گمرکی (header.scln، حداکثر 14 رقم) و کد گمرک محل اظهار (header.scc، دقیقاً 5 رقم).
inp=2 ارزitems[].currencyCode, amountCurrency, currencyRate, currencyPurchaseRate, vatBaseAmount, declarationNo, officeCode, buyer.passportNumberنرخ خرید ارز باید کوچک‌تر از نرخ فروش ارز باشد. declarationNo و officeCode مثل الگوی ۱. خریدار غیرایرانی فاقد کد فراگیر با buyer.type=4 و buyer.passportNumber ثبت می‌شود.
inp=3 طلا، جواهر و پلاتینitems[].wage, profit, commission, caratاجرت ساخت، سود فروشنده و حق‌العمل الزامی و غیرمنفی هستند.
inp=4 پیمانکاریcontractCodeشناسه یکتای ثبت قرارداد پیمانکاری، 12 رقم.
inp=5 قبوض خدماتیbillNoشناسه قبض یا شماره اشتراک بهره‌بردار، حداکثر 19 رقم.
inp=6 بلیت هواپیماflightInfoflightType: 1 داخلی، 2 خارجی. buyerMethod: 1 شماره ملی، 2 کد فراگیر اتباع، 3 گذرنامه.
inp=7 صادراتcottageNo, cottageDate, officeCode, items[].netWeight, currencyValue, currencyCode, currencyRateاگر تاریخ کوتاژ ارسال شود، شماره کوتاژ هم الزامی است. officeCode (کد گمرک محل اظهار، header.scc) اختیاری و دقیقاً 5 رقم است؛ شماره پروانه گمرکی در این الگو خارج از الگوست. نرخ مالیات بر ارزش افزوده (vatRate) در این الگو ۰ است و نرخ بیشتر از صفر رد می‌شود.
inp=8 بارنامهshipmentInfoشماره بارنامه، مبدأ/مقصد، فرستنده/گیرنده، نوع حمل، ناوگان و وزن کل کنترل می‌شوند. driverIdCode (شماره ملی یا کد فراگیر اتباع غیرایرانی راننده، header.did) در حمل جاده‌ای transportType=1 الزامی است و در هر حال باید 10 رقم (شماره ملی) یا 12 رقم (کد فراگیر) باشد؛ شناسه ملی 11 رقمی اشخاص حقوقی پذیرفته نمی‌شود. کشور و شهر با کدهای جدول کدینگ کشورها و شهرهای دستورالعمل (پیوست‌های ۹-۴ و ۹-۵) ارسال می‌شوند؛ کد ایران 033 است (نه 364) و برای ایران شهر الزامی است، مثلاً تهران 284 و تبریز 12.
inp=9 فرآورده‌های نفتی پالایش و پخشفیلدهای عمومی کالا/خدمت و مالیات، items[].vatBaseAmountvatBaseAmount مبلغ پایه مالیات بر ارزش افزوده (body[].vba) است؛ اگر بزرگ‌تر از صفر باشد، مالیات ردیف از همین مبلغ محاسبه می‌شود و در غیر این صورت مبلغ بعد از تخفیف مبناست.
inp=11 بورس اوراق بهادار مبتنی بر کالاsaleAnnNo, saleAnnDate, items[].amountAfterDiscount, items[].caratشماره اعلامیه فروش باید عددی باشد و تاریخ اعلامیه الزامی است. تاریخ تقویمی بدون جابه‌جایی روز به asd تبدیل می‌شود؛ برای Unix time، روز تقویمی تهران مبناست. برای نمونه، 20260901 معادل 1405/06/10 و asd=20697 است. تاریخ اعلامیه نباید بعد از تاریخ صورتحساب dateTime باشد. items[].amountAfterDiscount ارزش معامله در اعلامیه فروش بورس به ریال (عدد صحیح بزرگ‌تر از صفر) است و عیناً مبلغ بعد از تخفیف ردیف می‌شود؛ ترتیب اولویت: ابتدا amountAfterDiscount و در نبود آن floor(qty × unitPrice) که باید بزرگ‌تر از صفر باشد. مبلغ واحد در این الگو خارج از الگوست (مبلغ واحد در الگوی ۱۱): unitPrice فقط وقتی لازم است که amountAfterDiscount ارسال نشود، می‌تواند اعشاری باشد، در کنار amountAfterDiscount نادیده گرفته می‌شود ولی در هر حال نباید منفی باشد، و به سامانه مؤدیان ارسال نمی‌شود. مبلغ واحد ذخیره‌شده همیشه از مبلغ بعد از تخفیف محاسبه می‌شود، نه از unitPrice ارسالی؛ برای مثال qty=3 و unitPrice=333333.9 به adis=1000001 و مبلغ واحد نمایشی 333333.7 می‌رسد. فقط یک قلم مجاز است، discount غیرصفر با V79_OUT_OF_PATTERN رد می‌شود و vatRate الزامی است و باید 0 باشد. carat (عیار) اختیاری است و 0 یعنی ارسال‌نشده؛ مقدار دیگر باید بزرگ‌تر از صفر، حداکثر 1000 و حداکثر ۲ رقم اعشار. invoiceSubject=4، contractCode، billNo، tax17، payments، اطلاعات ارزی، سایر مالیات‌ها و contractNo در این الگو پذیرفته نمی‌شوند.
inp=13 بیمهinsPolicyNo, extInsPolicyNoشناسه بیمه‌نامه 9 تا 12 رقم است؛ شناسه الحاقیه اختیاری است.
inp=14 فروش زنجیرهitemsفقط یک قلم کالا یا خدمت مجاز است. نرخ مالیات بر ارزش افزوده (vatRate) در این الگو ۰ است و نرخ بیشتر از صفر رد می‌شود.

نمونه ورودی ساده آرایه‌ای

salesWithBuyerData request
{
  "uuid": "4d3d2921-6129-4a8b-9dc2-0ef08c2bf4fa",
  "data": [
    {
      "internalId": "INV-10001",
      "no": "A10001",
      "dateTime": "20260705113000",
      "isArticle9": false,
      "invoiceSubject": 1,
      "settlement": 1,
      "send": true,
      "fiscalId": "SND123",
      "sandBox": true,
      "buyer": {
        "type": 2,
        "nationalCode": "10100000000",
        "economicCode": "10987654321000",
        "zipCode": "1234567890",
        "name": "شرکت خریدار نمونه",
        "mobile": "09120000000",
        "address": "تهران، خیابان نمونه، پلاک ۱",
        "phone": "02188770000",
        "branchCode": 1
      },
      "items": [
        {
          "internalId": "ITEM-1001",
          "stuffId": "1234567890123",
          "description": "کالای نمونه",
          "qty": 2,
          "unit": "1627",
          "unitPrice": 5000000,
          "discount": 0,
          "vatRate": 10
        }
      ],
      "payments": [
        {
          "type": 2,
          "dateTime": "20260705113000",
          "price": 11000000
        }
      ]
    }
  ]
}

نمونه فیلدهای الگوهای خاص

special template fields
{
  "flightTicket": {
    "endpoint": "/api/invoice/flightTicket",
    "addToEachDataItem": {
      "flightInfo": {
        "flightType": 1,
        "buyerMethod": 1,
        "nationalId": "0012345678",
        "agentEconomicCode": "10987654321000"
      }
    }
  },
  "billOfLading": {
    "endpoint": "/api/invoice/billOfLading",
    "addToEachDataItem": {
      "shipmentInfo": {
        "blNumber": "123456789",
        "originCountry": "033",
        "originCity": "284",
        "destinationCountry": "033",
        "destinationCity": "12",
        "senderEconomicCode": "0012345678",
        "receiverEconomicCode": "10987654321",
        "transportType": "1",
        "fleetNumber": "IR-12-345",
        "driverIdCode": "0012345678",
        "totalWeight": 1250,
        "shippedItems": [
          { "stuffId": "1234567890123", "name": "کالای حمل‌شده" }
        ]
      }
    }
  },
  "insurance": {
    "endpoint": "/api/invoice/insurance",
    "typeTwoEndpoint": "/api/invoice/insuranceEndUser",
    "addToEachDataItem": {
      "insPolicyNo": "123456789",
      "extInsPolicyNo": "987654321"
    }
  },
  "oilProducts": {
    "endpoint": "/api/invoice/oilProducts",
    "typeTwoEndpoint": "/api/invoice/oilProductsEndUser"
  },
  "commoditySecurities": {
    "endpoint": "/api/invoice/commoditySecurities",
    "addToEachDataItem": {
      "saleAnnNo": "1405012345",
      "saleAnnDate": "20260705"
    }
  }
}

فیلدهای flightInfo (الگوی ۶)

فیلدقاعده
flightType1 داخلی، 2 خارجی.
buyerMethod1 شماره ملی، 2 کد فراگیر اتباع، 3 گذرنامه. اگر نفرستید، از شناسه‌ای که فرستاده‌اید تعیین می‌شود.
nationalId۱۰ رقم؛ با buyerMethod=1 الزامی است.
foreignId۱۲ رقم؛ با buyerMethod=2 الزامی است.
passportNumberحداکثر ۹ نویسه؛ با buyerMethod=3 و فقط در پرواز خارجی (flightType=2).
economicCode، agentEconomicCode۱۱ تا ۱۴ رقم؛ به ترتیب در tinb و tinc فرستاده می‌شوند.

فیلدهای shipmentInfo (الگوی ۸)

فیلدقاعده
blNumberالزامی، حداکثر ۱۸ رقم.
refBlNumberاختیاری، حداکثر ۱۸ رقم.
senderEconomicCode، receiverEconomicCodeالزامی؛ ۱۰، ۱۱ یا ۱۲ رقم.
transportType"1" جاده‌ای، "2" ریلی، "3" هوایی، "4" دریایی.
fleetNumberالزامی، حداکثر ۲۰ نویسه.
totalWeightبزرگ‌تر از صفر.
shippedItems[]هر عضو با stuffId ۱۳ رقمی و name حداکثر ۴۰۰ نویسه.

در الگوی صادرات (inp=7)، netWeight، currencyValue و currencyRate باید بزرگ‌تر از صفر باشند و currencyCode الزامی است. با کنترل کامل قواعد RC_IITP.IS_V7.9، در الگوهای ۶ و ۸ مقدار qty باید ۱ باشد (V79_AMOUNT_MUST_BE_ONE).

نمونه کامل مدل ساده برای الگوی بورس (/api/invoice/commoditySecurities)

اصلاحی (invoiceSubject: 2) در این الگو هم تابع وضعیت تأیید اعلامیه فروش بورس است: پس از ثبت «تأیید شده» با /api/invoice/exchangeAnnouncement یا در پنل، اصلاحی با کد EXCHANGE_ANNOUNCEMENT_CONFIRMED در مسیر $.data[i].sourceInternalId یا $.data[i].sourceTaxId (یا $.data[i]) رد می‌شود و فقط ابطال مجاز است. جزئیات در قاعده اصلاحی الگوی ۱۱.

این نمونه همان مسیر /api/invoice/simple/type/1/template/11 را هم پوشش می‌دهد. saleAnnDate می‌تواند yyyyMMdd، yyyyMMddHHmmss، Unix time یا تاریخ شمسی 1405/04/14 باشد و به همان روز تقویمی ذخیره و ارسال می‌شود. در روش تسویه 3، مقدار payment سهم نقدی است. مطابق نمونه، ارزش معامله در اعلامیه فروش بورس را در amountAfterDiscount بفرستید و unitPrice را حذف کنید؛ مبلغ واحد نمایشی از همین مبلغ محاسبه می‌شود (جدول مبالغ الگوی ۱۱).

commoditySecurities request
{
  "uuid": "0c7f5f0e-8a3d-4a53-9f5c-1d2b3c4d5e6f",
  "data": [
    {
      "internalId": "IME-2001",
      "no": "A20001",
      "dateTime": "20260705113000",
      "invoiceSubject": 1,
      "settlement": 3,
      "payment": 400000,
      "send": false,
      "fiscalId": "SND123",
      "sandBox": true,
      "saleAnnNo": "1405012345",
      "saleAnnDate": "20260705",
      "buyer": { "type": 2, "economicCode": "10987654321000", "zipCode": "1234567890" },
      "items": [
        {
          "stuffId": "1234567890123",
          "description": "کالای معامله‌شده در بورس کالا",
          "qty": 3,
          "unit": "1627",
          "amountAfterDiscount": 1000001,
          "vatRate": 0
        }
      ]
    }
  ]
}

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

صورتحساب اصلاحی در مدل ساده
{
  "uuid": "2df1926a-486c-4dd7-9b02-882e1e5a5c4a",
  "data": [
    {
      "internalId": "INV-10001-EDIT",
      "sourceInternalId": "INV-10001",
      "no": "A10002",
      "dateTime": "20260705123000",
      "invoiceSubject": 2,
      "settlement": 1,
      "send": false,
      "fiscalId": "SND123",
      "sandBox": true,
      "buyer": { "type": 2, "nationalCode": "10100000000", "economicCode": "10987654321000", "zipCode": "1234567890" },
      "items": [
        { "stuffId": "1234567890123", "description": "کالای اصلاح‌شده", "qty": 2, "unit": "1627", "unitPrice": 5200000, "vatRate": 10 }
      ]
    }
  ]
}

برای ابطال، cancelInvoice را به کار ببرید. اگر ابطالی را با مدل ساده (invoiceSubject: 3) می‌فرستید، آرایه items هم باید دست‌کم یک قلم داشته باشد. در صورتحساب ارجاعی، fiscalId و sandBox باید همان صورتحساب مرجع باشد (حافظه مالیاتی).

خریدار در صورتحساب اصلاحی، ابطالی و برگشت از فروش: طبق جدول ۱ دستورالعمل RC_IITP.IS_V7.9، وقتی invoiceSubject برابر ۲، ۳ یا ۴ است، فیلدهای tob، tinb، bid، bbc، bpn و sbc در سرآمد خارج از الگو هستند و خریدار همان خریدار صورتحساب مرجع است. مسیرهای مدل ساده این فیلدها را در JSON ساخته‌شده نمی‌گذارند و کد پستی bpc فقط جایی می‌ماند که قواعد اجازه دهند؛ simple/editInvoice هم وقتی اصلاحی صادر می‌کند همین‌طور عمل می‌کند. مسیرهای نوع ۱ (جز صادرات inp=7 و بورس inp=11)، مانند /api/invoice/salesWithBuyerData در نمونه بالا، همچنان شیء buyer را می‌پذیرند و لازم دارند؛ این خریدار باید همان خریدار صورتحساب مرجع باشد، وگرنه آن عضو با پیام مغایرت خریدار ثبت نمی‌شود. در مسیرهای نوع ۲، مانند /api/invoice/salesEndUser، می‌توانید buyer را حذف کنید.
نمونه بالا برای الگوهای عمومی است و در الگوی ۱۱ پذیرفته نمی‌شود. برای اصلاحی الگوی ۱۱ در /api/invoice/commoditySecurities، invoiceSubject: 2 و sourceInternalId را همراه saleAnnNo، saleAnnDate و amountAfterDiscount جدید بفرستید؛ unitPrice لازم نیست، vatRate الزامی است و باید 0 باشد و discount غیرصفر پذیرفته نمی‌شود. این اصلاحی فقط تا پیش از تأیید اعلامیه فروش بورس مجاز است (قاعده اصلاحی الگوی ۱۱).
13ثبت و پیگیری صورتحساب

ارسال دستی به سازمان امور مالیاتی و ثبت صورتحساب ابطالی

مسیرscopeبدنهخروجی
POST /api/invoice/sendInvoicev2.invoice.send{ "internalIds": ["INV-10001"] }صورتحساب‌های ثبت‌شده به‌صورت دستی در صف ارسال به سازمان امور مالیاتی قرار می‌گیرند. برای هر internalId، آخرین صورتحساب زنجیره آن در نظر گرفته می‌شود؛ یعنی اگر برای آن اصلاحی، ابطالی یا برگشت از فروش ثبت شده باشد (حتی ارسال‌نشده)، همان آخرین صورتحساب در صورت ارسال‌نشده بودن در صف ارسال قرار می‌گیرد و اگر قبلاً ارسال شده باشد فقط وضعیت آن برمی‌گردد. اگر حتی یک شناسه خطا بگیرد، پاسخ result: 0 است و خطای آن شناسه در errors می‌آید. شناسه‌های سالم همان درخواست در صف ارسال قرار می‌گیرند و وضعیت آن‌ها در data همین پاسخ برمی‌گردد؛ اگر هیچ شناسه‌ای به این مرحله نرسد، data برابر null است.
POST /api/invoice/cancelInvoicev2.invoice.cancelinternalId مرجع، uuid و در صورت نیاز cancelInternalIdصورتحساب ابطالی ثبت می‌شود؛ مقدار صریح send اولویت دارد و در نبود آن، تنظیم ارسال خودکار «API نسخه ۲» کسب‌وکار اعمال می‌شود. قواعد ابطال در فهرست زیر آمده است. توکنی که scope v2.invoice.cancel ندارد، پاسخ result: -1 می‌گیرد.

ارسال دستی با sendInvoice

در internalIds دست‌کم یک شناسه بفرستید؛ آرایه خالی پاسخ result: 0 با خطا در مسیر $.internalIds می‌گیرد. خطای هر شناسه در مسیر $.internalIds[i] می‌آید و ممکن است کد EXCHANGE_ANNOUNCEMENT_* یا INVOICE_SEND_RESULT_UNKNOWN داشته باشد. هر درخواست حداکثر ۵۰۰ شناسه می‌پذیرد. درخواستی با شناسه‌های بیشتر پیش از هر ارسالی با result: 0 و خطا در مسیر $.internalIds رد می‌شود. هر شناسه جداگانه ارسال می‌شود، پس برای کوتاه ماندن زمان پاسخ، شناسه‌های زیاد را در چند درخواست بفرستید.

درخواست sendInvoice
{ "internalIds": ["INV-10001", "INV-10002"] }
پاسخ sendInvoice
{
  "result": 1,
  "traceId": "…",
  "message": "درخواست ارسال صورتحساب‌ها با موفقیت در صف قرار گرفت.",
  "data": [
    { "asatspId": 105234, "taxId": "…", "isDefaultFiscalMemory": true, "status": 1, "issue": 1, "internalId": "INV-10001" }
  ]
}

قواعد ابطال با cancelInvoice

  • ابطال برای آخرین صورتحساب زنجیره internalId ثبت می‌شود و آن صورتحساب باید ارسال‌شده و دارای شماره مالیاتی باشد؛ اگر آخرین صورتحساب زنجیره اصلاحی ارسال‌نشده یا بی‌نتیجه باشد، درخواست با خطا در مسیر $.internalId رد می‌شود.
  • پیش از ثبت، وضعیت زنجیره مانند «ابطال» پنل از کارپوشه گرفته می‌شود (کدهای خطا).
  • تاریخ صدور ابطالی ابتدای دقیقه پیش از زمان ثبت است تا در ارسال فوری، تفاوت ساعت سرورها آن را «آینده» نشان ندهد، ولی هیچ‌گاه پیش از تاریخ و ساعت دقیق صورتحساب مرجع (تا ثانیه، با گرد شدن رو به بالا) نیست؛ طبق RC_IITP.IS_V7.9 (قاعده ۳ فیلد indatim) تاریخ صدور ابطالی نباید از تاریخ صدور مرجع کوچک‌تر باشد. ساعت سرور ممکن است چند ده ثانیه از ساعت واقعی عقب باشد؛ برای همین، ابطالی مرجعی که تازه ثبت شده با همان تاریخ و ساعت مرجع صادر می‌شود.
  • اگر آخرین صورتحساب زنجیره ابطالی ثبت‌نشده همین زنجیره باشد، ابطال دوم کنار آن ثبت نمی‌شود: ابطالی ردشده حذف و ابطال تازه ثبت می‌شود و ابطالی ارسال‌نشده یا بی‌نتیجه با کد خطا رد می‌شود (ابطالی ناموفق، ارسال‌نشده یا بی‌نتیجه).
cancelInvoice request
{
  "uuid": "74ff263d-bf33-40df-a56d-91f07bb1624b",
  "internalId": "INV-10001",
  "cancelInternalId": "INV-10001-CANCEL",
  "send": true,
  "description": "ابطال به درخواست مشتری"
}
فیلدقاعدهتوضیح
uuidالزامی، GUIDشناسه این درخواست؛ برای هر درخواست تازه مقدار تازه بسازید.
internalIdالزامیکد داخلی صورتحساب مرجع؛ ابطال روی آخرین صورتحساب زنجیره آن ثبت می‌شود.
cancelInternalIdاختیاریکد داخلی صورتحساب ابطالی؛ پیش‌فرض {internalId}-cancel.
sendاختیاری، booleanمانند /send؛ در نبود آن، تنظیم ارسال خودکار «API نسخه ۲» کسب‌وکار اعمال می‌شود.
descriptionاختیاریتوضیح صورتحساب ابطالی؛ پیش‌فرض «ابطال صورتحساب {شماره}».
tokenاختیاریفقط همراه کلید ثابت قدیمی معنا دارد و با Access Token نادیده گرفته می‌شود.

پاسخ موفق پیام «صورتحساب ابطالی با موفقیت ثبت شد.» دارد و data[0] اطلاعات صورتحساب ابطالی تازه است (internalId برابر cancelInternalId و issue: 3). درخواست تکراری پاسخ result: -2 با پیام «درخواست ابطال تکراری است.» می‌گیرد: کد INVOICE_DUPLICATE_REQUEST در مسیر $.uuid یعنی uuid تکراری است و INVOICE_INTERNAL_ID_DUPLICATE در مسیر $.internalId یعنی cancelInternalId پیش‌تر به کار رفته است.

اگر ثبت ابطالی به‌دلیل ارسال قبلی با نتیجه نامشخص یا خطای گذرای پایگاه داده کامل نشود، پاسخ result: 0 با message «ثبت صورتحساب ابطالی انجام نشد.» است و خطای آن کد INVOICE_SEND_RESULT_UNKNOWN یا INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE دارد (در مسیر $، یا $.internalId اگر خطا هنگام گرفتن وضعیت زنجیره رخ دهد). با کد نخست، ابطالی ثبت نشده است و پس از مشخص شدن نتیجه ارسال قبلی می‌توانید دوباره درخواست دهید. با کد دوم، ابتدا آخرین صورتحساب زنجیره را با inquiryInternalId و internalId مرجع استعلام کنید و اگر ابطال ثبت نشده بود، cancelInvoice را با uuid تازه دوباره فراخوانی کنید.

پاسخ cancelInvoice
{
  "result": 1,
  "traceId": "…",
  "message": "صورتحساب ابطالی با موفقیت ثبت شد.",
  "data": [
    {
      "asatspId": 105240,
      "taxId": "A1B2C304E7900000F42411",
      "fiscalId": "A1B2C3",
      "sandBox": false,
      "environment": "Production",
      "isDefaultFiscalMemory": true,
      "status": 0,
      "issue": 3,
      "internalId": "INV-10001-CANCEL"
    }
  ]
}
ابطالی ناموفق، ارسال‌نشده یا بی‌نتیجه: اگر آخرین صورتحساب زنجیره، ابطالیِ همین زنجیره باشد که در سامانهٔ مؤدیان ثبت نشده است، cancelInvoice هیچ‌گاه ابطال دومی کنار آن نمی‌سازد. رفتار به وضعیت همان ابطالی بستگی دارد:
  • ردشده (آخرین نتیجهٔ ارسال آن شکست قطعی است، مثلاً خطای 0200201 دربارهٔ تاریخ صدور): آن ابطالی مانند «حذف ابطال ناموفق» پنل حذف (بایگانی) می‌شود و زنجیره به صورتحساب مرجع برمی‌گردد. سپس ابطال تازه از همان مرجع، درست مانند هر ابطال دیگر، ثبت و طبق send ارسال می‌شود: وضعیت زنجیره از کارپوشه گرفته می‌شود، تاریخ صدور طبق قاعدهٔ بالا است و شمارهٔ سریال و شمارهٔ مالیاتی تازه می‌گیرد. پاسخ همان ساختار ثبت ابطال را دارد و message آن «صورتحساب ابطالی قبلی که سامانهٔ مؤدیان آن را رد کرده بود حذف شد و صورتحساب ابطالی تازه ثبت شد.» است. این حذف با کد پیگیری همین درخواست در لاگ برنامهٔ پنل ثبت می‌شود.
  • اگر پس از این حذف، ابطال تازه ثبت نشود (مثلاً وضعیت زنجیره از کارپوشه دریافت نشد، یا ثبت با INVOICE_SEND_RESULT_UNKNOWN یا INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE متوقف شد)، پاسخ result: 0 با message «صورتحساب ابطالی ناموفق قبلی حذف شد، اما صورتحساب ابطالی تازه ثبت نشد.» است؛ نخستین خطا کد FAILED_CANCELLATION_REMOVED_NEW_NOT_REGISTERED دارد و خطای بعدی علت را می‌گوید. حذف برنمی‌گردد و صورتحساب مرجع دوباره آخرین صورتحساب زنجیره است؛ پس از رفع علت، cancelInvoice را با uuid تازه دوباره فراخوانی کنید تا ابطال از مسیر عادی ثبت شود (اگر نتیجه نامشخص بود، ابتدا آخرین صورتحساب زنجیره را با inquiryInternalId و internalId مرجع استعلام کنید).
  • ارسال‌نشده (با send: false ثبت شده و هنوز ارسال نشده): درخواست با کد PREVIOUS_CANCELLATION_UNSENT در مسیر $.internalId رد می‌شود؛ همان ابطالی را با sendInvoice ارسال کنید.
  • بی‌نتیجه (در صف یا در حال ارسال، یا پاسخ سامانهٔ مؤدیان هنوز NOT_FOUND است): درخواست با کد PREVIOUS_CANCELLATION_PENDING در مسیر $.internalId رد می‌شود؛ نتیجه را با inquiryInternalId پیگیری کنید و اگر رد شد، cancelInvoice را دوباره فراخوانی کنید.
  • uuid همیشه باید تازه باشد. cancelInternalId می‌تواند تازه باشد یا همان شناسهٔ ابطالیِ ردشده (اگر در هیچ‌کدام از دو درخواست فرستاده نشود، هر دو بار همان مقدار پیش‌فرض {internalId}-cancel است)؛ این شناسه پس از ثبت، ابطال تازه را برمی‌گرداند. اگر شناسهٔ تازه‌ای فرستاده شود، شناسهٔ ابطالیِ ردشده مانند هر صورتحساب حذف‌شده در پنل دیگر در استعلام پیدا نمی‌شود.
  • ابطالیِ ثبت‌شده مانند قبل با خطا در مسیر $.internalId رد می‌شود.
  • این رفتار فقط برای ابطالی است. اصلاحی یا برگشت از فروشِ ناموفق را با editInvoice اصلاح و ارسال کنید؛ تا وقتی آخرین صورتحساب زنجیره است، cancelInvoice رد می‌شود.
14ثبت و پیگیری صورتحساب

پیگیری وضعیت صورتحساب

سرویس‌های پیگیری وضعیت با Access Token دارای scope v2.invoice.read فراخوانی می‌شوند و آخرین وضعیت پردازش صورتحساب را بازمی‌گردانند. در دوره مهاجرت، Customer API Key قدیمی هم پذیرفته می‌شود.

برای هر سه روش پیگیری، یک مسیر تک‌مقداری و یک مسیر آرایه‌ای وجود دارد. پاسخ این سرویس‌ها قالب همیشگی (result، traceId و message) را ندارد: مسیر تک‌مقداری یک شیء و مسیر آرایه‌ای یک آرایه برمی‌گرداند. مسیر آرایه‌ای حداکثر ۲۵۰ مقدار می‌پذیرد و برای هر مقدار، به همان ترتیب ورودی، یک عضو برمی‌گرداند. اگر احراز هویت ناموفق باشد، یا آرایه خالی باشد یا بیش از ۲۵۰ مقدار داشته باشد، پاسخ آرایه‌ای فقط یک عضو با status: 3 و علت در error دارد؛ پس پیش از تطبیق پاسخ با ورودی، برابر بودن تعداد اعضا را بررسی کنید. مسیر تک‌مقداری هم در خطای احراز هویت شیئی با status: 3 برمی‌گرداند.

مسیرفیلد درخواستکاربرد
POST /api/invoice/inquiryInternalIdinternalIdپیگیری با کد داخلی ارسالی.
POST /api/invoice/inquiryInternalIdsinternalIds[]پیگیری گروهی با کدهای داخلی؛ حداکثر ۲۵۰ مقدار.
POST /api/invoice/inquiryNonoپیگیری با شماره صورتحساب یا inno.
POST /api/invoice/inquiryNosnos[]پیگیری گروهی با شماره‌های صورتحساب یا inno؛ حداکثر ۲۵۰ مقدار.
POST /api/invoice/inquiryTaxIdtaxIdپیگیری با شماره منحصر به فرد مالیاتی.
POST /api/invoice/inquiryTaxIdstaxIds[]پیگیری گروهی با شماره‌های منحصر به فرد مالیاتی؛ حداکثر ۲۵۰ مقدار.
پیگیری وضعیت آخرین صورتحساب زنجیره را برمی‌گرداند. اگر برای صورتحسابی اصلاحی، ابطالی یا برگشت از فروش ثبت شده باشد، پیگیری با internalId یا taxId صورتحساب اصلی، taxId و status همان آخرین صورتحساب را برمی‌گرداند و internalId پاسخ همان مقداری است که فرستاده‌اید. موضوع صورتحساب برگشتی در فیلد issue می‌آید: 1 اصلی، 2 اصلاحی، 3 ابطالی و 4 برگشت از فروش. پیش از ذخیره taxId پاسخ، issue را بررسی کنید تا شماره مالیاتی صورتحساب ارجاعی به‌جای شماره صورتحساب اصلی ثبت نشود.

inquiryNo فقط یک صورتحساب برمی‌گرداند. فاصله‌های ابتدا و انتهای شماره در نظر گرفته نمی‌شود. شماره عددی با مقدار عددی آن مقایسه می‌شود و شماره غیرعددی باید با کل شماره صورتحساب یکسان باشد؛ بخشی از شماره (مثلاً A1 برای A10) صورتحسابی پیدا نمی‌کند. اگر چند صورتحساب این شماره را داشته باشند (مثلاً در دو سال مالی)، مانند گذشته نخستین صورتحسابی که ثبت شده انتخاب می‌شود و وضعیت آخرین صورتحساب زنجیره آن برمی‌گردد. پاسخ inquiryNo فیلد no (همان مقدار ارسالی) را دارد و پاسخ inquiryNo و inquiryTaxId فیلد internalId ندارد. برای پیگیری قطعی از internalId یا taxId استفاده کنید. کد داخلی عددی با مقدار عددی آن مقایسه می‌شود؛ برای نمونه "001" و "1" یک صورتحساب به حساب می‌آیند.

inquiryInternalId body
{
  "internalId": "1000001"
}
inquiryInternalIds body
{
  "internalIds": [
    "1000001",
    "1000002"
  ]
}
inquiryNo body
{
  "no": "A000000001"
}
inquiryNos body
{
  "nos": [
    "A000000001",
    "A000000002"
  ]
}
inquiryTaxId body
{
  "taxId": "A1B2C3D4E5F6G7H8I9J0K1"
}
inquiryTaxIds body
{
  "taxIds": [
    "A1B2C304E7900000F42410",
    "SND12304E7900000F42411"
  ]
}
cURL / batch inquiry
curl -X POST "https://api-v2.asatsp.ir/api/invoice/inquiryInternalIds" \
  -H "Authorization: Bearer <AccessToken with v2.invoice.read>" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"internalIds":["1000001","1000002"]}'

نمونه پاسخ آرایه‌ای

در پاسخ گروهی، شناسه جست‌وجوشده روی همان عضو بازگردانده می‌شود. یافت‌نشدن یک صورتحساب مانع پیگیری سایر اعضا نیست.

inquiryInternalIds response
[
  {
    "asatspId": 105234,
    "taxId": "A1B2C304E7900000F42410",
    "fiscalMemoryId": 31,
    "fiscalId": "A1B2C3",
    "fiscalMemoryTitle": "شناسه اصلی",
    "sandBox": false,
    "environment": "Production",
    "environmentTitle": "عملیاتی",
    "isDefaultFiscalMemory": true,
    "status": 2,
    "issue": 1,
    "internalId": "1000001",
    "refrenceNumber": "…",
    "json": { "…": "همان صورتحساب ارسال‌شده به سامانه مؤدیان" },
    "statusInquery": "…"
  },
  {
    "isDefaultFiscalMemory": false,
    "status": 3,
    "error": ["صورتحساب یافت نشد"],
    "internalId": "1000002"
  }
]

وضعیت‌های رایج

statusمعنااقدام پیشنهادی
0ثبت‌شده و هنوز ارسال‌نشدهاگر با send: false یا با ارسال خودکار خاموش ثبت شده است، sendInvoice را فراخوانی کنید؛ در غیر این صورت چند دقیقه بعد دوباره پیگیری کنید.
1در صف ارسال یا ارسال‌شده و در انتظار پاسخ سامانه مؤدیانپس از چند دقیقه، وضعیت را دوباره پیگیری کنید.
2موفقشماره مرجع و taxId را ذخیره کنید.
3دارای خطاپیام خطا را در error بررسی کنید؛ در این وضعیت json برنمی‌گردد. اگر سامانه مؤدیان صورتحساب را رد کرده است، آن را با editInvoice اصلاح و دوباره ارسال کنید. پاسخ بدون asatspId یعنی صورتحساب پیدا نشد یا خود درخواست رد شد.
7پیش‌فاکتور (proforma)ارسال نمی‌شود و taxId ندارد؛ اعتبار و نتیجهٔ تبدیل را در proforma ببینید و در صورت نیاز در پنل به صورتحساب تبدیل کنید.
refrenceNumber (شماره مرجع سامانه مؤدیان) فقط در وضعیت‌های 1 و 2 برمی‌گردد (در وضعیت 1 ممکن است هنوز خالی باشد) و در وضعیت‌های 0 و 3 نمی‌آید. فقط در وضعیت 2 (موفق)، json (همان payload ارسال‌شده به سامانه مؤدیان) و در صورت وجود مقدار، statusInquery (وضعیت صورتحساب/واکنش خریدار در سامانه مؤدیان) و article6Status (وضعیت ماده ۶: عدول یا عدم عدول) هم برمی‌گردند. پاسخ پیگیری فیلد جداگانه‌ای برای ردیف‌ها ندارد. در الگوی ۱۱، در json.Body[0] adis و am مقدار دارند ولی fee، prdis و dis مقداری ندارند (برابر null هستند یا اصلاً نمی‌آیند)؛ مبلغ واحد نمایشی ذخیره‌شده در پاسخ پیگیری برنمی‌گردد (مبلغ واحد در الگوی ۱۱). اگر صورتحساب موفق هنوز پاسخ نهایی سامانه مؤدیان را ندارد (statusInquery خالی یا AWAITING_REACTION)، پیگیری همان «استعلام وضعیت» پنل را انجام می‌دهد: پاسخ ذخیره می‌شود و زنجیرهٔ صورتحساب هم به‌روز می‌شود؛ مثلاً با پذیرش یک ابطالی، صورتحساب مرجع آن همان لحظه «ابطال‌شده» می‌شود. پاسخ، وضعیت صورتحساب پس از این به‌روزرسانی است.

مقدارهای رایج statusInquery: AWAITING_REACTION، NO_NEED_REACTION، APPROVED، REJECTED، CANCELED، SYSTEMIC_APPROVED، SYSTEMIC_REJECTED و IMPOSSIBLE_REACTION. مقدار article6Status یکی از EXCEEDED یا NOT_EXCEEDED است. این مقدارها را سامانه مؤدیان تعیین می‌کند و ممکن است مقدار تازه‌ای به آن‌ها اضافه شود؛ مقدار ناشناخته را خطا ندانید.

15ثبت و پیگیری صورتحساب

ویرایش و اصلاح صورتحساب

با این دو سرویس، صورتحسابی را که قبلاً ثبت کرده‌اید با همان رفتار پنل معتمد آسا ویرایش می‌کنید: کل صورتحساب را با محتوای تازه می‌فرستید و سامانه تشخیص می‌دهد چه باید بشود. صورتحسابی که هنوز به سامانهٔ مؤدیان نرفته، نسخهٔ تازه‌ای از خودش می‌شود؛ صورتحسابی که در سامانهٔ مؤدیان ثبت شده با صورتحساب اصلاحی (موضوع ۲، مطابق بند ۵-۲ دستورالعمل صدور صورتحساب الکترونیکی RC_IITP.IS_V7.9) تغییر می‌کند و اصلاحی فقط با تأیید صریح شما صادر می‌شود. هر ویرایش نسخهٔ تازه‌ای می‌سازد و نسخهٔ قبلی در سوابق می‌ماند.

مسیرscopeبدنهکاربرد
POST /api/invoice/editInvoicev2.invoice.senduuid، internalId یا taxId، data (JSON سازمان)ویرایش با ساختار رسمی Header، Body و Payments؛ همان ساختار و قواعد ثبت صورتحساب با JSON استاندارد.
POST /api/invoice/simple/editInvoicev2.invoice.senduuid، internalId یا taxId، data (مدل ساده)ویرایش با همان مدل ساده؛ نوع و الگو همان صورتحساب می‌ماند.

نتیجهٔ ویرایش در هر وضعیت

وضعیت صورتحسابنتیجهedit.outcome
ارسال‌نشده یا ناموفق؛ همچنین اصلاحی یا برگشتی که هنوز ارسال نشدهنسخهٔ تازهٔ همان صورتحساب با همان شماره سریال، بدون نیاز به تأیید. اگر تاریخ صدور عوض شود، شماره مالیاتی هم عوض می‌شود.draftUpdated
ثبت‌شده در سامانهٔ مؤدیان و فقط ردیف‌های پرداخت تغییر کرده استنسخهٔ تازه با همان شماره مالیاتی؛ پرداخت‌های تازه در کارپوشه ثبت می‌شوند (مانند ثبت پرداخت) و اصلاحی صادر نمی‌شود.paymentUpdated
ثبت‌شده و هر تغییر دیگر، از جمله روش تسویهصورتحساب اصلاحی با شماره مالیاتی تازه که مرجع آن همین صورتحساب است؛ فقط با تأیید صریح.correctionIssued یا confirmationRequired
هیچ تغییری نکرده استچیزی ثبت نمی‌شود.unchanged
در صف ارسال، با نتیجهٔ نامشخص، ابطال‌شده یا خودش ابطالیویرایش نمی‌شود و خطای کددار برمی‌گردد (کدها).—
تأیید صریح صورتحساب اصلاحی

دو راه دارد. دو مرحله‌ای: درخواست را بدون تأیید بفرستید؛ اگر تغییرات اصلاحی صادر کند، چیزی ثبت نمی‌شود و پاسخ با result: 0، کد INVOICE_CORRECTION_CONFIRMATION_REQUIRED و edit.confirmationToken برمی‌گردد. همان درخواست را با همان محتوا و همراه این توکن (حداکثر تا ۱۵ دقیقه) دوباره بفرستید تا اصلاحی صادر شود. یک مرحله‌ای: اگر از اول می‌دانید ویرایش اصلاحی صادر می‌کند و آن را می‌خواهید، confirmCorrection: true بفرستید تا در همان درخواست صادر شود و تأیید دوباره لازم نباشد.

توکن به همان محتوا و همان صورتحساب گره خورده است

اگر محتوا را عوض کنید (INVOICE_EDIT_CONFIRMATION_MISMATCH)، مهلت ۱۵ دقیقه بگذرد (INVOICE_EDIT_CONFIRMATION_EXPIRED) یا صورتحساب در این فاصله تغییر کند، مثلاً از پنل (INVOICE_EDIT_CONFIRMATION_STALE)، چیزی ثبت نمی‌شود؛ درخواست را بدون توکن بفرستید تا تأیید تازه بگیرید. توکن یک‌بار مصرف است، چون پس از صدور اصلاحی، صورتحساب جاری عوض می‌شود.

آنچه در اصلاحی ثابت می‌ماند

طبق بند ۵-۲ دستورالعمل، نوع و الگوی صورتحساب، اطلاعات خریدار، شناسهٔ کالا/خدمت (کالای تازه افزوده نمی‌شود) و نرخ مالیات بر ارزش افزوده در اصلاحی تغییر نمی‌کنند. چنین درخواستی با INVOICE_EDIT_FIELD_NOT_CORRECTABLE (نام فیلد در field) یا کد خریدار سامانه رد می‌شود. برای این تغییرها صورتحساب را با cancelInvoice ابطال و صورتحساب جدید صادر کنید.

کدام صورتحساب ویرایش می‌شود

صورتحساب را با internalId یا taxId (فقط یکی) مشخص کنید. سامانه نسخهٔ جاری زنجیرهٔ آن را پیدا می‌کند؛ مثلاً اگر روی آن اصلاحیِ ارسال‌نشده‌ای هست، همان پیش‌نویس ویرایش می‌شود. اصلاحِ یک اصلاحی فقط پس از تأیید آن در سامانهٔ مؤدیان ممکن است. حافظهٔ مالیاتی و محیط (Sandbox یا عملیاتی) همان صورتحساب می‌ماند.

وضعیت صورتحساب در کارپوشه

پیش از اصلاحی، وضعیت زنجیره مانند پنل از کارپوشه گرفته می‌شود: آخرین استعلامِ کمتر از ۲ ساعت مستقیم استفاده می‌شود، بین ۲ تا ۲۴ ساعت دوباره استعلام می‌شود (اگر کارپوشه پاسخ ندهد، همان آخرین استعلام مبناست) و بیش از ۲۴ ساعت حتماً استعلام می‌شود. اگر استعلام ممکن نباشد، خطای INVOICE_REFERENCE_STATUS_UNAVAILABLE برمی‌گردد؛ کمی بعد دوباره تلاش کنید.

تکرار درخواست و اطلاعات پنل

uuid هر درخواست در محدودهٔ شرکت یکتاست و تا چیزی ثبت نشود مصرف نمی‌شود؛ پس درخواست تأییدشده می‌تواند همان uuid مرحلهٔ اول را داشته باشد. پس از ثبت، تکرار همان uuid با result: -2 و INVOICE_EDIT_DUPLICATE_REQUEST رد می‌شود. اطلاعاتی که فقط در پنل هست (توضیح خریدار، قالب چاپ، پیوست‌ها، و توضیح صورتحساب اگر description نفرستید) از صورتحساب فعلی حفظ می‌شود.

فیلدهای درخواست

فیلدقاعدهتوضیح
tokenاختیاریتوکن تکمیلی نمایندگی، مانند سایر سرویس‌ها.
uuidالزامی، GUID یکتا برای شرکتشناسهٔ این درخواست.
internalId یا taxIdدقیقاً یکی الزامیکد داخلی یا شماره مالیاتی ۲۲ کاراکتری صورتحسابی که ویرایش می‌شود. نسخهٔ تازه همان internalId را نگه می‌دارد و استعلام با آن، نسخهٔ جاری را برمی‌گرداند.
dataالزامیکل صورتحساب با محتوای تازه: در editInvoice شیء Header، Body و Payments با قواعد /send؛ در simple/editInvoice همان عضو data[] مدل ساده. موضوع (ins یا invoiceSubject) و مرجع (irtaxid یا sourceTaxId) را سامانه تعیین می‌کند و مقدار ارسالی نادیده گرفته می‌شود؛ internalId، fiscalId و sandBox داخل data مدل ساده هم اثری ندارند. در simple/editInvoice فیلدهای no و dateTime را همیشه بفرستید؛ نبودن dateTime تاریخ صدور را زمان حال می‌کند.
sendاختیاریمانند /send: true ارسال خودکار، false بدون ارسال، و نبودن آن یعنی تنظیم ارسال خودکار API نسخه ۲ کسب‌وکار.
confirmCorrectionاختیاری، true یا falsetrue: اگر تغییرات صورتحساب اصلاحی صادر کند، در همین درخواست صادر شود. روی صورتحساب ارسال‌نشده اثری ندارد.
confirmationTokenاختیاریتوکن پاسخ confirmationRequired برای صدور همان اصلاحی، حداکثر تا ۱۵ دقیقه. با confirmCorrection: true لازم نیست.
descriptionاختیاری، فقط در editInvoiceتوضیح صورتحساب؛ اگر نفرستید، توضیح فعلی می‌ماند. در مدل ساده همان data.description است.
editInvoice request (مقدار قلم از ۲ به ۳)
{
  "uuid": "6b0d1f0e-3a52-4f7c-9a1d-2f0b6c9e4a10",
  "internalId": "1000001",
  "send": true,
  "data": {
    "Header": {
      "indatim": 1782940800000,
      "inty": 1,
      "inp": 1,
      "inno": "A000000001",
      "tins": "12345678901234",
      "tob": 2,
      "tinb": "10987654321000",
      "bpc": "1234567890",
      "setm": 1,
      "tprdis": 15000000,
      "tdis": 0,
      "tadis": 15000000,
      "tvam": 1500000,
      "todam": 0,
      "tbill": 16500000,
      "cap": 16500000,
      "insp": 0,
      "tvop": 1500000
    },
    "Body": [
      {
        "sstid": "1234567890123",
        "sstt": "کالای نمونه",
        "mu": "1627",
        "am": 3,
        "fee": 5000000,
        "prdis": 15000000,
        "dis": 0,
        "adis": 15000000,
        "vra": 10,
        "vam": 1500000,
        "odam": 0,
        "olam": 0,
        "tsstam": 16500000
      }
    ],
    "Payments": [
      {
        "pdt": 1782940800000,
        "pmt": 2,
        "pv": 16500000
      }
    ]
  }
}

اگر این صورتحساب در سامانهٔ مؤدیان ثبت شده باشد، پاسخ اول تأیید می‌خواهد و چیزی ثبت نمی‌شود:

editInvoice response: confirmationRequired
{
  "result": 0,
  "traceId": "3c1f9a52-7d0e-4b6a-8f21-5e9d0c4b7a13",
  "message": "صورتحساب اصلاحی بدون تأیید صادر نمی‌شود؛ چیزی ثبت نشد.",
  "errors": [
    {
      "code": "INVOICE_CORRECTION_CONFIRMATION_REQUIRED",
      "path": "$",
      "message": "این تغییرات روی صورتحسابی که در سامانهٔ مؤدیان ثبت شده، صورتحساب اصلاحی صادر می‌کند و صدور آن تأیید صریح شما را می‌خواهد. برای صدور آن، همین درخواست را همراه confirmationToken این پاسخ (حداکثر تا ۱۵ دقیقه) دوباره بفرستید."
    }
  ],
  "edit": {
    "outcome": "confirmationRequired",
    "previousTaxId": "A111H104EA6001D0B32AC6",
    "referenceTaxId": "A111H104EA6001D0B32AC6",
    "reason": "FIELDS_CHANGED",
    "confirmationToken": "ec1.1782941700000.105234.9b2f0c4e5d1a7f3b8c6e2d4a0f9b1c3e5d7a9f2b4c6e8d0a1f3b5c7e9d2a4f6b",
    "expiresAt": 1782941700000
  }
}

همان درخواست با همان محتوا و همراه توکن، اصلاحی را صادر می‌کند (به‌جای توکن می‌توانستید از اول "confirmCorrection": true بفرستید):

editInvoice request: confirmed
{
  "uuid": "6b0d1f0e-3a52-4f7c-9a1d-2f0b6c9e4a10",
  "internalId": "1000001",
  "send": true,
  "confirmationToken": "ec1.1782941700000.105234.9b2f0c4e5d1a7f3b8c6e2d4a0f9b1c3e5d7a9f2b4c6e8d0a1f3b5c7e9d2a4f6b",
  "data": {
    "Header": {
      "indatim": 1782940800000,
      "inty": 1,
      "inp": 1,
      "inno": "A000000001",
      "tins": "12345678901234",
      "tob": 2,
      "tinb": "10987654321000",
      "bpc": "1234567890",
      "setm": 1,
      "tprdis": 15000000,
      "tdis": 0,
      "tadis": 15000000,
      "tvam": 1500000,
      "todam": 0,
      "tbill": 16500000,
      "cap": 16500000,
      "insp": 0,
      "tvop": 1500000
    },
    "Body": [
      {
        "sstid": "1234567890123",
        "sstt": "کالای نمونه",
        "mu": "1627",
        "am": 3,
        "fee": 5000000,
        "prdis": 15000000,
        "dis": 0,
        "adis": 15000000,
        "vra": 10,
        "vam": 1500000,
        "odam": 0,
        "olam": 0,
        "tsstam": 16500000
      }
    ],
    "Payments": [
      {
        "pdt": 1782940800000,
        "pmt": 2,
        "pv": 16500000
      }
    ]
  }
}
editInvoice response: correctionIssued
{
  "result": 1,
  "traceId": "8e4b2d61-0c9f-4a37-b5e8-1d6f3a9c2e70",
  "message": "صورتحساب اصلاحی ثبت شد.",
  "data": [
    {
      "asatspId": 105240,
      "taxId": "A111H104EA6001D0B32B07",
      "isDefaultFiscalMemory": true,
      "status": 0,
      "issue": 2,
      "internalId": "1000001"
    }
  ],
  "edit": {
    "outcome": "correctionIssued",
    "previousTaxId": "A111H104EA6001D0B32AC6",
    "taxId": "A111H104EA6001D0B32B07",
    "referenceTaxId": "A111H104EA6001D0B32AC6",
    "confirmedBy": "confirmationToken"
  }
}

ویرایش با مدل ساده و تأیید از پیش (confirmCorrection):

simple/editInvoice request
{
  "uuid": "a7c3e9f1-5b2d-4e8a-9c6f-0d1b3e5a7c90",
  "internalId": "INV-10001",
  "confirmCorrection": true,
  "data": {
    "no": "A10001",
    "dateTime": "20260705113000",
    "settlement": 1,
    "buyer": {
      "type": 2,
      "nationalCode": "10100000000",
      "economicCode": "10987654321000",
      "zipCode": "1234567890"
    },
    "items": [
      {
        "stuffId": "1234567890123",
        "description": "کالای نمونه",
        "qty": 3,
        "unit": "1627",
        "unitPrice": 5000000,
        "discount": 0,
        "vatRate": 10
      }
    ],
    "payments": [
      {
        "type": 2,
        "dateTime": "20260705113000",
        "price": 16500000
      }
    ]
  }
}

فیلدهای پاسخ

پاسخ در قالب همیشگی با HTTP 200 برمی‌گردد. در موفقیت، result برابر 1 و data[0] اطلاعات استعلام نسخهٔ جاری صورتحساب است (برای اصلاحی، issue: 2 و شماره مالیاتی تازه). در خطا، result برابر 0 (احراز هویت -1، تکراری -2) و کد خطا در errors[].code است. شیء edit فقط در پاسخ این دو سرویس می‌آید:

فیلدتوضیح
edit.outcomedraftUpdated، paymentUpdated، correctionIssued، unchanged یا confirmationRequired (جدول بالا).
edit.previousTaxIdشماره مالیاتی صورتحسابی که ویرایش شد.
edit.taxIdشماره مالیاتی نسخهٔ ثبت‌شده؛ برای اصلاحی، شمارهٔ تازه.
edit.referenceTaxIdمرجع صورتحساب اصلاحی (irtaxid)؛ در correctionIssued و confirmationRequired.
edit.confirmedByدر correctionIssued: confirmCorrection یا confirmationToken؛ همین در «لاگ‌های برنامه» پنل هم ثبت می‌شود.
edit.reasonدر confirmationRequired: FIELDS_CHANGED (تغییر غیر از پرداخت)، SETTLEMENT_CHANGED (روش تسویه) یا CHANGES_BESIDES_PAYMENT (پرداخت به‌همراه تغییرهای دیگر).
edit.confirmationToken، edit.expiresAtتوکن تأیید و پایان اعتبار آن (Unix time میلی‌ثانیه)؛ فقط در confirmationRequired.
سرویس‌های قبلی تغییری نکرده‌اند: /send با ins=2 و مدل ساده با invoiceSubject=2 مانند گذشته بدون مرحلهٔ تأیید صورتحساب اصلاحی صادر می‌کنند، چون در آن‌ها خودتان صریحاً «اصلاحی» خواسته‌اید؛ اگر مرجع آن‌ها هنوز ارسال نشده باشد، همان پیش‌نویس ویرایش می‌شود و اصلاحی صادر نمی‌شود. برای ویرایش با رفتار کامل پنل، از editInvoice و simple/editInvoice استفاده کنید.
16ثبت و پیگیری صورتحساب

وضعیت تأیید اعلامیه فروش بورس (الگوی ۱۱)

طبق دستورالعمل RC_IITP.IS_V7.9، برای صورتحساب نوع ۱ با الگوی بورس اوراق بهادار مبتنی بر کالا (inp=11)، صدور اصلاحی (ins=2) فقط تا زمانی مجاز است که اعلامیه فروش بورس تأیید نشده باشد؛ پس از تأیید فقط ابطال (ins=3) مجاز است. سامانه مؤدیان راهی برای استعلام این تأیید ندارد، بنابراین وضعیت هر زنجیره صورتحساب به‌صورت دستی (از پنل یا همین سرویس‌ها) ثبت می‌شود و همه تصمیم‌های اصلاحی آن زنجیره در پنل و API از همین وضعیت پیروی می‌کنند.

مسیرscopeبدنهکاربرد
POST /api/invoice/inquiryExchangeAnnouncementv2.invoice.readinternalId یا taxIdاستعلام وضعیت فعلی زنجیره.
POST /api/invoice/exchangeAnnouncementv2.invoice.sendinternalId یا taxId، confirmed، note، expectedVersionثبت دستی «تأیید شده» یا «تأیید نشده».
وضعیت متعلق به زنجیره است

هر internalId یا taxId از زنجیره (اصلی یا اصلاحی) را می‌توانید بفرستید؛ وضعیت یک بار برای کل زنجیره ذخیره می‌شود و کلید آن originTaxId (شماره مالیاتی صورتحساب اصلی زنجیره) است. صورتحساب فقط در محدوده شرکت احراز هویت‌شده جست‌وجو می‌شود.

پیش‌شرط

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

تکرار بی‌اثر است

ارسال دوباره همان وضعیت (و همان note یا بدون note) چیزی ثبت نمی‌کند و پاسخ موفق با وضعیت فعلی برمی‌گرداند؛ بنابراین تلاش مجدد پس از قطع ارتباط امن است.

کنترل تغییر هم‌زمان

expectedVersion اختیاری است. اگر مقدار version آخرین استعلام را بفرستید و وضعیت در این فاصله تغییر کرده باشد، خطای EXCHANGE_ANNOUNCEMENT_VERSION_CONFLICT برمی‌گردد.

فیلدهای درخواست

فیلدقاعدهتوضیح
tokenاختیاریتوکن تکمیلی نمایندگی، مانند سایر سرویس‌ها.
internalIdدقیقاً یکی از internalId یا taxIdکد داخلی صورتحساب.
taxIdدقیقاً یکی از internalId یا taxIdشماره منحصر به فرد مالیاتی صورتحساب.
confirmedفقط در exchangeAnnouncement، الزامی، true یا falsetrue یعنی اعلامیه فروش بورس تأیید شده و false یعنی تأیید نشده است.
noteاختیاری، حداکثر ۵۰۰ کاراکترتوضیح تغییر؛ در تاریخچه ثبت می‌شود.
expectedVersionاختیاریهمان version پاسخ استعلام.

مقادیر وضعیت

statusمعنااثر بر اصلاحی
notRecordedهنوز وضعیتی ثبت نشده است.اصلاحی مانند گذشته مجاز است.
notConfirmedاعلامیه فروش بورس تأیید نشده است.اصلاحی مجاز است.
confirmedاعلامیه فروش بورس تأیید شده است.فقط ابطال؛ اصلاحی با EXCHANGE_ANNOUNCEMENT_CONFIRMED رد می‌شود.

منبع و کانال ثبت

فیلدمقدارمعنا
sourcemanualثبت دستی (پنل، API نسخه ۲ یا اسکریپت پشتیبانی).
sourceorgApiدریافت‌شده از API آتی سازمان. تغییر دستی آن فقط برای مدیر سامانه و با توضیح مجاز است؛ در API نسخه ۲ خطای EXCHANGE_ANNOUNCEMENT_FORBIDDEN برمی‌گردد.
channelpanel، apiV2، orgApi، scriptمسیری که آخرین ثبت از آن انجام شده است. ثبت از این سرویس همیشه apiV2 است و setBy شناسه client یا legacy-company:{companyId} را نشان می‌دهد.

فیلدهای پاسخ

پاسخ در قالب همیشگی (result، traceId، message، errors، data) با HTTP 200 برمی‌گردد و وضعیت در فیلد exchangeAnnouncement قرار دارد. در خطا، result برابر 0 (و در خطای احراز هویت -1) است و کد خطا در errors[].code می‌آید؛ فهرست کدها در جدول خطاها.

فیلدتوضیح
invoiceIdشناسه صورتحساب درخواستی.
originTaxId، rootInvoiceIdشماره مالیاتی و شناسه صورتحساب اصلی زنجیره (کلید وضعیت).
statusnotRecorded، notConfirmed یا confirmed.
source، channelمنبع و کانال آخرین ثبت؛ پیش از اولین ثبت وجود ندارند.
setBy، setByUserId، setAtUtc، setAtثبت‌کننده و زمان آخرین ثبت (setAt به تاریخ شمسی و وقت تهران).
saleAnnNo، saleAnnDateشماره و تاریخ شمسی اعلامیه فروش بورس زنجیره.
noteتوضیح آخرین ثبت.
versionنسخه ردیف وضعیت؛ برای expectedVersion.
canChangeآیا این توکن می‌تواند وضعیت را تغییر دهد (نیازمند v2.invoice.send و منبع غیر orgApi).
pendingCorrectionDraftsاصلاحی‌های باز زنجیره (invoiceId، no، hash): پیش‌نویس‌های ارسال‌نشده، و اصلاحی‌هایی که برای ارسال ثبت شده‌اند ولی هنوز نتیجه‌ای از سامانه مؤدیان ندارند با inFlight: true. برای پیش‌نویس ارسال‌نشده فیلد inFlight وجود ندارد.
ثبت «تأیید شده» حتی وقتی پیش‌نویس اصلاحی ارسال‌نشده دارید مجاز است و آن پیش‌نویس‌ها در pendingCorrectionDrafts فهرست می‌شوند. تا وقتی وضعیت «تأیید شده» است، این پیش‌نویس‌ها نه ذخیره می‌شوند و نه ارسال؛ برای مثال /api/invoice/sendInvoice برای آن‌ها خطای EXCHANGE_ANNOUNCEMENT_CONFIRMED در مسیر $.internalIds[i] برمی‌گرداند. اصلاحی‌ای که پیش از ثبت «تأیید شده» برای ارسال ثبت شده ولی هنوز نتیجه‌ای ندارد با inFlight: true در همین فهرست می‌آید؛ تا وقتی وضعیت «تأیید شده» است، سامانه آن را دوباره در صف ارسال قرار نمی‌دهد.
پیش‌نویس اصلاحی پس از «تأیید شده»: اصلاحی ثبت‌شده، حتی اگر ارسال نشده باشد، بلافاصله آخرین صورتحساب زنجیره می‌شود و sendInvoice و cancelInvoice همیشه روی آخرین صورتحساب زنجیره عمل می‌کنند. بنابراین:
  • sendInvoice با internalId صورتحساب اصلی یا هر عضو قبلی زنجیره، همان پیش‌نویس اصلاحی را ارسال می‌کند و در وضعیت «تأیید شده» با EXCHANGE_ANNOUNCEMENT_CONFIRMED در مسیر $.internalIds[i] رد می‌شود. چون با هر خطا پاسخ result: 0 بدون data برمی‌گردد، سایر شناسه‌های همان درخواست را که ممکن است در صف ارسال قرار گرفته باشند با سرویس‌های پیگیری بررسی کنید.
  • cancelInvoice فقط آخرین صورتحساب زنجیره را، در صورتی که ارسال‌شده و دارای شماره مالیاتی باشد، باطل می‌کند؛ تا وقتی پیش‌نویس اصلاحی ارسال‌نشده آخرین صورتحساب زنجیره است، ابطال با خطا در مسیر $.internalId رد می‌شود.
  • API نسخه ۲ امکان حذف پیش‌نویس ارسال‌نشده را ندارد. برای ابطال زنجیره، ابتدا پیش‌نویس را در پنل حذف کنید تا صورتحساب قبلی دوباره آخرین صورتحساب زنجیره شود، سپس cancelInvoice را فراخوانی کنید.
  • اگر «تأیید شده» به اشتباه ثبت شده است، ثبت confirmed: false اصلاحی‌ها و پیش‌نویس‌های همان زنجیره را دوباره قابل ثبت و ارسال می‌کند. این تغییر برای وضعیت دریافت‌شده از سامانه سازمان (source: orgApi) با EXCHANGE_ANNOUNCEMENT_FORBIDDEN رد می‌شود.
اگر وضعیت موقتاً قابل خواندن نباشد، فقط اصلاحی‌های زنجیره الگوی ۱۱ با کد EXCHANGE_ANNOUNCEMENT_STATUS_UNAVAILABLE متوقف می‌شوند؛ صورتحساب اصلی، ابطال، برگشت از فروش و صورتحساب‌های سایر الگوها تحت تأثیر نیستند.
در پاسخ سرویس‌های پیگیری (inquiryInternalId، inquiryNo، inquiryTaxId و نسخه‌های آرایه‌ای)، پاسخ ثبت و پاسخ sendInvoice و cancelInvoice، برای صورتحساب الگوی ۱۱ فیلد اختیاری exchangeAnnouncement با ساختار کوتاه { status, source?, setBy?, setAt?, setAtUtc? } اضافه می‌شود. برای سایر الگوها، یا اگر وضعیت قابل خواندن نباشد، این فیلد در پاسخ وجود ندارد.
inquiryExchangeAnnouncement body
{
  "taxId": "A1B2C304E7900000F42410"
}
exchangeAnnouncement body
{
  "internalId": "IME-1001",
  "confirmed": true,
  "note": "اعلامیه در سامانه بورس کالا تأیید شد.",
  "expectedVersion": "AAAAAAAAB9A="
}
exchangeAnnouncement response
{
  "result": 1,
  "traceId": "0c5d2a4e-6f1b-4c3e-9a57-2b8f4d1e7a90",
  "message": "وضعیت اعلامیه فروش بورس ثبت شد.",
  "data": [],
  "exchangeAnnouncement": {
    "invoiceId": 105234,
    "originTaxId": "A1B2C304E7900000F42410",
    "rootInvoiceId": 105234,
    "status": "confirmed",
    "source": "manual",
    "channel": "apiV2",
    "setBy": "API v2 (customer:81001)",
    "setAtUtc": "2026-09-15T06:30:00Z",
    "setAt": "1405/06/24 ساعت 10:00",
    "saleAnnNo": "1405012345",
    "saleAnnDate": "1405/06/10",
    "note": "اعلامیه در سامانه بورس کالا تأیید شد.",
    "version": "AAAAAAAAB9E=",
    "canChange": true,
    "pendingCorrectionDrafts": [
      { "invoiceId": 105240, "no": "A000000012", "hash": "9b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e" },
      { "invoiceId": 105241, "no": "A000000013", "hash": "0a1b2c3d4e5f60718293a4b5c6d7e8f9", "inFlight": true }
    ]
  }
}
17کارپوشهٔ مالیاتی

کارپوشه مالیاتی، واکنش گروهی و فایل Excel

با این مسیرها، نرم‌افزار شما همان کارهای بخش «کارپوشه مالیاتی» پنل را انجام می‌دهد: فهرست صورتحساب‌های خرید، فروش و مجازی و قراردادهای شخص ثالث را از سامانه مؤدیان می‌خواند، صورتحساب‌های در انتظار واکنش و قراردادها را به‌صورت گروهی تأیید یا رد می‌کند و همین کارها را با فایل Excel هم انجام می‌دهد.

این API همان منطق کارپوشه پنل را اجرا می‌کند. کسب‌وکار، کد اقتصادی و دسترسی واگذارشده فقط از توکن دسترسی تعیین می‌شوند؛ هیچ مقداری در JSON یا فایل Excel کسب‌وکار یا مؤدی دیگری را انتخاب نمی‌کند.

احراز هویت و Internal Permission: همه مسیرها از client_credentials نوع Customer استفاده می‌کنند. عملیات صرفاً خواندنی، یعنی خواندن فهرست‌ها با JSON، Export، Template و Result، به scope v2.invoice.read نیاز دارند. Preview هیچ PUT سازمانی اجرا نمی‌کند، اما چون Actionability و Permission هر ردیف را با همان Preflight عملیات بررسی می‌کند، مانند Bulk/Execute به scope v2.invoice.send نیاز دارد. نبود scope با HTTP 403 برگردانده می‌شود. API Key قدیمی فقط تا مهلت مهاجرت اعلام‌شده و با همان هدرهای Deprecation قبلی پشتیبانی می‌شود.
مجوزهای قرارداد: دیدن قراردادها به مجوز contract.brokerage:view در دسترسی واگذارشده نیاز دارد. تأیید یا رد قرارداد علاوه بر scope v2.invoice.send، مجوز contract.brokerage:manage را لازم دارد و باید از سوی معتمد آسا فعال شده باشد (تنظیم سرور TaxWorkspace.ContractReactionsEnabled). نبود این مجوز فقط همین عملیات را متوقف می‌کند و دسترسی‌های دیگر کار می‌کنند.
فعال بودن سرویس: سرویس‌های کارپوشه برای همه کسب‌وکارها یک‌جا فعال می‌شوند. پاسخ 503 با کد tax_workspace_disabled یعنی این سرویس در این محیط فعال نیست و 503 با کد service_not_configured یعنی تنظیمات امن سرور کامل نیست؛ در هر دو حالت با پشتیبانی معتمد آسا تماس بگیرید. هر کسب‌وکار هم باید دسترسی واگذارشده کارپوشه را گرفته باشد؛ تا مدیر کسب‌وکار آن را از تنظیمات کسب‌وکار در پنل یا با مسیرهای شناسه یکتای حافظه مالیاتی با API نگرفته باشد، پاسخ 409 با کد tax_workspace_reauthorization_required است.
محیط آزمایشی ندارد: محیط مسیرهای کارپوشه تنظیم سرور است و این مسیرها فیلد sandBox ندارند؛ در https://api-v2.asatsp.ir، تأیید و رد گروهی و اجرای Excel روی کارپوشه واقعی کسب‌وکار انجام می‌شود. ابتدا فقط فهرست‌ها و پیش‌نمایش Excel را آزمایش کنید و تأیید یا رد را آگاهانه و با یک صورتحساب واقعی انجام دهید.

Endpointها

MethodEndpointScopeکاربرد
GET/api/v2/tax-workspace/invoices/{kind}v2.invoice.readخواندن یک صفحه (حداکثر ۱۰ ردیف) از فهرست صورتحساب‌های کارپوشه با JSON.
GET/api/v2/tax-workspace/invoices/{kind}/virtual-as-broker-clientv2.invoice.readصورتحساب‌های مجازی یک روز که کسب‌وکار شما آمر آن‌هاست؛ فقط برای sales و purchase.
GET/api/v2/tax-workspace/brokerage-contractsv2.invoice.readخواندن یک صفحه (حداکثر ۱۰ ردیف) از قراردادهای شخص ثالث با JSON.
PUT/api/v2/tax-workspace/invoices/bulkv2.invoice.sendتأیید یا رد گروهی صورتحساب‌های خرید و صورتحساب‌های مجازی فروشی که کسب‌وکار شما آمر آن‌هاست، با JSON.
PUT/api/v2/tax-workspace/brokerage-contracts/bulkv2.invoice.sendApprove/Reject گروهی قرارداد شخص ثالث؛ هر قرارداد با Request مستقل سازمان اجرا می‌شود.
GET/api/v2/tax-workspace/invoices/{kind}/excel/exportv2.invoice.readفایل Excel همه ردیف‌های یک روز (همه صفحه‌ها، حداکثر ۵۰۰ ردیف) با همان فیلترهای فهرست JSON.
GET/api/v2/tax-workspace/invoices/{kind}/excel/templatev2.invoice.readنمونه امن .xlsx برای بخش‌های دارای واکنش.
POST/api/v2/tax-workspace/invoices/{kind}/excel/previewv2.invoice.sendآپلود multipart، Parse و Preflight خواندنی Actionability/Permission؛ هیچ PUT سازمانی اجرا نمی‌شود.
POST/api/v2/tax-workspace/invoices/{kind}/excel/executev2.invoice.sendاجرای Preview تأییدشده با previewToken کوتاه‌عمر.
GET/api/v2/tax-workspace/brokerage-contracts/excel/exportv2.invoice.readخروجی Filterشده قراردادها.
GET/api/v2/tax-workspace/brokerage-contracts/excel/templatev2.invoice.readنمونه عملیات قرارداد.
POST/api/v2/tax-workspace/brokerage-contracts/excel/previewv2.invoice.sendاعتبارسنجی و Preflight قرارداد بدون اجرای PUT.
POST/api/v2/tax-workspace/brokerage-contracts/excel/executev2.invoice.sendاجرای عملیات قرارداد پس از Confirmation.
POST/api/v2/tax-workspace/excel/resultv2.invoice.readدریافت فایل نتیجه با resultToken متعلق به همان Company/API Client.

Kind و Filter خروجی صورتحساب

مقادیر مجاز {kind} عبارت‌اند از purchase، sales، virtual-purchase و virtual-sales. برای تأیید یا رد، از فهرست purchase یا sales استفاده کنید و فقط ردیف‌هایی را بفرستید که actionAllowed آن‌ها true است. در فهرست purchase این ردیف‌ها صورتحساب‌های خرید در انتظار واکنش‌اند و در فهرست sales صورتحساب مجازی فروشی که حق‌العمل‌کار ثبت کرده و کسب‌وکار شما آمر آن است. فهرست‌های virtual-purchase و virtual-sales برای دیدن وضعیت‌اند؛ این دو مقدار در درخواست واکنش فقط برای سازگاری با نسخه‌های قبلی پذیرفته می‌شوند. واکنش به صورتحساب مجازی با آمر است؛ ردیفی که شما در آن حق‌العمل‌کار هستید با کد invoice_virtual_broker_side و ردیف فروشی که مجازی نیست با کد invoice_not_virtual_sale و وضعیت NOT_ACTIONABLE برمی‌گردد.

فیلترهای خروجی Excel صورتحساب همان پارامترهای جدول «خواندن فهرست‌ها با JSON» در ادامه است: period و بازه یک‌روزه issuanceDateFrom و issuanceDateTo الزامی‌اند و pageNumber و pageSize به کار نمی‌روند. خروجی همه صفحه‌های همان روز را در بر می‌گیرد و پارامتری برای مرتب‌سازی ندارد؛ اگر بیش از ۵۰۰ ردیف باشد، پاسخ 409 با کد tax_workspace_excel_export_row_limit_exceeded است.

در پاسخ virtual-purchase و virtual-sales، فیلد brokerClientName نام آمر را دارد (حداکثر ۴۰۰ نویسه، همان‌طور که سازمان برمی‌گرداند). در فهرست خرید و فروش عادی این فیلد null است.

Export قرارداد نیز Filterهای contractBrokerageId، contractBrokerageNumber، contractBrokerageInternalNumber، status، کدهای اقتصادی طرفین و بازه‌های issue/create date را می‌پذیرد. سرور صفحات حداکثر ۱۰تایی سازمان را کنترل‌شده واکشی می‌کند و از سقف TaxWorkspace.ExcelExportMaxRows عبور نمی‌کند.

خواندن فهرست‌ها با JSON

سامانه فروش یا حسابداری متصل می‌تواند فهرست صورتحساب‌ها و قراردادهای کارپوشه را بدون دریافت فایل Excel و صفحه‌به‌صفحه با JSON بخواند، سپس برای ردیف‌های قابل واکنش، تأیید یا رد را با PUT /api/v2/tax-workspace/invoices/bulk یا PUT /api/v2/tax-workspace/brokerage-contracts/bulk بفرستد. هر درخواست دقیقاً یک صفحه را از سامانه مؤدیان می‌خواند، همان اعتبارسنجی و دسترسی واگذارشده پنل را طی می‌کند و در گزارش عملیات کارپوشه همان کسب‌وکار ثبت می‌شود. این مسیرها فقط خواندنی‌اند و چیزی را در کارپوشه تغییر نمی‌دهند.

پارامتر صورتحسابالزامیتوضیح
{kind}بلهدر مسیر: purchase، sales، virtual-purchase یا virtual-sales. مقدار دیگر با HTTP 404 و کد unsupported_invoice_kind رد می‌شود.
periodبلهسال و فصل مالیاتی با قالب YYYYPP؛ مثلاً 140503 برای فصل سوم ۱۴۰۵. فصل فقط 01 تا 04 است. حداقل 140404 (زمستان ۱۴۰۴) و حداکثر دوره‌ی جاری تقویم تهران است (سند رسمی سرویس‌های شرکت معتمد)؛ مقدار بیرون از این بازه با HTTP 400 و پیام روشن رد می‌شود.
issuanceDateFrom / issuanceDateToبلهابتدا و انتهای بازه تاریخ صدور با epoch milliseconds سیزده‌رقمی. هر دو باید در یک روز تقویم تهران و در همان سال و فصل period باشند و ابتدای بازه بعد از انتهای آن نباشد. برای چند روز، هر روز را جداگانه بخوانید.
pageNumberخیرشماره صفحه از 1؛ پیش‌فرض 1.
pageSizeخیرتعداد ردیف هر صفحه از 1 تا حداکثر 10؛ پیش‌فرض 10.
statusخیریکی از AWAITING_REACTION، APPROVED، REJECTED، SYSTEMIC_APPROVED، SYSTEMIC_REJECTED، NO_NEED_REACTION، IMPOSSIBLE_REACTION یا CANCELED.
patternخیریکی از SALE، CURRENCY_SALE، GOLD، CONTRACT، BILL، PLANE_TICKET، EXPORT، LADING، REFINEMENT_AND_DISTRIBUTION، MERCANTILE_EXCHANGE_SALE، INSURANCE_SERVICES، CHAIN، MERCANTILE_EXCHANGE_BUY یا IMPORT.
contractBrokerageNumberخیرشماره قرارداد شخص ثالث؛ دقیقاً ۱۲ رقم.
sellerRoleخیرفقط در sales: NORMAL، BROKER_CLIENT (آمر) یا BROKER (حق‌العمل‌کار).
buyerRoleخیرفقط در purchase: NORMAL، BROKER_CLIENT (آمر) یا BROKER (حق‌العمل‌کار). اگر سامانه مؤدیان این فیلتر را نپذیرد، جست‌وجو بدون آن انجام و ردیف‌ها در سرور بر اساس نقش خریدار پالایش می‌شوند؛ در این حالت notices همین را می‌گوید و یک صفحه ممکن است پیش از صفحه‌ی آخر کمتر از pageSize ردیف داشته باشد، پس تا رسیدن به صفحه‌ی خالی ادامه دهید.

پاسخ تعداد کل ردیف‌ها را برنمی‌گرداند. صفحه‌ها را از pageNumber=1 به ترتیب بخوانید؛ وقتی تعداد ردیف‌های data کمتر از pageSize بود، صفحه آخر را خوانده‌اید (اگر صفحه آخر دقیقاً pageSize ردیف داشته باشد، صفحه بعد فهرست خالی برمی‌گرداند). در فهرست‌های purchase و sales، فیلد actionAllowed نشان می‌دهد این کسب‌وکار می‌تواند آن ردیف را تأیید یا رد کند؛ taxId همین ردیف‌ها را به PUT /api/v2/tax-workspace/invoices/bulk بفرستید. فهرست‌های مجازی فقط برای دیدن وضعیت‌اند و در آن‌ها این فیلد null است. سرور پیش از هر واکنش، وضعیت ردیف را دوباره بررسی می‌کند. اگر سامانه مؤدیان بازه را محدود کرده باشد (مثلاً در روز اول فصل)، توضیح فارسی آن در آرایه اختیاری notices می‌آید. خطای پارامترها با HTTP 400 و کد validation_failed و پیامی که همه ایرادها را نام می‌برد برمی‌گردد.

برای دیدن یک‌جای صورتحساب‌های مجازی یک روز که کسب‌وکار شما در آن‌ها آمر است (مانند بخش «شما آمر هستید» در پنل)، GET /api/v2/tax-workspace/invoices/sales/virtual-as-broker-client یا GET /api/v2/tax-workspace/invoices/purchase/virtual-as-broker-client را با همان period و بازه یک‌روزه بخوانید. سرور حداکثر ۱۰ صفحه ۱۰تایی (۱۰۰ صورتحساب) از فهرست فروش یا خرید همان روز را می‌خواند و فقط ردیف‌هایی را برمی‌گرداند که شما آمر آن‌ها هستید؛ بنابراین pageNumber و pageSize در این مسیر به کار نمی‌روند و اگر به این سقف برسد، notices آن را اعلام می‌کند. در این مسیر {kind} فقط sales یا purchase است.

Read one page of purchase invoices
curl -G "https://api-v2.asatsp.ir/api/v2/tax-workspace/invoices/purchase" \
  -H "Authorization: Bearer <AccessToken with v2.invoice.read>" \
  -H "X-Correlation-ID: 00000000-0000-0000-0000-000000000001" \
  --data-urlencode "period=140503" \
  --data-urlencode "issuanceDateFrom=1792182600000" \
  --data-urlencode "issuanceDateTo=1792268999999" \
  --data-urlencode "status=AWAITING_REACTION" \
  --data-urlencode "pageNumber=1" \
  --data-urlencode "pageSize=10"

در این نمونه، بازه از ۰۰:۰۰ تا ۲۳:۵۹:۵۹٫۹۹۹ روز ۱۴۰۵/۰۷/۲۵ به وقت تهران است که در فصل 140503 قرار دارد. همه داده‌های نمونه ساختگی‌اند.

Invoice list response
{
  "status": "OK",
  "data": [
    {
      "taxId": "A111111111111111111111",
      "parentTaxId": null,
      "type": "FIRST",
      "pattern": "SALE",
      "subject": "ORIGINAL",
      "status": "AWAITING_REACTION",
      "referenceTaxId": null,
      "totalAmount": "1100000",
      "totalVatAmount": "100000",
      "issuanceDate": 1792219500000,
      "article6Status": null,
      "buyerCallStatus": null,
      "sellerCallStatus": null,
      "isVirtualInvoice": false,
      "sellerName": "فروشنده نمونه",
      "buyerName": "خریدار نمونه",
      "buyerEconomicNumber": "10000000001",
      "buyerRole": "NORMAL",
      "sellerRole": "NORMAL",
      "sellerEconomicNumber": "10000000002",
      "period": "140503",
      "createDate": 1792219800000,
      "contractBrokerageNumber": null,
      "brokerClientName": null,
      "actionAllowed": true
    }
  ],
  "errors": [],
  "fieldErrors": [],
  "correlationId": "00000000-0000-0000-0000-000000000001"
}
پارامتر قراردادتوضیح
pageNumber / pageSizeمانند فهرست صورتحساب؛ pageSize از 1 تا حداکثر 10 و پیش‌فرض آن 10 است. بدون هیچ پارامتری، صفحه اول خوانده می‌شود.
contractBrokerageIdشناسه قرارداد؛ حداکثر ۱۶ رقم.
contractBrokerageNumberشماره قرارداد؛ دقیقاً ۱۲ رقم.
contractBrokerageInternalNumberشماره داخلی قرارداد؛ حداکثر ۱۹ نویسه.
brokerClientEconomicNumber / brokerEconomicNumberکد اقتصادی آمر یا حق‌العمل‌کار؛ ۱۱ یا ۱۴ رقم.
statusقابل تکرار؛ AWAITING_REACTION، FINAL_REGISTRATION، CANCELLED یا REJECTED. مثلاً status=AWAITING_REACTION&status=FINAL_REGISTRATION.
issueDateFrom / issueDateToبازه تاریخ عقد با epoch milliseconds سیزده‌رقمی.
createDateFrom / createDateToبازه تاریخ ثبت با epoch milliseconds سیزده‌رقمی.

در فهرست قراردادها، actionAllowed مشخص می‌کند قرارداد در انتظار واکنش همین کسب‌وکار است؛ شماره این قراردادها را در contractBrokerageNumbers به PUT /api/v2/tax-workspace/brokerage-contracts/bulk بفرستید.

Read contracts awaiting reaction
curl -G "https://api-v2.asatsp.ir/api/v2/tax-workspace/brokerage-contracts" \
  -H "Authorization: Bearer <AccessToken with v2.invoice.read>" \
  --data-urlencode "status=AWAITING_REACTION" \
  --data-urlencode "pageNumber=1" \
  --data-urlencode "pageSize=10"
Contract list response
{
  "status": "OK",
  "data": [
    {
      "contractBrokerageId": "1000000000000001",
      "issueDate": 1790109000000,
      "startDate": 1792701000000,
      "createDate": 1790229600000,
      "updateDate": 1790229600000,
      "status": "AWAITING_REACTION",
      "subject": "MAIN",
      "type": "BROKERAGE_SELL_CONTRACT",
      "contractBrokerageRegistrar": "BROKER",
      "brokerClientEconomicNumber": "10000000001",
      "brokerClientName": "آمر نمونه",
      "brokerEconomicNumber": "10000000002",
      "brokerName": "حق‌العمل‌کار نمونه",
      "amount": "500000000",
      "contractBrokerageInternalNumber": "INT-0001",
      "contractBrokerageNumber": "000000000001",
      "parentContractBrokerageId": null,
      "title": "قرارداد نمونه",
      "brokerBranchCode": null,
      "brokerClientBranchCode": null,
      "actionAllowed": true
    }
  ],
  "errors": [],
  "fieldErrors": [],
  "correlationId": "00000000-0000-0000-0000-000000000001"
}

واکنش گروهی به صورتحساب‌ها با JSON

در حالت ساده فقط kind، آرایه taxIds و action ارسال می‌شود. Backend روز صدور و دوره مالیاتی را از بخش روز رسمی TaxId استخراج می‌کند، حداکثر دو تاریخ محتمل تهران را در فهرست واگذارشده همان کارپوشه استعلام می‌گیرد و فقط TaxId دقیق با وضعیت AWAITING_REACTION را قبل از PUT می‌پذیرد. بنابراین Client برای تأیید نیازی به ارسال period یا تاریخ ندارد و TaxId نیز نمی‌تواند کارپوشه دیگری را انتخاب کند.

Minimal invoice approve
{
  "kind": "purchase",
  "taxIds": ["<TaxId1>", "<TaxId2>"],
  "action": "APPROVE"
}
Minimal invoice reject
{
  "kind": "purchase",
  "taxIds": ["<TaxId1>", "<TaxId2>"],
  "action": "REJECT",
  "rejectReasons": ["PRODUCT", "AMOUNT"],
  "rejectDescription": "مغایرت اطلاعات ردیف‌ها"
}

Action فقط APPROVE یا REJECT است. دلیل‌های مجاز: NOT_INFORMED، BUYER، SELLER، PRODUCT، AMOUNT، PAYMENT و OTHER. برای OTHER توضیح الزامی است. برای Actionهای متفاوت در یک درخواست، شکل تفصیلی سازگار با نسخه قبل یعنی operations[] همچنان پشتیبانی می‌شود؛ در این شکل period و issuanceDate اختیاری‌اند و در صورت حذف از TaxId استخراج می‌شوند. ارسال هم‌زمان taxIds و operations با invalid_bulk_shape رد می‌شود.

Mixed invoice bulk request
{
  "kind": "purchase",
  "operations": [
    {
      "taxId": "A111111111111111111111",
      "period": "140501",
      "issuanceDate": 1780000000000,
      "action": "APPROVE",
      "rejectReasons": [],
      "rejectDescription": null
    },
    {
      "taxId": "A222222222222222222222",
      "period": "140501",
      "issuanceDate": 1780000000000,
      "action": "REJECT",
      "rejectReasons": ["PRODUCT", "AMOUNT"],
      "rejectDescription": "مغایرت ردیف نمونه"
    }
  ]
}
Bulk response schema
{
  "status": "OK",
  "data": {
    "total": 2,
    "success": 1,
    "failed": 1,
    "skipped": 0,
    "batchCorrelationId": "00000000-0000-0000-0000-000000000002",
    "results": [
      {
        "identifier": "A111111111111111111111",
        "period": "140501",
        "issuanceDate": 1780000000000,
        "action": "APPROVE",
        "status": "SUCCESS",
        "code": null,
        "message": "عملیات انجام شد.",
        "correlationId": "00000000-0000-0000-0000-000000000001"
      },
      {
        "identifier": "A222222222222222222222",
        "period": "140501",
        "issuanceDate": 1780000000000,
        "action": "REJECT",
        "status": "NOT_ACTIONABLE",
        "code": "invoice_not_awaiting_reaction",
        "message": "صورتحساب دیگر در وضعیت در انتظار واکنش نیست.",
        "correlationId": "00000000-0000-0000-0000-000000000001"
      }
    ]
  },
  "errors": [],
  "fieldErrors": [],
  "correlationId": "00000000-0000-0000-0000-000000000001"
}

وضعیت هر ردیف در results[].status:

statusمعنا
SUCCESSسامانه مؤدیان واکنش را پذیرفت.
SKIPPEDردیف عملیاتی نداشت (no_action).
VALIDATION_ERRORورودی ردیف نامعتبر است و چیزی ارسال نشد.
NOT_ACTIONABLEردیف در این کارپوشه پیدا نشد یا در انتظار واکنش این کسب‌وکار نیست و چیزی ارسال نشد.
PERMISSION_DENIEDمجوز لازم در دسترسی واگذارشده نیست.
FAILEDسامانه مؤدیان یا بررسی پیش از ارسال آن را رد کرد.
AMBIGUOUSپاسخ سامانه مؤدیان نرسید و نتیجه قطعی نیست؛ پیش از هر تکرار، فهرست همان روز را بخوانید.

شمارنده failed همه ردیف‌هایی را می‌شمارد که SUCCESS یا SKIPPED نیستند.

واکنش گروهی به قراردادها با JSON

Contract numbers with one action
{
  "contractBrokerageNumbers": ["000000000001", "000000000002"],
  "action": "APPROVE"
}
All actionable contracts in current workspace
{
  "allForCurrentEconomicNumber": true,
  "economicNumber": "<CurrentWorkspaceEconomicNumber>",
  "action": "APPROVE"
}

برای انتخاب همه، فقط قراردادهای AWAITING_REACTION و قابل اقدام در کارپوشه احرازشده فعلی انتخاب می‌شوند. economicNumber اختیاری و صرفاً تأیید تطابق است؛ Backend هرگز از آن برای انتخاب Tenant یا Delegation استفاده نمی‌کند و مقدار متفاوت را با economic_number_context_mismatch رد می‌کند. شکل قبلی operations[] با contractBrokerageId یا contractBrokerageNumber همچنان برای Actionهای ترکیبی معتبر است، ولی سه روش انتخاب را نمی‌توان هم‌زمان فرستاد. endpoint رسمی قرارداد یک شناسه می‌پذیرد؛ بنابراین API هر Contract را با Request مستقل و concurrency محدود اجرا می‌کند و batch ساختگی برای سازمان نمی‌سازد. تعداد Operationهای واقعاً قابل اجرا در هر درخواست JSON یا فایل Excel با TaxWorkspace.ContractBulkMaxActions محدود می‌شود؛ مقدار پیش‌فرض امن 20 و بازه قابل تنظیم 1..100 است. ردیف‌های بدون Action یا نامعتبر در این سقف اجرایی شمرده نمی‌شوند.

بسته‌های ۱۰تایی و نتیجه جزئی

تعداد Operationهای واقعاً قابل اجرای صورتحساب در یک درخواست JSON یا فایل Excel با TaxWorkspace.InvoiceBulkMaxActions محدود می‌شود؛ مقدار پیش‌فرض 20 و بازه قابل تنظیم 1..100 است. این سقف با chunk حداکثر ۱۰تایی هر Request سازمان تفاوت دارد.

  • Approve صورتحساب‌ها در chunkهای حداکثر ۱۰تایی ارسال می‌شود.
  • Rejectها ابتدا بر اساس ترکیب دقیق Reasons و Description گروه‌بندی و سپس حداکثر ۱۰تایی می‌شوند.
  • Atomicity در سطح هر Request سازمان حفظ می‌شود؛ Fail شدن یک chunk همه اعضای همان chunk را Fail گزارش می‌کند.
  • فایل بزرگ می‌تواند Partial Success داشته باشد؛ نتیجه هر ردیف در response و فایل نتیجه مشخص است.
  • برای PUT هیچ Retry کور انجام نمی‌شود. نتیجه مبهم با GET Recheck فعلی بررسی و در صورت عدم قطعیت با AMBIGUOUS گزارش می‌شود.

پس از نتیجه AMBIGUOUS، کارپوشه تا روشن شدن نتیجه، واکنش تازه نمی‌پذیرد و ردیف‌های درخواست بعدی با AMBIGUOUS و کد tax_workspace_mutation_in_progress یا tax_workspace_mutation_recheck_required برمی‌گردند. فهرست همان روز را با GET /api/v2/tax-workspace/invoices/{kind} (یا فهرست قراردادها) بخوانید: ردیفی که دیگر AWAITING_REACTION نیست، انجام شده است؛ فقط ردیف‌های باقی‌مانده را دوباره بفرستید.

این مسیرها نتیجه را در همان درخواست برمی‌گردانند و ممکن است چند دقیقه طول بکشند، چون برای هر ردیف چند بار با سامانه مؤدیان تماس گرفته می‌شود. سرور برای این مسیرها تا دو ساعت منتظر می‌ماند (executionTimeout=7200)؛ مهلت انتظار نرم‌افزار خود را متناسب با تعداد ردیف‌ها تنظیم کنید. اگر پاسخ نرسید، واکنش را دوباره نفرستید؛ ابتدا فهرست همان روز را بخوانید.

واکنش با فایل Excel: دریافت فایل، پیش‌نمایش، اجرا و فایل نتیجه

  1. فایل واقعی Filterشده یا Template را دانلود کنید.
  2. نمونه صورتحساب فقط چهار ستون فارسی «شناسه یکتای مالیاتی»، «عملیات»، «دلایل رد» و «توضیحات رد» دارد. نمونه قرارداد فقط «شماره قرارداد» و «عملیات» دارد. چند دلیل فارسی با ; جدا می‌شوند؛ مانند «کالا یا خدمت;مبلغ صورتحساب».
  3. برای واکنش به همه قراردادهای قابل اقدام همین کارپوشه، در ستون «شماره قرارداد» مقدار «همه» را بنویسید. فایل هیچ کد اقتصادی یا شناسه Tenant دریافت نمی‌کند.
  4. فایل را با multipart/form-data و نام فیلد file برای Preview ارسال کنید. Preview هیچ واکنشی اجرا نمی‌کند.
  5. Summary شامل قابل اجرا، Approve، Reject، بدون Action و خطادار را بررسی کنید.
  6. previewToken کوتاه‌عمر را با endpoint Execute ارسال کنید.
  7. پس از اجرا، فایل نتیجه را با resultToken دریافت کنید.

Workbook جدید به‌صورت راست‌به‌چپ و با Sheetهای فارسی داده‌ها، راهنما و فهرست‌ها تولید می‌شود. عنوان ستون‌ها، وضعیت‌ها، نوع‌ها، نقش‌ها، عملیات «تأیید/رد» و دلیل‌های رد با اصطلاحات فارسی مستندات نمایش داده می‌شوند و Backend آن‌ها را پیش از اجرا به کدهای فنی ثابت تبدیل می‌کند. فایل‌های قدیمی دارای Sheet Data و عنوان‌ها یا کدهای انگلیسی همچنان قابل بارگذاری‌اند. فایل نتیجه ستون‌های فارسی «نتیجه عملیات»، «زمان پردازش»، «کد پاسخ»، «پیام پاسخ» و «شناسه رهگیری» را اضافه می‌کند. هیچ Token، Secret یا Authorization Header در فایل نوشته نمی‌شود. Claim اجرای Excel با تنظیم TaxWorkspace.ExcelExecutionRetentionHours در بازه 3..168 ساعت نگه‌داری می‌شود و مقدار پیش‌فرض آن 24 ساعت است.

Excel Preview response
{
  "status": "OK",
  "data": {
    "previewToken": "<PreviewToken>",
    "batchCorrelationId": "00000000-0000-0000-0000-000000000001",
    "expiresAt": 1780000900000,
    "summary": {
      "total": 2,
      "executable": 1,
      "approve": 1,
      "reject": 0,
      "noAction": 0,
      "invalid": 1
    },
    "rows": [
      {
        "rowNumber": 2,
        "identifier": "<SampleTaxId1>",
        "period": "140501",
        "issuanceDate": 1780000000000,
        "action": "APPROVE",
        "rejectReasons": [],
        "rejectDescription": null,
        "errors": [],
        "warnings": [],
        "previewStatus": "EXECUTABLE",
        "previewCode": null,
        "previewMessage": null
      },
      {
        "rowNumber": 3,
        "identifier": "<SampleTaxId2>",
        "action": "REJECT",
        "errors": ["برای رد صورتحساب حداقل یک دلیل لازم است."],
        "warnings": [],
        "previewStatus": "VALIDATION_ERROR",
        "previewCode": "invalid_excel_row",
        "previewMessage": "برای رد صورتحساب حداقل یک دلیل لازم است."
      }
    ]
  },
  "errors": [],
  "fieldErrors": [],
  "correlationId": "00000000-0000-0000-0000-000000000001"
}

previewStatus هر ردیف یکی از این مقدارهاست: EXECUTABLE (اجرا می‌شود)، SKIPPED (بدون عملیات)، VALIDATION_ERROR (خطای ردیف؛ متن آن در errors[])، NOT_ACTIONABLE، PERMISSION_DENIED، FEATURE_DISABLED (تأیید و رد قرارداد فعال نیست)، FAILED یا AMBIGUOUS. فقط ردیف‌های EXECUTABLE با previewToken اجرا می‌شوند.

Excel Execute response
{
  "status": "OK",
  "data": {
    "batchCorrelationId": "00000000-0000-0000-0000-000000000001",
    "resultToken": "<ResultToken>",
    "summary": {
      "total": 2,
      "success": 1,
      "failed": 1,
      "skipped": 0,
      "batchCorrelationId": "00000000-0000-0000-0000-000000000001",
      "results": [
        {
          "identifier": "<SampleTaxId1>",
          "period": "140501",
          "issuanceDate": 1780000000000,
          "action": "APPROVE",
          "status": "SUCCESS",
          "code": null,
          "message": "عملیات انجام شد.",
          "correlationId": "00000000-0000-0000-0000-000000000001"
        },
        {
          "identifier": "<SampleTaxId2>",
          "action": "REJECT",
          "status": "VALIDATION_ERROR",
          "code": "invalid_excel_row",
          "message": "برای رد صورتحساب حداقل یک دلیل لازم است.",
          "correlationId": "00000000-0000-0000-0000-000000000001"
        }
      ]
    }
  },
  "errors": [],
  "fieldErrors": [],
  "correlationId": "00000000-0000-0000-0000-000000000001"
}
فقط فایل .xlsx با Content-Type برابر application/vnd.openxmlformats-officedocument.spreadsheetml.sheet یا application/octet-stream پذیرفته می‌شود و سرور ساختار آن را هم بررسی می‌کند. هدر Content-Length الزامی است؛ ارسال تکه‌ای (chunked) بدون آن با HTTP 411 رد می‌شود. حجم فایل به‌طور پیش‌فرض حداکثر ۵ مگابایت و تعداد ردیف‌ها حداکثر ۵۰۰ است. کل فایل رد می‌شود اگر رمزدار باشد، ماکرو داشته باشد، در عنوان ستون‌ها فرمول باشد یا ستونی غیر از ستون‌های نمونه و خروجی داشته باشد. فرمول در یک سلول داده یا شناسه تکراری فقط همان ردیف را نامعتبر می‌کند. حداکثر عملیات قابل اجرای صورتحساب و قرارداد در هر نوبت به‌طور پیش‌فرض ۲۰ است و previewToken پانزده دقیقه اعتبار دارد. نتیجه هر اجرا برای تکرار امن و دریافت فایل نتیجه به‌طور پیش‌فرض ۲۴ ساعت نگه‌داری می‌شود.

نمونه cURL

JSON bulk approve
curl -X PUT "https://api-v2.asatsp.ir/api/v2/tax-workspace/invoices/bulk" \
  -H "Authorization: Bearer <AccessToken with v2.invoice.send>" \
  -H "X-Correlation-ID: 00000000-0000-0000-0000-000000000001" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"kind":"purchase","taxIds":["<TaxId1>","<TaxId2>"],"action":"APPROVE"}'
Excel preview then execute
curl -X POST "https://api-v2.asatsp.ir/api/v2/tax-workspace/invoices/purchase/excel/preview" \
  -H "Authorization: Bearer <AccessToken with v2.invoice.send>" \
  -F "file=@operations.xlsx;type=application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"

curl -X POST "https://api-v2.asatsp.ir/api/v2/tax-workspace/invoices/purchase/excel/execute" \
  -H "Authorization: Bearer <AccessToken with v2.invoice.send>" \
  -H "Content-Type: application/json" \
  -d '{"previewToken":"<PreviewToken>"}'

curl -X POST "https://api-v2.asatsp.ir/api/v2/tax-workspace/excel/result" \
  -H "Authorization: Bearer <AccessToken with v2.invoice.read>" \
  -H "Content-Type: application/json" \
  -d '{"resultToken":"<ResultToken>"}' \
  --output tax-workspace-result.xlsx

وضعیت‌های HTTP و کدهای خطا

HTTPCode نمونهمعنا
200invalid_excel_row / invoice_not_awaiting_reaction / contract_not_actionable / duplicate_identifierخطای هر ردیف در نتیجه همان ردیف می‌آید و بقیه ردیف‌ها اجرا می‌شوند: پیش‌نمایش در data.rows[].previewStatus و previewCode، واکنش گروهی JSON در data.results[] و اجرای Excel در data.summary.results[]. فقط در پیش‌نمایش Excel قرارداد، خاموش بودن تأیید و رد قرارداد و نبود مجوز آن هم در همین ستون‌ها می‌آید.
400invalid_bulk_size / invalid_excel_preview_token / tax_workspace_excel_file_required / validation_failedاندازه Batch، Token پیش‌نمایش، ساختار multipart یا پارامترهای خواندن فهرست (مثلاً بازه بیش از یک روز تهران یا pageSize بیشتر از ۱۰) نامعتبر است.
400کدهای tax_workspace_excel_*، مثلاً tax_workspace_excel_unexpected_header، tax_workspace_excel_header_missing، tax_workspace_excel_data_sheet_missing، tax_workspace_excel_invalid_package و tax_workspace_excel_macro_or_encryption_not_allowedساختار فایل پذیرفته نیست و کل فایل رد می‌شود.
401unauthorizedAccess Token/API Key ارسال نشده یا معتبر نیست.
403forbidden / IP_NOT_ALLOWED / tax_workspace_excel_token_context_mismatch / delegation_permission_missingScope لازم در توکن نیست یا توکن برای این مسیر نیست (مثلاً توکن همکار)، Customer API Key قدیمی از نشانی‌ای بیرون از محدودیت IP رسیده است، Token متعلق به Company، API Client، کارپوشه یا نوع عملیات جاری نیست، یا مجوز لازم آن فهرست (مثلاً مشاهده خرید یا قرارداد) در دسترسی واگذارشده کارپوشه نیست. علت در errors[].message می‌آید.
403tax_workspace_contract_permission_missingمجوز contract.brokerage:manage در دسترسی واگذارشده نیست؛ واکنش گروهی JSON و اجرای Excel قرارداد با همین پاسخ رد می‌شوند.
404unsupported_invoice_kindمقدار {kind} در مسیر پشتیبانی نمی‌شود.
408request_cancelled / upstream_timeoutدرخواست در زمان پردازش لغو شده یا زمان آن به پایان رسیده است؛ upstream_timeout یعنی سامانه مؤدیان به‌موقع پاسخ نداد.
409tax_workspace_excel_export_row_limit_exceeded / tax_workspace_invoice_bulk_action_limit_exceeded / tax_workspace_contract_bulk_action_limit_exceeded / tax_workspace_excel_execution_in_progress / tax_workspace_excel_execution_outcome_unknown / tax_workspace_excel_token_expired / tax_workspace_excel_result_expiredسقف نتیجه یا عملیات رد شده، اجرای همان Preview در حال انجام یا نتیجه قبلی نامشخص است، یا مهلت Preview/Result پایان یافته است. این پاسخ‌ها مجوز Retry کور PUT نیستند.
403tax_workspace_permission_missing (همراه کد سازمان ACCESS_DENIED)سامانه مؤدیان گفته است مجوز همین سرویس در تفویض نیست. فقط همین عملیات ناموفق است و دسترسی واگذارشده و دیگر مجوزهای آن سر جایشان می‌مانند؛ برای این بخش، مدیر کسب‌وکار باید از تنظیمات کسب‌وکار دسترسی را با همین مجوز دوباره بگیرد.
409tax_workspace_reauthorization_requiredدسترسی واگذارشده کارپوشه فعال نیست یا اعتبار آن تمام شده است؛ مدیر کسب‌وکار باید از تنظیمات کسب‌وکار در پنل دوباره دسترسی بگیرد. تکرار درخواست تا آن زمان نتیجه‌ای ندارد.
411tax_workspace_excel_content_length_requiredارسال Content-Length برای Upload الزامی است.
413tax_workspace_excel_file_too_large / tax_workspace_excel_row_limit_exceededحجم فایل یا تعداد ردیف‌های Upload از سقف تنظیم‌شده بیشتر است.
415tax_workspace_excel_invalid_content_type / tax_workspace_excel_invalid_extensionفایل multipart، پسوند یا Content-Type معتبر نیست.
500tax_workspace_internal_errorخطای پیش‌بینی‌نشده سرور؛ correlationId را برای پشتیبانی بفرستید.
502upstream_invalid_response / upstream_invalid_dataپاسخ سامانه مؤدیان قابل پردازش نبود.
503service_not_configured / tax_workspace_disabled / upstream_transport_errorتنظیمات سرور کامل نیست، سرویس در این محیط فعال نیست یا ارتباط با سامانه مؤدیان برقرار نشد.
503tax_workspace_excel_unavailableفایل Excel خروجی، نمونه یا نتیجه در سرور آماده نشد؛ درخواست شما ایرادی ندارد. کمی بعد دوباره تلاش کنید و اگر تکرار شد، correlationId را برای پشتیبانی بفرستید.
503tax_workspace_contract_reactions_disabledتأیید و رد قرارداد هنوز فعال نشده است؛ واکنش گروهی JSON و اجرای Excel قرارداد با همین پاسخ رد می‌شوند.

همه پاسخ‌های JSON این مسیرها، جز رد شدن Access Token به‌دلیل محدودیت IP، قالب Envelope دارند: status، data، errors[]، fieldErrors[] و correlationId. همان correlationId در هدر X-Correlation-ID هم برمی‌گردد. فایل موفق با HTTP 200 و Content-Type فایل xlsx برمی‌گردد؛ اگر فایل ساخته نشود، پاسخ JSON است.

اگر سامانه مؤدیان درخواست را رد کند، پاسخ با همان وضعیت HTTP سازمان (مثلاً 400 یا 406) برمی‌گردد؛ کد و پیام سازمان در errors[] و خطای هر فیلد در fieldErrors[] می‌آید. فیلد status متن آزاد است (مثلاً OK، SUCCESS، BADREQUEST یا NOT_ACCEPTABLE)؛ برای تصمیم‌گیری، وضعیت HTTP و errors[].code را بخوانید.

تا وقتی تأیید و رد قرارداد فعال نشده، دیدن فهرست و جزئیات قراردادها، فایل خروجی و نمونه Excel، صورتحساب‌ها و دسترسی واگذارشده عادی کار می‌کنند. پیش‌نمایش فایل قرارداد خوانده می‌شود، اما ردیف‌های دارای عملیات با وضعیت FEATURE_DISABLED برمی‌گردند. اگر تأیید و رد قرارداد فعال باشد ولی مجوز contract.brokerage:manage در دسترسی واگذارشده نباشد، کد tax_workspace_contract_permission_missing برمی‌گردد.
18کارپوشهٔ مالیاتی

شناسه یکتای حافظه مالیاتی با API

نرم‌افزار متصل یا نرم‌افزار همکار می‌تواند شناسه یکتای حافظه مالیاتی را بدون ورود مؤدی به کارپوشه، مستقیم از سامانه مؤدیان بگیرد. آسا به‌عنوان شرکت معتمد درخواست را می‌فرستد؛ رضایت مالک با رمز یک‌بارمصرفی است که سامانه مؤدیان به موبایل ثبت‌شده در کارپوشه مالیاتی مؤدی می‌فرستد. همان رمز دسترسی آسا به کارپوشه را هم فعال می‌کند (همه مجوزهای قابل تفویض، از جمله memory-unique-id:manage).

دو راه: کسب‌وکاری که به API v2 وصل است، با اعتبارنامه Customer خودش (v2.invoice.read و v2.invoice.send) دسترسی را می‌گیرد و شناسه را دریافت می‌کند؛ شناسه همان لحظه روی کسب‌وکار ثبت می‌شود و برای ارسال صورتحساب آماده است. نرم‌افزار همکار برای مؤدی‌ای که هنوز در آسا ثبت نشده، با اعتبارنامه Partner (v2.register) همین کار را انجام می‌دهد؛ شناسه فقط برگردانده می‌شود و همکار با آن POST /api/register را صدا می‌زند. پیش از تأیید رمز هیچ کسب‌وکاری ساخته نمی‌شود.

Endpointها

MethodEndpointاعتبارنامه / Scopeکاربرد
GET/api/v2/tax-workspace/delegationCustomer / v2.invoice.readوضعیت دسترسی کارپوشه همین کسب‌وکار: usable، otpPending، maskedMobile، expiresAt، memoryPermissionGranted.
POST/api/v2/tax-workspace/delegation/otpCustomer / v2.invoice.sendارسال رمز سامانه مؤدیان به موبایل مالک. بدنه اختیاری: {"validityDurationDays": 365} (۱ تا ۳۶۵).
POST/api/v2/tax-workspace/delegation/verifyCustomer / v2.invoice.sendتأیید رمز: {"otp": "123456"}.
POST/api/v2/tax-workspace/memory-unique-idCustomer / v2.invoice.sendدریافت شناسه یکتای تازه و ثبت آن روی کسب‌وکار. بدنه اختیاری: {"title": "..."}.
POST/api/v2/tax-workspace/onboarding/otpPartner / v2.registerارسال رمز برای مؤدی ثبت‌نشده: {"economicCode": "14000000001"}.
POST/api/v2/tax-workspace/onboarding/verifyPartner / v2.registerتأیید رمز: {"economicCode": "14000000001", "otp": "123456"}.
POST/api/v2/tax-workspace/onboarding/memory-unique-idPartner / v2.registerدریافت شناسه یکتا برای همان شماره اقتصادی، فقط تا ۳۰ دقیقه پس از تأیید رمز توسط همین همکار.

روند همکار برای مؤدی تازه

  1. POST /api/v2/tax-workspace/onboarding/otp با شماره اقتصادی مؤدی؛ پاسخ maskedMobile، otpLength و otpExpiresAt (epoch milliseconds) را برمی‌گرداند. تا پایان اعتبار، رمز دوباره فرستاده نمی‌شود.
  2. مؤدی رمز پیامک‌شده را به شما می‌دهد؛ POST /api/v2/tax-workspace/onboarding/verify.
  3. POST /api/v2/tax-workspace/onboarding/memory-unique-id؛ مقدار memoryUniqueId را بردارید.
  4. POST /api/register با همان economicCode و fiscalId برابر memoryUniqueId. اگر environment در پاسخ مرحله ۳ برابر Sandbox بود، sandBox: true را هم بفرستید؛ شناسه Sandbox در محیط عملیاتی پذیرفته نمی‌شود.
پاسخ onboarding/otp و delegation/otp
{
  "status": "OK",
  "data": {
    "economicCode": "14000000001",
    "status": "PendingOtp",
    "usable": false,
    "otpPending": true,
    "maskedMobile": "0912***4567",
    "otpLength": 6,
    "otpExpiresAt": 1792300000000,
    "expiresAt": null,
    "grantedPermissions": [],
    "memoryUniqueIdAvailable": true,
    "memoryPermissionGranted": false
  },
  "errors": [],
  "fieldErrors": [],
  "correlationId": "3f2c1d7e9b8a4c6d8e1f0a2b3c4d5e6f"
}
پاسخ memory-unique-id
{
  "status": "SUCCESS",
  "data": {
    "memoryUniqueId": "A1B2C3",
    "message": "درخواست با موفقیت انجام شد.",
    "companyTokenId": 1234,
    "created": true,
    "environment": "Production"
  },
  "errors": [],
  "fieldErrors": [],
  "correlationId": "3f2c1d7e9b8a4c6d8e1f0a2b3c4d5e6f"
}

در روند همکار، companyTokenId خالی است و created مقدار false دارد؛ شناسه پس از /api/register روی کسب‌وکار ثبت می‌شود.

خطاها

HTTPcodeمعنا
400validation_failed / invalid_validity / invalid_otpشماره اقتصادی ۱۱ یا ۱۴ رقم نیست، مدت اعتبار بیرون از ۱ تا ۳۶۵ است یا رمز ناقص است.
400 / 429TSP_OTP_IS_WRONG، TSP_OTP_NOT_EXIST، TSP_OTP_MAX_ATTEMPTS_EXCEEDED، TSP_OTP_REQUEST_LIMIT_EXCEEDED، INVALID_TAX_PROFILE_STATUSپاسخ خود سامانه مؤدیان، بی‌تغییر (رمز نادرست، منقضی، تلاش زیاد، سقف درخواست، کارپوشه غیرفعال).
403tax_workspace_memory_permission_missingدسترسی فعلی مجوز memory-unique-id:manage را ندارد؛ رمز تازه بگیرید.
409tax_workspace_reauthorization_required / pending_otp_not_foundدسترسی منقضی یا لغو شده، یا رمز فعالی برای تأیید نیست.
409onboarding_owner_check_requiredاین همکار در ۳۰ دقیقه گذشته رمز همین شماره اقتصادی را تأیید نکرده است.
400exceeding.the.limit.unique.id / at.least.one.branch.is.requiredسقف شناسه‌های فعال مؤدی پر است، یا سامانه برای این پرونده انتخاب شعبه می‌خواهد (شناسه را در کارپوشه بسازید).
429rate_limitedبیش از ۶۰ درخواست رمز در ساعت از یک اعتبارنامه همکار.
503tax_workspace_disabled / tax_workspace_memory_unique_id_disabled / service_not_configuredسرویس کارپوشه یا دریافت شناسه در این محیط فعال نیست.

هر درخواست، با شماره اقتصادی و نتیجه، در گزارش عملیات کارپوشه ثبت می‌شود؛ رمز و توکن هرگز ذخیره یا برگردانده نمی‌شوند. قالب پاسخ همان Envelope بخش کارپوشه (status، data، errors[]، fieldErrors[]، correlationId) است.

19کارپوشهٔ مالیاتی

ثبت پرداخت صورتحساب ارسال‌شده در کارپوشه

برای صورتحسابی که با روش تسویه نسیه یا نقدی/نسیه به سامانه مؤدیان ارسال و در کارپوشه ثبت شده است، پرداخت‌های بعدی خریدار از طریق سرویس رسمی «ثبت پرداخت صورتحساب» (invoice-payment، مستند RC_TICS.IS) در کارپوشه ثبت می‌شوند. این سرویس همان کار را برای شما انجام می‌دهد: پرداخت‌های جدید روی آخرین صورتحساب زنجیره internalId ذخیره می‌شوند، نسخهٔ جدید صورتحساب با همان شماره مالیاتی ساخته می‌شود (اصلاحی صادر نمی‌شود) و هر ردیف جدید در همان درخواست به سامانه مؤدیان فرستاده می‌شود. اگر پاسخ سازمان به موقع نرسد یا خطای گذرا (مانند کد 10015) برگردد، ثبت به‌صورت خودکار دوباره تلاش می‌شود و نتیجه را با /api/invoice/inquiryPayment پیگیری می‌کنید.

مسیرscopeبدنهکاربرد
POST /api/invoice/registerPaymentv2.invoice.senduuid، internalId، payments[]افزودن پرداخت‌های جدید به صورتحساب ارسال‌شده و ثبت آن‌ها در کارپوشه.
POST /api/invoice/inquiryPaymentv2.invoice.readinternalIdوضعیت همهٔ ردیف‌های پرداخت صورتحساب و وضعیت ثبت هر کدام در کارپوشه.
پیش‌شرط صورتحساب

آخرین صورتحساب زنجیره باید ارسال‌شده و در سامانه مؤدیان ثبت شده باشد (وضعیت تأیید شده، تأیید سیستمی یا در انتظار واکنش)، ابطالی نباشد و روش تسویه‌ای که به سازمان ارسال شده نقدی نباشد؛ الگوی بورس (inp=11) اطلاعات پرداخت ندارد. ثبت پرداخت فقط برای صورتحساب نوع ۱ است؛ صورتحساب نوع ۲ با کد دلیل CASH_SETTLEMENT پذیرفته نمی‌شود. روش تسویهٔ صورتحساب با ثبت پرداخت تغییر نمی‌کند (همان است که به سازمان رفته). در غیر این صورت خطای INVOICE_PAYMENT_NOT_APPLICABLE با دلیل در errors[].message و کد دلیل در errors[].field برمی‌گردد و چیزی ذخیره نمی‌شود.

تاریخ پرداخت

تاریخ و زمان هر پرداخت نباید قبل از تاریخ و زمان صدور صورتحساب باشد (خطای INVOICE_PAYMENT_DATE_BEFORE_ISSUE در مسیر $.payments[i].dateTime) و نباید بعد از زمان حال باشد (خطای INVOICE_PAYMENT_DATE_IN_FUTURE در همان مسیر، معادل کد رسمی 10013؛ مقایسه به وقت تهران و با چند دقیقه اغماض برای اختلاف ساعت). سازمان همچنین پرداخت خارج از دورهٔ جاری را نمی‌پذیرد (کد رسمی 10012)؛ این یکی در نتیجهٔ ثبت همان ردیف با وضعیت rejected برمی‌گردد.

ردیف‌های قبلی قفل هستند

ردیفی که سازمان دارد (همراه صورتحساب رفته یا با این سرویس ثبت شده) دیگر قابل ویرایش یا حذف نیست، چون سامانه مؤدیان سرویسی برای حذف یا اصلاح پرداخت ندارد. این سرویس فقط پرداخت اضافه می‌کند؛ در پاسخ، payments[].locked این ردیف‌ها را نشان می‌دهد.

تکرار درخواست

uuid برای هر درخواست الزامی و در محدودهٔ شرکت یکتاست؛ ارسال دوبارهٔ همان uuid با result: -2 و کد INVOICE_PAYMENT_DUPLICATE_REQUEST رد می‌شود تا یک پرداخت دو بار ثبت نشود. پس از قطع ارتباط، ابتدا با inquiryPayment وضعیت را ببینید و فقط پرداخت‌هایی را که در فهرست نیستند با uuid تازه بفرستید.

فیلدهای درخواست registerPayment

فیلدقاعدهتوضیح
tokenاختیاریتوکن تکمیلی نمایندگی، مانند سایر سرویس‌ها.
uuidالزامی، GUID یکتا برای شرکتشناسهٔ این درخواست؛ برای کنترل تکراری‌بودن.
internalIdالزامیکد داخلی صورتحساب؛ آخرین صورتحساب زنجیرهٔ آن در نظر گرفته می‌شود.
paymentsآرایهٔ ۱ تا ۵۰ عضوهر عضو با همان مدل payments[] مدل ساده.
payments[].typeالزامی، 1 تا 8همان کدهای روش پرداخت مدل ساده (جدول مقادیر شمارشی)؛ به ترتیب به paymentMethod سرویس سازمان (CHEQUE، BARTER، CASH، POS، INTERNET، CARD، TRANSFER، OTHER) نگاشت می‌شود.
payments[].dateTimeالزامی؛ Unix time میلی‌ثانیه، yyyyMMddHHmmss یا تاریخ شمسی 1405/06/25 10:30تاریخ و زمان پرداخت؛ نباید قبل از صدور صورتحساب باشد.
payments[].priceالزامی، عدد ریالی بزرگ‌تر از صفر، حداکثر ۱۸ رقممبلغ پرداخت همان‌طور که خریدار پرداخته (با مالیات بر ارزش افزوده)؛ اعشار حذف می‌شود. آنچه به کارپوشه می‌رود (paidAmount) سهم بدون مالیات همین مبلغ است: کارپوشه مبالغ تسویه را بدون مالیات نگه می‌دارد و «سهم مالیات بر ارزش افزوده از پرداخت» را خودش می‌افزاید؛ سهم مالیات با نسبت مالیات به مبلغ نهایی همان صورتحساب محاسبه و از مبلغ کم می‌شود (مثلاً روی صورتحساب ۱۰٪، پرداخت ۳٬۲۴۲٬۱۷۰ ریال با paidAmount برابر ۲٬۹۴۷٬۴۲۸ ثبت می‌شود). مبلغ ثبت‌شده در payments[].registration.registeredAmount برمی‌گردد.
payments[].terminalNumberاختیاری، فقط رقم، حداکثر ۸ رقمشماره پایانه (terminalNumber).
payments[].traceNoاختیاری، فقط رقم، حداکثر ۱۴ رقمشماره پیگیری یا مرجع پرداخت (referenceNumber).
payments[].cardNo، payerNationalCode، switchNumber، acquirerNumber، descriptionاختیاری (رقم، به ترتیب حداکثر ۱۶، ۱۲، ۹ و ۱۴ رقم)در سوابق شما ذخیره می‌شوند و به سرویس ثبت پرداخت سازمان فرستاده نمی‌شوند.
registerPayment request
{
  "uuid": "1f0c0f1e-6b1c-4c7b-9a2e-4d5a9d2f7a11",
  "internalId": "INV-10001",
  "payments": [
    {
      "type": 6,
      "dateTime": "1405/06/25 10:30",
      "price": 25000000,
      "traceNo": "13023878656431",
      "terminalNumber": "1302387",
      "description": "قسط دوم"
    }
  ]
}

فیلدهای پاسخ

پاسخ در قالب همیشگی (result، traceId، message، errors، data) با HTTP 200 برمی‌گردد. عضو data[0] همان اطلاعات استعلام صورتحساب است به‌علاوهٔ paymentRegistration (قابلیت ثبت پرداخت روی این صورتحساب) و payments[] (همهٔ ردیف‌های پرداخت صورتحساب با وضعیت هر کدام). در خطا، result برابر 0 (تکراری -2، احراز هویت -1) است و کدها در errors[].code می‌آیند.

فیلدتوضیح
paymentRegistration.eligibletrue یعنی پرداخت‌های جدید روی این صورتحساب در کارپوشه ثبت می‌شوند؛ در غیر این صورت code و reason دلیل را می‌گویند.
paymentRegistration.rowsLockedصورتحساب ارسال‌شده است و ردیف‌های قبلی پرداخت آن قابل تغییر نیستند.
payments[].id، type، dateTime، timestamp، price، traceNo، terminalNumberردیف پرداخت. dateTime تاریخ میلادی و ساعت به وقت تهران با قالب yyyy/MM/dd HH:mm است (مثلاً 2026/09/16 10:30) و timestamp همان زمان به Unix time میلی‌ثانیه؛ برای پردازش، timestamp را بخوانید.
payments[].lockedردیف نزد سازمان است (یا ممکن است باشد) و دیگر تغییر نمی‌کند.
payments[].registration.statusوضعیت ثبت در کارپوشه؛ مقادیر در جدول زیر.
payments[].registration.code، messageکد و پیام رسمی سازمان در رد شدن (مثلاً 10014)، یا کد داخلی خطای انتقال.
payments[].registration.registeredAmountمبلغی که برای این ردیف به کارپوشه فرستاده شده (paidAmount، بدون سهم مالیات بر ارزش افزوده)؛ فقط وقتی ثبتی وجود دارد.
payments[].registration.registeredAt، lastAttemptAt، taxCreateDateزمان ثبت موفق، زمان آخرین تلاش و createDate برگشتی از سازمان (Unix time میلی‌ثانیه).

مقادیر status

statusمعنااقدام
registeredسازمان ثبت پرداخت را با SUCCESS پذیرفته است.—
queuedدر صف ثبت یا تلاش مجدد خودکار (پاسخ سازمان به موقع نرسیده یا خطای گذرا داشته).بعداً با inquiryPayment پیگیری کنید.
rejectedسازمان با خطای رسمی رد کرده است (code و message).علت را رفع کنید؛ ردیف ردشده در پنل قابل ویرایش است.
unknownدرخواست به سازمان رسیده ولی پاسخ آن گم شده است؛ ممکن است ثبت شده باشد.خودکار تکرار نمی‌شود؛ ابتدا کارپوشه را بررسی کنید و در صورت نیاز از پنل «تلاش مجدد» بزنید.
notApplicableهرگز فرستاده نشده است (تسویه نقدی، صورتحساب ابطالی، روش یا تاریخ نامعتبر).—
failedتلاش‌های خودکار به پایان رسیده است.از پنل «تلاش مجدد» بزنید یا با پشتیبانی تماس بگیرید.
sentWithInvoiceردیف همراه خود صورتحساب به سازمان رفته است (بخش Payments صورتحساب).—
notRegisteredصورتحساب هنوز ارسال نشده و ردیف با خود صورتحساب خواهد رفت.—
registerPayment response
{
  "result": 1,
  "traceId": "0f6c5f7a-2f6b-4a4f-9f5a-1b2c3d4e5f60",
  "message": "پرداخت‌ها ثبت شدند.",
  "data": [
    {
      "internalId": "INV-10001",
      "taxId": "A111H104EA6001D0B32AC6",
      "status": 2,
      "statusInquery": "AWAITING_REACTION",
      "paymentRegistration": { "eligible": true, "rowsLocked": true },
      "payments": [
        {
          "id": 50622,
          "type": 6,
          "dateTime": "2026/09/16 10:30",
          "timestamp": 1789542000000,
          "price": 25000000,
          "traceNo": "13023878656431",
          "terminalNumber": "1302387",
          "description": "قسط دوم",
          "locked": true,
          "registration": {
            "status": "registered",
            "registeredAt": 1789542065000,
            "taxCreateDate": 1789542064000,
            "registrationId": 12,
            "registeredAmount": 22727273
          }
        }
      ]
    }
  ]
}
این سرویس فقط پرداخت‌های بعد از ارسال را ثبت می‌کند. پرداخت‌هایی که هنگام ثبت صورتحساب در payments[] (مدل ساده) یا Payments (JSON سازمان) می‌فرستید همراه خود صورتحساب به سازمان می‌روند و در استعلام با وضعیت sentWithInvoice دیده می‌شوند.
19Aکارپوشه مالیاتی

استعلام پرونده مالیاتی

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

مسیرscopeبدنهکاربرد
POST /api/v2/tax-file-inquiryv2.lookup.readidentifierفهرست پرونده‌های مالیاتی یک کد ملی، شناسه ملی، کد فراگیر اتباع یا شماره اقتصادی.
پیش‌شرط: سرویس ارزش‌افزوده

این استعلام همان سرویس ارزش‌افزوده «استعلام پرونده مالیاتی خریدار» در پنل است. کسب‌وکار باید خودش آن را در پنل، بخش «تنظیمات کسب‌وکار ← سرویس‌ها و تعرفه‌ها»، فعال کند. تا سرویس فعال نشده، پاسخ 403 با کد tax_file_inquiry_not_active است و از سامانه مؤدیان چیزی پرسیده نمی‌شود.

هزینه هر استعلام

هزینه طبق تعرفه همین سرویس در پنل است و از کیف پول کسب‌وکار کم می‌شود. هر استعلامی که سامانه مؤدیان به آن پاسخ دهد یک بار هزینه دارد؛ پاسخ «پرونده‌ای پیدا نشد» هم پاسخ سازمان است. شناسه نادرست و استعلامی که سازمان به آن پاسخ نداد هزینه‌ای ندارد. اگر موجودی کیف پول به اندازه یک استعلام نباشد، پاسخ 402 با کد tax_file_inquiry_wallet_insufficient است.

تکرار استعلام

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

سقف و درخواست هم‌زمان

این سرویس سقف روزانه ندارد. استعلام‌های هر کسب‌وکار یکی پس از دیگری انجام می‌شود: درخواست هم‌زمان تا ۳۰ ثانیه منتظر نوبت می‌ماند و اگر نوبت نرسد پاسخ 429 با کد tax_file_inquiry_busy می‌گیرد. درخواست‌ها را پشت سر هم بفرستید و مهلت پاسخ را در سامانه خودتان دست‌کم ۶۰ ثانیه بگذارید.

فیلدهای درخواست

فیلدقاعدهتوضیح
identifierالزامیکد ملی (۱۰ رقم)، شناسه ملی (۱۱ رقم)، کد فراگیر اتباع (۱۲ رقم) یا شماره اقتصادی (۱۱ یا ۱۴ رقم). رقم فارسی و خط تیره پذیرفته می‌شود. با کد ملی، همه پرونده‌های آن شخص فهرست می‌شود. عدد ۱۱ رقمی ابتدا به‌عنوان شماره اقتصادی و اگر پرونده‌ای نداشت به‌عنوان شناسه ملی پرسیده می‌شود.

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

POST /api/v2/tax-file-inquiry
curl -X POST "https://api-v2.asatsp.ir/api/v2/tax-file-inquiry" \
  -H "Authorization: Bearer <AccessToken with v2.lookup.read>" \
  -H "Content-Type: application/json; charset=utf-8" \
  --max-time 60 \
  -d '{"identifier":"0012345678"}'

فیلدهای پاسخ

پاسخ در همان Envelope سرویس‌های کارپوشه است: status، data، errors[]، fieldErrors[] و correlationId. مقدار correlationId در هدر X-Correlation-ID هم برمی‌گردد و همین استعلام را در گزارش کارپوشه کسب‌وکار در پنل نشان می‌دهد؛ هنگام پیگیری از پشتیبانی آن را بفرستید.

فیلدنوعتوضیح
data.identifierstringشناسه پرسیده‌شده با رقم لاتین و بدون جداکننده.
data.queriedBystringnationalId یا economicCode: شناسه با کدام عنوان از سازمان پرسیده شد.
data.foundbooleantrue وقتی دست‌کم یک پرونده پیدا شده است. با false فهرست taxFiles خالی است و data.message توضیح می‌دهد.
data.taxFiles[]arrayپرونده‌ها؛ پرونده‌های فعال اول می‌آیند.
taxFiles[].economicCodestring / nullشماره اقتصادی پرونده (۱۱ یا ۱۴ رقم). همین مقدار را در tinb یا buyer.economicCode صورتحساب بفرستید.
taxFiles[].nationalIdstring / nullکد ملی، شناسه ملی یا کد فراگیر صاحب پرونده.
taxFiles[].brandstring / nullنام تجاری ثبت‌شده برای پرونده، اگر سازمان آن را برگرداند.
taxFiles[].taxFileStatusstringوضعیت کارپوشه به مقدار سازمان: ACTIVE، NOT_ALLOCATED، TEMPORARY_UNAUTHORIZE یا PERMANENT_UNAUTHORIZE.
taxFiles[].taxFileStatusTitlestringعنوان فارسی همان وضعیت: «فعال»، «تخصیص نیافته»، «غیرمجاز موقت» یا «غیرمجاز دائم».
taxFiles[].activebooleantrue فقط برای کارپوشه فعال.
taxFiles[].callStatusTitlestring / nullوضعیت فراخوان مؤدی: «مشمول» یا «غیرمشمول».
taxFiles[].registrationStatusTitlestring / nullوضعیت ثبت‌نام پرونده در سامانه مؤدیان: «ثبت‌نام فعال» یا «ثبت‌نام غیرفعال».
taxFiles[].buyerTypenumber / nullنوع مؤدی از روی شناسه‌های پرونده، با همان کدهای tob: 1 حقیقی، 2 حقوقی، 3 مشارکت مدنی، 4 اتباع غیرایرانی. اگر از شناسه‌ها مشخص نشود null است.
taxFiles[].buyerTypeTitlestring / nullعنوان فارسی نوع مؤدی.
taxFiles[].warningstring / nullهشدار پیش از صدور صورتحساب نوع ۱ برای این پرونده، مثلاً وقتی کارپوشه فعال نیست و صورتحساب ممکن است در سامانه مؤدیان رد شود.
پاسخ: دو پرونده برای یک کد ملی
{
  "status": "OK",
  "data": {
    "identifier": "0012345678",
    "queriedBy": "nationalId",
    "found": true,
    "message": null,
    "taxFiles": [
      {
        "economicCode": "00123456780001",
        "nationalId": "0012345678",
        "brand": "فروشگاه نمونه",
        "taxFileStatus": "ACTIVE",
        "taxFileStatusTitle": "فعال",
        "active": true,
        "callStatusTitle": "مشمول",
        "registrationStatusTitle": "ثبت‌نام فعال",
        "buyerType": 1,
        "buyerTypeTitle": "حقیقی",
        "warning": null
      },
      {
        "economicCode": "00123456780002",
        "nationalId": "0012345678",
        "brand": null,
        "taxFileStatus": "NOT_ALLOCATED",
        "taxFileStatusTitle": "تخصیص نیافته",
        "active": false,
        "callStatusTitle": "مشمول",
        "registrationStatusTitle": "ثبت‌نام فعال",
        "buyerType": 1,
        "buyerTypeTitle": "حقیقی",
        "warning": "کارپوشه این پرونده «تخصیص نیافته» است؛ صورتحساب نوع ۱ برای این خریدار ممکن است در سامانه مؤدیان رد شود."
      }
    ]
  },
  "errors": [],
  "fieldErrors": [],
  "correlationId": "6f1c2d0a8b7e4c1e9a3b5d7f0c2e4a61"
}
پاسخ: پرونده‌ای پیدا نشد (HTTP 200)
{
  "status": "OK",
  "data": {
    "identifier": "0012345678",
    "queriedBy": "nationalId",
    "found": false,
    "message": "با این شناسه پرونده مالیاتی در سامانه مؤدیان پیدا نشد.",
    "taxFiles": []
  },
  "errors": [],
  "fieldErrors": [],
  "correlationId": "6f1c2d0a8b7e4c1e9a3b5d7f0c2e4a62"
}
پاسخ: سرویس برای کسب‌وکار فعال نیست (HTTP 403)
{
  "status": "FORBIDDEN",
  "data": null,
  "errors": [
    {
      "code": "tax_file_inquiry_not_active",
      "message": "«استعلام پرونده مالیاتی خریدار» سرویس ارزش‌افزوده است و برای این کسب‌وکار فعال نیست؛ آن را در پنل، بخش «تنظیمات کسب‌وکار ← سرویس‌ها و تعرفه‌ها»، فعال کنید."
    }
  ],
  "fieldErrors": [],
  "correlationId": "6f1c2d0a8b7e4c1e9a3b5d7f0c2e4a63"
}

خطاها

کد خطا را از errors[0].code بخوانید و متن errors[0].message را به کاربر نشان دهید.

HTTPCodeمعنا و اقدامهزینه
400validation_failedidentifier خالی است یا تعداد رقم‌های آن ۱۰، ۱۱، ۱۲ یا ۱۴ نیست. شناسه را اصلاح کنید.ندارد
401unauthorizedAccess Token ارسال نشده، نامعتبر یا منقضی است. توکن تازه بگیرید.ندارد
402tax_file_inquiry_wallet_insufficientسرویس فعال است ولی موجودی کیف پول کسب‌وکار به اندازه یک استعلام نیست. کیف پول را در پنل شارژ کنید.ندارد
403tax_file_inquiry_not_activeسرویس ارزش‌افزوده برای این کسب‌وکار فعال نیست. آن را در پنل فعال کنید.ندارد
403forbidden / IP_NOT_ALLOWEDتوکن scope لازم را ندارد، یا درخواست از نشانی‌ای خارج از محدودیت IP اعتبارنامه رسیده است.ندارد
429tax_file_inquiry_busyاستعلام قبلی همین کسب‌وکار هنوز در حال انجام است. همین درخواست را پس از تعداد ثانیه‌ای که هدر Retry-After می‌گوید تکرار کنید.ندارد
502organization_unavailableسامانه مؤدیان به استعلام پاسخ نداد. کمی بعد دوباره تلاش کنید.ندارد
503tax_file_lookup_unavailableاستعلام پرونده مالیاتی موقتاً در دسترس نیست. کمی بعد دوباره تلاش کنید.ندارد
504organization_timeoutپاسخ سامانه مؤدیان در مهلت ۱۵ ثانیه نرسید. کمی بعد دوباره تلاش کنید.ندارد
اگر فقط می‌خواهید شماره اقتصادی خریدار حقیقی هنگام ثبت صورتحساب نوع ۱ خودکار پر شود، به این سرویس نیاز ندارید: با فعال بودن همین سرویس ارزش‌افزوده، کد ملی خریدار را بدون tinb بفرستید و بخش خریدار حقیقی با کد ملی را ببینید. این سرویس برای وقتی است که می‌خواهید پرونده‌ها را پیش از صدور ببینید یا بین چند پرونده انتخاب کنید.
20مرجع

فهرست مسیرهای API

ثبت یا به‌روزرسانی مشتریPOST
/api/register ایجاد یا به‌روزرسانی مشتری و دریافت اعتبارنامهٔ مشتری (serviceAuth).
ثبت با JSON استاندارد سازمانPOST
/api/invoice/send ثبت صورتحساب با ساختار رسمی سازمان امور مالیاتی در آرایه data.
فروش نوع ۱ با اطلاعات خریدارPOST
/api/invoice/salesWithBuyerData مدل ساده آرایه‌ای برای صورتحساب نوع ۱، الگوی فروش عادی.
فروش نوع ۲ به مصرف‌کننده نهاییPOST
/api/invoice/salesEndUser مدل ساده آرایه‌ای برای صورتحساب نوع ۲ بدون الزام اطلاعات خریدار.
الگوهای تخصصی صورتحسابPOST
/api/invoice/simple/type/{invoiceType}/template/{template} مسیر عمومی همه ترکیب‌های مجاز نوع و الگو، و ۱۴ مسیر ثابت مانند exchange، jewelry، contracting، flightTicket، billOfLading، commoditySecurities و insuranceEndUser برای الگوهای ارز، طلا، پیمانکاری، قبوض، پرواز، صادرات، بارنامه، فرآورده‌های نفتی، اوراق مبتنی بر کالا، بیمه و فروش زنجیره.
ارسال دستی و ثبت ابطالPOST
/api/invoice/sendInvoice قرار دادن صورتحساب‌های ثبت‌شده در صف ارسال و ثبت صورتحساب ابطالی.
داده‌های مرجع واحد و ارزGET
/api/InvoiceItemUnit و /api/Currency دریافت کدهای مرجع مورد استفاده در unit و currencyCode.
پیگیری با کد داخلیPOST
/api/invoice/inquiryInternalId دریافت وضعیت صورتحساب بر اساس internalId ارسالی.
پیگیری با شماره صورتحسابPOST
/api/invoice/inquiryNo دریافت وضعیت صورتحساب بر اساس شماره داخلی یا inno.
پیگیری با شماره مالیاتیPOST
/api/invoice/inquiryTaxId دریافت وضعیت صورتحساب بر اساس شماره منحصر به فرد مالیاتی.
وضعیت اعلامیه فروش بورس (الگوی ۱۱)POST
/api/invoice/inquiryExchangeAnnouncement و /api/invoice/exchangeAnnouncement استعلام و ثبت دستی تأیید اعلامیه فروش بورس زنجیره صورتحساب؛ پس از تأیید، فقط ابطال مجاز است.
ثبت پرداخت صورتحساب ارسال‌شده در کارپوشهPOST
/api/invoice/registerPayment و /api/invoice/inquiryPayment افزودن پرداخت‌های بعدی به صورتحساب نسیه یا نقدی/نسیهٔ ارسال‌شده و ثبت خودکار آن‌ها در سامانه مؤدیان؛ پیگیری وضعیت هر ردیف.
استعلام پرونده مالیاتیPOST
/api/v2/tax-file-inquiry فهرست پرونده‌های مالیاتی یک کد ملی، شناسه ملی یا شماره اقتصادی با وضعیت کارپوشه؛ سرویس ارزش‌افزوده با هزینه هر استعلام.
ویرایش و اصلاح صورتحسابPOST
/api/invoice/editInvoice و /api/invoice/simple/editInvoice ویرایش صورتحساب قبلی با رفتار پنل؛ صورتحساب ثبت‌شده با صورتحساب اصلاحی و فقط با تأیید صریح تغییر می‌کند.
کارپوشه مالیاتی و عملیات ExcelGET / POST / PUT
/api/v2/tax-workspace/* خواندن فهرست صورتحساب‌ها و قراردادهای کارپوشه، تأیید و رد گروهی با JSON و Excel، دسترسی واگذارشده و شناسه یکتای حافظه مالیاتی.

این فهرست مسیرهای اصلی را نشان می‌دهد. همه مسیرهای API، با روش، scope و فیلدهای درخواست و پاسخ هر کدام، در فایل OpenAPI آمده است.

21مرجع

اعتبارسنجی JSON مطابق دستورالعمل

اعتبارسنجی پیش از تبدیل نهایی و ذخیره انجام می‌شود. مسیر خطاها با قراردادی مشابه JSONPath بازگردانده می‌شود؛ برای مثال $.data[1].data.Header.tbill به فیلد tbill در صورتحساب دوم اشاره دارد.

شناسه‌ها و کدها (tins، tinb، bid، bpc، inno، irtaxid، sstid، mu و شماره‌های پرداخت مانند trmn و pcn) را رشته JSON و داخل گیومه بفرستید؛ عدد بدون گیومه رد می‌شود. مبلغ‌ها، نرخ‌ها، تاریخ‌ها و کدهای شمارشی (مانند inty و pmt) عدد هستند.

ریشه درخواست

فیلدقاعدهنمونه خطا
$بدنه باید JSON object معتبر باشد. property تکراری پذیرفته نمی‌شود.ساختار JSON معتبر نیست.
uuidدر ریشه درخواست؛ رشته غیرخالی و GUID معتبر. شناسه کل درخواست گروهی است و برای هر درخواست جدید باید مقدار تازه‌ای داشته باشد.این uuid قبلاً در درخواست دیگری از شرکت احراز هویت‌شده ثبت شده است؛ محدوده شرکت فقط برای کنترل تکراری‌بودن استفاده می‌شود. کد خطا: INVOICE_DUPLICATE_REQUEST.
dataآرایه شامل ۱ تا ۲۵۰ صورتحساب؛ هر عضو مستقل اعتبارسنجی و پردازش می‌شود.بیشتر از ۲۵۰ عضو باعث رد کامل درخواست پیش از پردازش می‌شود.
data[].internalIdرشته غیرخالی، یکتا داخل همان درخواست گروهی و یکتا برای شرکت.internalId ارسالی قبلاً برای این شرکت ثبت شده است. (کد INVOICE_INTERNAL_ID_DUPLICATE؛ تکرار در همان درخواست: INVOICE_INTERNAL_ID_REPEATED_IN_REQUEST؛ خطاهای تکراری بودن)
data[].sendاختیاری و در صورت ارسال باید boolean باشد.true ارسال خودکار و false ثبت بدون ارسال را برای همان عضو قطعی می‌کند؛ در نبود فیلد، تنظیم «API نسخه ۲» کسب‌وکار اعمال می‌شود.
data[].dataobject شامل Header و Body.فیلد data الزامی است.

Header

فیلدقاعدهتوضیح
indatimUnix time عددی بر حسب میلی‌ثانیه، حداکثر 13 رقم.تاریخ و زمان صدور صورتحساب.
indati2mتاریخ و زمان ثبت صورتحساب؛ Unix time عددی بر حسب میلی‌ثانیه، حداکثر ۱۳ رقم و بدون اعشار.فقط در ماده ۹ و همراه insr=1 لازم است؛ باید مستقل از indatim و بزرگ‌تر یا مساوی آن باشد، از زمان ارسال جلوتر نباشد و فاصله آن تا ارسال بیش از ۱۵ روز نباشد.
insrقاعده ارسال صورتحساب؛ در حالت ماده ۹ مقدار عددی 1.برای صورتحساب خارج از مهلت ۱۵ روز همراه indati2m لازم است. برای صورتحساب عادی داخل مهلت، خارج از الگو است و در payload نهایی اعمال نمی‌شود.
inty1 یا 2نوع صورتحساب؛ در صورتحساب ابطالی نسخه ۷.۹ ارسال نمی‌شود و از مرجع دریافت می‌شود.
inp1، 2، 3، 4، 5، 6، 7، 8، 9، 11، 13 یا 14الگوی صورتحساب؛ در صورتحساب ابطالی نسخه ۷.۹ ارسال نمی‌شود و از مرجع دریافت می‌شود.
inty + inpنوع ۱: همه الگوهای مجاز؛ نوع ۲: 1، 3، 9، 13ترکیب نوع و الگو پیش از ثبت کنترل می‌شود و برای ترکیب نامعتبر خطای ساخت‌یافته برمی‌گردد.
ins1 اصلی، 2 اصلاحی، 3 ابطالی، 4 برگشت از فروشبرای غیر اصلی، irtaxid الزامی است. در ابطالی (ins=3) نوع، الگو، خریدار و اقلام از مرجع خوانده می‌شود: اگر inty، inp، فیلدهای خریدار، دیگر فیلدهای خارج از الگو یا Body را هم بفرستید، رد نمی‌شود؛ آن فیلدها نادیده گرفته می‌شوند و نامشان در warnings همان عضو پاسخ می‌آید. ابطالی فقط به مشخصات خودش نیاز دارد: indatim، inno، tins، ins=3 و irtaxid. روش تسویه (setm) و جمع‌های سرآمد را می‌توانید نفرستید؛ در این صورت از صورتحساب مرجع خوانده می‌شوند. در اصلاحی (ins=2) و برگشت از فروش (ins=4) هم خریدار از مرجع خوانده می‌شود و با این دو عوض نمی‌شود: فیلدهای خریدار و دیگر فیلدهای خارج از الگو در سرآمد، اقلام یا پرداخت رد نمی‌شوند، بلکه نادیده گرفته می‌شوند و نامشان در warnings می‌آید. برای تغییر خریدار، مرجع را ابطال کنید و صورتحساب تازه بفرستید. با ins=2 روی مرجعی که هنوز ارسال نشده، همان پیش‌نویس ویرایش می‌شود و اصلاحی صادر نمی‌شود؛ برای ویرایش با رفتار پنل از editInvoice استفاده کنید. پیش از ثبت اصلاحی، ابطالی یا برگشت از فروشِ مرجع ثبت‌شده، وضعیت زنجیرهٔ آن مانند پنل از کارپوشه گرفته می‌شود (کدهای خطا). در برگشت از فروش (ins=4)، Body اقلام باقی‌مانده پس از برگشت است (برگشت از فروش).
innoرشته شامل حروف و اعداد انگلیسی، حداکثر 10 کاراکتر.سریال داخلی حافظه مالیاتی.
tinsشماره اقتصادی فروشنده، 11 تا 14 رقم.باید با شرکت احراز هویت‌شده برابر باشد.
tob1 حقیقی، 2 حقوقی، 3 مشارکت مدنی، 4 اتباع غیر ایرانینوع شخص خریدار؛ برای صورتحساب نوع ۲ و الگوی صادرات اختیاری و برای صورتحساب ابطالی خارج از الگو است.
tinb11 تا 14 رقم.در صورت ارسال خریدار حقوقی الزامی است؛ در الگوی صادرات اختیاری و در صورتحساب ابطالی خارج از الگو است.
bid5 تا 14 رقم.برای نوع ۱ به‌جز الگوی صادرات، حداقل tinb یا bid لازم است؛ در صورتحساب ابطالی خارج از الگو است.
bpcدر صورت ارسال دقیقاً 10 رقم.کد پستی خریدار.
setm1 نقدی، 2 نسیه، 3 نقدی/نسیهروش تسویه. در ابطالی (ins=3) اختیاری است و اگر ارسال نشود، روش تسویه صورتحساب مرجع ثبت می‌شود.
capعدد ریالی غیرمنفی.فقط در روش نقدی/نسیه (setm=3) الزامی است (دستورالعمل V7.9، جدول ۲۵). در روش نقدی (setm=1) اختیاری است و اگر نیاید، کل صورتحساب نقدی ثبت می‌شود. اگر ارسال شود، جمع cap و insp نباید از tbill بیشتر باشد. در الگوی بورس inp=11 با روش نقدی/نسیه، همین مقدار سهم نقدی صورتحساب است و ذخیره می‌شود.
inspعدد ریالی غیرمنفی.فقط در روش نقدی/نسیه (setm=3) الزامی است (دستورالعمل V7.9، جدول ۲۶). در روش نسیه (setm=2) اختیاری است و اگر نیاید، کل صورتحساب نسیه ثبت می‌شود.
tprdis, tdis, tadis, tvam, todam, tbillجمع‌های Header باید با مجموع Body برابر باشند.برای الگوی صادرات برخی جمع‌ها اختیاری‌اند. در الگوی بورس inp=11، tprdis، tdis و todam خارج از الگو هستند و tadis الزامی و برابر adis است. در ابطالی (ins=3) این جمع‌ها لازم نیستند و مبالغ از صورتحساب مرجع گرفته می‌شود.
crnبرای الگوی پیمانکاری الزامی.شماره قرارداد.
billidبرای الگوی قبوض خدماتی الزامی.شناسه قبض.
bpnحداکثر ۹ حرف و رقم لاتین.در الگوی فروش ارز (inp=2) برای خریدار غیرایرانی فاقد کد فراگیر: tob=4 و bpn بدون bid؛ خریدار با همین شماره گذرنامه ثبت می‌شود.
scln, sccscln حداکثر 14 رقم؛ scc دقیقاً 5 رقم.شماره پروانه گمرکی (نوع ۱، الگوهای ۱ و ۲) و کد گمرک محل اظهار (نوع ۱، الگوهای ۱، ۲ و ۷)؛ ذخیره و به سامانه مؤدیان ارسال می‌شوند. مقدار خارج از این قالب نادیده گرفته می‌شود.
cdcn, cdcdcdcn حداکثر 14 رقم؛ cdcd روز Unix.شماره و تاریخ کوتاژ اظهارنامه گمرکی در الگوی صادرات (inp=7).
in, an9 تا 12 رقم.شناسه یکتای بیمه‌نامه (الزامی) و الحاقیه در الگوی بیمه (inp=13).
Body[].vbaعدد ریالی غیرمنفی.مبلغ پایه مالیات بر ارزش افزوده در الگوی ۹؛ مقدار بزرگ‌تر از صفر ذخیره و ارسال می‌شود.
asnرشته فقط شامل رقم، ۱ تا ۳۰ رقم.شماره اعلامیه فروش بورس؛ در الگوی بورس اوراق بهادار مبتنی بر کالا inp=11 برای صورتحساب اصلی و اصلاحی الزامی است.
asdعدد صحیح مثبت: تعداد روز از 1970/01/01 (Unix day؛ نه میلی‌ثانیه).تاریخ اعلامیه فروش بورس؛ در inp=11 الزامی است و نباید بعد از روز تقویمی تاریخ صدور indatim به وقت تهران باشد. برای نمونه، 20697 یعنی 2026/09/01 (1405/06/10).
inp=11فقط نوع ۱، یک ردیف، بدون برگشت از فروش (ins=4).tprdis، tdis و todam خارج از الگو هستند؛ مقدار صفر آن‌ها (و tprdis برابر tadis) حذف و مقدار دیگر رد می‌شود. سایر فیلدهای خارج از الگو (از جمله crn، billid و tax17) با مقدار صفر یا رشته خالی حذف می‌شوند و با مقدار دیگر پذیرفته نمی‌شوند. tadis الزامی است و باید برابر adis تنها ردیف باشد. در setm=3 جمع cap و insp باید برابر tbill باشد. نمونه کامل و قاعده مبلغ واحد در بخش الگوی ۱۱ آمده است.

Body

فیلدقاعدهتوضیح
Bodyآرایه شامل حداقل یک قلم.در الگوی بورس اوراق بهادار مبتنی بر کالا inp=11 و الگوی فروش زنجیره inp=14 فقط یک ردیف مجاز است؛ در صورتحساب ابطالی نسخه ۷.۹ کل Body حذف و اطلاعات از مرجع دریافت می‌شود.
sstidرشته 13 رقمی.شناسه کالا/خدمت.
ssttرشته حداکثر 400 کاراکتر، اختیاری.شرح کالا/خدمت.
muکد عددی واحد اندازه‌گیری.در صورت ارسال باید کد یکی از واحدهای فهرست /api/InvoiceItemUnit/codes باشد؛ کد ناشناخته با خطای همین فیلد رد می‌شود و صورتحساب ثبت نمی‌شود. در الگوی بورس inp=11 الزامی است.
amعدد مثبت.تعداد/مقدار.
feeعدد ریالی صحیح و غیرمنفی (بدون اعشار).مبلغ واحد؛ در همه الگوها به‌جز فروش ارز inp=2 (اختیاری) و بورس inp=11 الزامی است. مقدار اعشاری یا منفی در هر الگویی، حتی وقتی فیلد لازم نیست، خطا می‌گیرد. در الگوی بورس inp=11 خارج از الگوست: ارسال نکنید؛ مقدار معتبر ارسالی نادیده گرفته می‌شود، ذخیره نمی‌شود و به سامانه مؤدیان ارسال نمی‌شود، و با فعال شدن کنترل کامل Rule Matrix نسخه ۷.۹ برای این الگو با V79_OUT_OF_PATTERN رد خواهد شد. جزئیات در مبلغ واحد در الگوی ۱۱.
prdisعدد ریالی غیرمنفی.مبلغ قبل از تخفیف. در الگوی صادرات inp=7 اختیاری است؛ در الگوی بورس inp=11 خارج از الگوست؛ مقدار صفر یا برابر با adis حذف و هر مقدار دیگر رد می‌شود و adis از آن محاسبه نمی‌شود.
disعدد ریالی غیرمنفی، پیش‌فرض صفر.تخفیف. در الگوی بورس inp=11 خارج از الگوست؛ مقدار صفر حذف و مقدار غیرصفر رد می‌شود.
adisبرابر prdis - dis؛ در صورت ارسال‌نشدن از همین رابطه محاسبه می‌شود. در الگوی بورس inp=11 مقدار مستقل و الزامی است و از prdis، dis یا fee محاسبه نمی‌شود.مبلغ بعد از تخفیف. در الگوی بورس inp=11 باید دقیقاً ارزش معامله در اعلامیه فروش بورس (ریال، عدد صحیح بزرگ‌تر از صفر) باشد؛ همین مقدار عیناً ذخیره و ارسال می‌شود و لازم نیست بر am بخش‌پذیر باشد. مبلغ واحد نمایشی ذخیره‌شده از همین مقدار محاسبه می‌شود و ارسال نمی‌شود (مبلغ واحد در الگوی ۱۱).
vraعدد بین 0 تا 100.نرخ مالیات بر ارزش افزوده. در الگوهای صادرات (inp=7)، بورس (inp=11) و فروش زنجیره (inp=14) باید 0 باشد؛ نرخ بیشتر از صفر رد می‌شود.
vamعدد ریالی غیرمنفی.مبلغ مالیات بر ارزش افزوده. در الگوی بورس inp=11 باید 0 باشد.
cpr, sovatدر الگوی فروش ارز (inp=2) الزامی‌اند.cpr نرخ خرید ارز است (تا ۱۸ رقم صحیح و ۸ رقم اعشار) و sovat مأخذ مالیات بر ارزش افزوده (عدد ریالی صحیح و غیرمنفی).
odam, olamعدد ریالی غیرمنفی؛ در صورت عدم ارسال، صفر در نظر گرفته می‌شود.سایر مالیات/عوارض و وجوه قانونی. در الگوی بورس inp=11 خارج از الگوست؛ مقدار صفر حذف و مقدار غیرصفر رد می‌شود.
tsstamبرابر adis + vam + odam + olam.مبلغ کل ردیف.
cfee, cut, exrاگر اطلاعات ارزی ارسال شود، کنترل می‌شوند.میزان ارز، نوع ارز و نرخ برابری. cfee حداکثر 14 رقم صحیح و 4 رقم اعشار دارد؛ exr (و در مسیر ساده currencyRate) تا 18 رقم صحیح و 8 رقم اعشار پذیرفته و با همان اعشار ذخیره می‌شود؛ ارسال اعشار به سامانه مؤدیان فعلاً فقط در Sandbox انجام می‌شود و در محیط عملیاتی پس از آزمون Sandbox فعال می‌شود؛ در مسیر ساده همین قاعده برای amountCurrency (و در فروش ارز برای qty وقتی amountCurrency نیامده) کنترل می‌شود. در الگوی بورس inp=11 خارج از الگوست؛ مقدار صفر یا خالی حذف و مقدار دیگر رد می‌شود.
consfee, spro, bros, tcpbsبرای طلا/جواهر inp=3 الزامی است.اجرت، سود، حق‌العمل و جمع آن‌ها.
nw, ssrv, sscvبرای صادرات inp=7 الزامی.وزن خالص، ارزش ریالی و ارزش ارزی. در صادرات cfee، prdis، dis و adis خارج از الگو هستند و نباید فرستاده شوند؛ ارزش ارزی ردیف همان sscv است. در مسیر ساده /api/invoice/export همین ارزش با currencyValue فرستاده می‌شود.
cuiاختیاری؛ بزرگ‌تر از صفر، حداکثر 1000 و حداکثر ۲ رقم اعشار.عیار در الگوی بورس inp=11؛ مقدار 0 یعنی ارسال‌نشده و حذف می‌شود.

Payments

فیلدقاعدهتوضیح
Paymentsاختیاری؛ در صورت ارسال باید array باشد.جزئیات پرداخت. در الگوی بورس inp=11 خارج از الگوست؛ فیلد را حذف کنید یا آرایه خالی بفرستید.
pmtعدد صحیح یکی از مقادیر 1 تا 8.1 چک، 2 تهاتر، 3 وجه نقد، 4 کارت‌خوان (POS)، 5 درگاه پرداخت اینترنتی، 6 کارت‌به‌کارت، 7 انتقال به حساب، 8 سایر.
pdtUnix time عددی بر حسب میلی‌ثانیه.تاریخ پرداخت.
pvعدد ریالی غیرمنفی.نباید از tbill بیشتر شود.
acn14 رقم.برای pmt=4 الزامی.
trmn8 رقم.برای pmt=4 الزامی.
pcn16 رقم.برای pmt=4 الزامی.
iinn9 رقم.شماره سوئیچ پرداخت، اختیاری.
trn1 تا 14 رقم.شماره پیگیری یا مرجع، اختیاری.
pid1 تا 12 رقم.شناسه پرداخت‌کننده، اختیاری.

کنترل‌های محاسباتی

کنترلقاعدهمسیر خطا
مالکیت فروشندهHeader.tins برابر شماره اقتصادی کسب‌وکار احراز هویت‌شده.$.data[n].data.Header.tins
جمع قبل از تخفیفHeader.tprdis = sum(Body[].prdis)$.data[n].data.Header.tprdis
جمع تخفیفHeader.tdis = sum(Body[].dis)$.data[n].data.Header.tdis
جمع بعد از تخفیفHeader.tadis = sum(Body[].adis)$.data[n].data.Header.tadis
جمع ارزش افزودهHeader.tvam = sum(Body[].vam)$.data[n].data.Header.tvam
جمع کلHeader.tbill = sum(Body[].tsstam)$.data[n].data.Header.tbill
تسویهcap + insp <= tbill در صورت ارسال cap یا insp.$.data[n].data.Header.cap
پرداخت‌هامجموع Payments[].pv نباید از tbill بیشتر باشد.$.data[n].data.Payments
22مرجع

نکات مهم ساختار داده

موضوعتوضیحپیشنهاد پیاده‌سازی
مبالغ ریالیفیلدهای مبلغی باید به‌صورت عدد غیرمنفی و بدون اعشار ارسال شوند.محاسبات را پیش از serialization نهایی گرد و کنترل کنید.
تاریخ‌هاindatim، indati2m و pdt Unix time بر حسب میلی‌ثانیه هستند. indati2m فقط تاریخ ثبت ماده ۹ است و جایگزین indatim نمی‌شود.همه را به میلی‌ثانیه بفرستید. مقدار حداکثر ۱۰ رقمی indatim و pdt به ثانیه خوانده می‌شود، ولی indati2m ثانیه‌ای پذیرفته نمی‌شود.
حساسیت نام فیلدهانام فیلدها در سمت API به‌صورت case-insensitive پردازش می‌شوند.برای هماهنگی با نمونه‌ها از Header، Body و Payments استفاده کنید.
ارسال خودکارمقدار صریح send برای هر صورتحساب بر تنظیم کسب‌وکار اولویت دارد؛ در نبود آن، تنظیم مستقل «API نسخه ۲» استفاده می‌شود.برای رفتار قطعی همان درخواست، مقدار send: true یا send: false را ارسال کنید.
درخواست گروهیهر عضو data مستقل اعتبارسنجی و ذخیره می‌شود و پاسخ ۱:۱ به ترتیب ورودی برمی‌گردد. سقف هر درخواست ۲۵۰ عضو است.فقط اعضای دارای status: 3 را پس از اصلاح و با uuid جدید دوباره ارسال کنید.
23مرجع

داده‌های مرجع

مسیراحراز هویتکاربرد
GET /api/InvoiceItemUnitv2.lookup.readدیکشنری UnitId => Name: شناسه داخلی واحدها در معتمد آسا. این شناسه کد رسمی نیست و برای unit یا mu فرستاده نشود؛ از /api/InvoiceItemUnit/codes استفاده کنید (واحد اندازه‌گیری در مدل ساده).
GET /api/InvoiceItemUnit/codesv2.lookup.readآرایه [{ "code": "164", "name": "کیلوگرم" }]: کد رسمی هر واحد (سند واحدهای اندازه‌گیری سازمان، RC_UMGS_ST_V1_18)، همان مقداری که در Body[].mu و در مدل ساده در items[].unit فرستاده می‌شود؛ برای نمونه «عدد» 1627.
GET /api/Currencyv2.lookup.readدیکشنری Code => Name برای انتخاب ارزهای مجاز.
GET /api/v2/stuffid/{code}v2.lookup.readمشخصات یک شناسه کالا/خدمت ۱۳ رقمی از فهرست سامانه مودیان: { "result": 1, "data": { "code", "description", "type", "vatRate", "taxable", "category", "editDate" } }. شناسه‌ای که در فهرست نیست: HTTP 404 با کد STUFFID_NOT_FOUND؛ شناسه‌ای که ۱۳ رقم نیست: HTTP 400 با کد INVALID_STUFFID.

پاسخ موفق /api/InvoiceItemUnit، /api/InvoiceItemUnit/codes و /api/Currency خود فهرست است و فیلد result ندارد. اگر توکن نامعتبر باشد یا scope v2.lookup.read نداشته باشد، پاسخ این سه مسیر مانند سرویس‌های /api/invoice/* است: HTTP 200 با {"result": -1, "traceId": "…", "message": "…", "errors": [{ "path": "headers.Authorization", "message": "…" }]}. علت رد در errors[0].message و، اگر کد داشته باشد (مثلاً IP_NOT_ALLOWED)، در errors[0].code می‌آید.

محدودیت IP اعتبارنامه

با «محدودیت IP» (پنل: تنظیمات کسب‌وکار ← «اتصال API v2») اعتبارنامه کسب‌وکار و Customer API Key قدیمی آن در API نسخه ۲ فقط از نشانی‌های فهرست پذیرفته می‌شود. نشانی، همانی است که درخواست از آن به سرور آسا می‌رسد. تغییر فهرست حداکثر ظرف یک دقیقه اعمال می‌شود. API نسخه ۱ تا زمان بسته شدن در ۱ آذر ۱۴۰۵ از این محدودیت پیروی نمی‌کند؛ اعتبارنامه همکاران API (کارگزارها) هم جدا است و شامل آن نمی‌شود. درخواستی که از نشانی دیگر برسد پیش از هر بررسی دیگری رد می‌شود:

  • دریافت توکن (POST /api/auth/v2/token) و ساخت اعتبارنامه با کلید ثابت (POST /api/auth/v2/client-credentials): HTTP 403 با { "error": "ip_not_allowed", "code": "IP_NOT_ALLOWED", "error_description": "…" }.
  • هر سرویس دیگر با توکن کسب‌وکار: HTTP 403 با { "result": -1, "code": "IP_NOT_ALLOWED", "message": "…", "errors": [{ "path": "headers.Authorization", "code": "IP_NOT_ALLOWED" }] }.

این پاسخ را دوباره امتحان نکنید و توکن تازه هم نگیرید؛ نشانی سرور را در پنل به فهرست اضافه کنید. نرم‌افزار کسب‌وکار می‌تواند وضعیت را بخواند و اعتبارنامه را به نشانی سرور خودش محدود کند:

مسیراحراز هویتکاربرد
GET /api/v2/client/ip-accessتوکن کسب‌وکار{ "result": 1, "data": { "enabled", "allowedIps": [], "callerIp", "refused": [{ "at", "ip" }] } }؛ callerIp نشانی این سرور از دید آسا است.
POST /api/v2/client/ip-access/lockتوکن کسب‌وکارنشانی همین درخواست را به فهرست اضافه و محدودیت را روشن می‌کند؛ پاسخ مانند مسیر بالا. حذف نشانی یا خاموش کردن محدودیت فقط از پنل ممکن است. با Customer API Key قدیمی پاسخ HTTP 403 با کد CLIENT_CREDENTIALS_REQUIRED است.
24مرجع

خطاها و پاسخ‌ها

پاسخ‌های API دو قالب دارند. مسیرهای /api/invoice/* و /api/register با HTTP 200 پاسخ می‌دهند و نتیجه را باید از result خواند؛ پیام در message و خطاها در errors[] می‌آید (در /api/register کد خطا در فیلد error است). مسیرهای /api/v2/tax-workspace/*، /api/v2/partner/* و /api/v2/tax-file-inquiry قالب Envelope (status، data، errors[]، fieldErrors[] و correlationId) و وضعیت HTTP واقعی دارند. /api/v2/stuffid و /api/v2/client/* هم result دارند و هم وضعیت HTTP واقعی. در همه مسیرها، رد شدن به‌دلیل «محدودیت IP» پاسخ HTTP 403 با {"result": -1, "code": "IP_NOT_ALLOWED"} است و نشانی ناموجود پاسخ HTTP 404 (جزئیات). مقدار traceId یا correlationId را برای پیگیری پشتیبانی نگه دارید.

هر صورتحساب هر درخواست ثبت (و هر ابطال و ویرایش) یک ردیف در صفحه «لاگ‌های برنامه» پنل معتمد آسا با بخش «API نسخه ۲» دارد: نتیجه (موفق/ناموفق)، متن خطای همان صورتحساب، شماره صورتحساب، internalId و traceId در آن ثبت می‌شود و با جست‌وجوی هر کدام از این مقادیر پیدا می‌شود. برای دیدن علت رد یک صورتحساب، پیش از تماس با پشتیبانی همین صفحه را ببینید.
resultمعنانمونه وضعیت
-2درخواست تکراریuuid این درخواست قبلاً در محدوده شرکت احراز هویت‌شده ثبت شده و کل درخواست رد شده است (INVOICE_DUPLICATE_REQUEST).
-1احراز هویت نامعتبرهدر Authorization ارسال نشده، Access Token منقضی یا scope لازم وجود ندارد.
0هیچ صورتحسابی ثبت نشدهساختار ریشه یا uuid نامعتبر است، تعداد اعضا بیشتر از ۲۵۰ است، یا تمام اعضای آرایه خطا دارند.
1حداقل یک ثبت موفقممکن است همه اعضا موفق باشند یا پاسخ جزئی شامل اعضای موفق و اعضای دارای status: 3 باشد.
2، 3ثبت مشتریexists یا edit در پاسخ سرویس ثبت مشتری.

نشانی ناموجود و درخواست ردشده پیش از سرویس

نشانی‌ای زیر /api/ که سرویسی ندارد، پاسخ HTTP 404 با { "result": 0, "code": "ROUTE_NOT_FOUND", "message": "…", "traceId": "…", "errors": [{ "path": "$", "code": "ROUTE_NOT_FOUND" }] } می‌گیرد. درخواستی که پیش از رسیدن به سرویس رد شود، مثلاً به دلیل نویسه غیرمجاز در نشانی، با همین قالب، وضعیت HTTP همان خطا و کد BAD_REQUEST پاسخ می‌گیرد. خطای پیش‌بینی‌نشده سرور در این مرحله HTTP 500 و کد SERVER_ERROR دارد.

تکرار درخواست، پاسخ ROUTE_NOT_FOUND و BAD_REQUEST را تغییر نمی‌دهد؛ نشانی یا درخواست را با این مستندات اصلاح کنید. فقط SERVER_ERROR را می‌توان پس از کمی مکث دوباره امتحان کرد.

کدهای خطای اعلامیه فروش بورس (الگوی ۱۱)

این کدها در errors[].code برمی‌گردند. پاسخ HTTP مانند سایر سرویس‌ها 200 است؛ در سرویس‌های وضعیت اعلامیه، result برابر 0 است و در ثبت گروهی فقط همان عضو خطا می‌گیرد. سایر خطاها بدون code و مانند گذشته برمی‌گردند.

codepathمعنا و اقدام
EXCHANGE_ANNOUNCEMENT_CONFIRMED$.data[i] یا در sendInvoice مسیر $.internalIds[i]اعلامیه فروش بورس این زنجیره تأیید شده است؛ اصلاحی مجاز نیست و فقط ابطال امکان‌پذیر است. پیش‌نویس اصلاحی ثبت‌شده هم تا وقتی وضعیت «تأیید شده» است ارسال نمی‌شود.
EXCHANGE_ANNOUNCEMENT_STATUS_UNAVAILABLE$.data[i]، $.internalIds[i] یا $وضعیت تأیید اعلامیه موقتاً قابل خواندن نیست؛ اصلاحی الگوی ۱۱ فعلاً ممکن نیست. چند دقیقه بعد دوباره تلاش کنید. سایر صورتحساب‌ها تحت تأثیر نیستند.
INVOICE_NOT_FOUND$.internalId یا $.taxIdصورتحسابی با این شناسه در شرکت احراز هویت‌شده یافت نشد.
EXCHANGE_ANNOUNCEMENT_NOT_APPLICABLE$صورتحساب اصلی زنجیره نوع ۱ با الگوی ۱۱ نیست، هنوز با موفقیت ارسال نشده، یا صورتحساب درخواستی ابطالی است.
EXCHANGE_ANNOUNCEMENT_FORBIDDEN$وضعیت از سامانه سازمان (source: orgApi) دریافت شده است و فقط مدیر سامانه می‌تواند آن را به‌صورت دستی تغییر دهد.
EXCHANGE_ANNOUNCEMENT_NOTE_REQUIRED$.noteبرای تغییر دستی وضعیتی که از سامانه سازمان دریافت شده، ثبت توضیح الزامی است.
EXCHANGE_ANNOUNCEMENT_VERSION_CONFLICT$.expectedVersionوضعیت هم‌زمان تغییر کرده است؛ دوباره استعلام کنید و با version جدید ارسال کنید.
EXCHANGE_ANNOUNCEMENT_REQUEST_INVALID$، $.confirmed، $.note یا $.expectedVersionدرخواست نامعتبر است: هیچ‌یک یا هر دو فیلد internalId و taxId ارسال شده، confirmed ارسال نشده، توضیح بیش از ۵۰۰ کاراکتر است یا expectedVersion معتبر نیست.
INVOICE_PAYMENT_NOT_APPLICABLE$.internalIdروی این صورتحساب پرداخت در کارپوشه ثبت نمی‌شود: ارسال‌نشده یا بی‌نتیجه، ابطالی، الگوی بورس، یا روش تسویه نقدی. کد دلیل در field یکی از INVOICE_CANCELLED، INVOICE_NOT_SENT، INVOICE_NOT_APPROVED، INVOICE_WITHOUT_TAX_ID، PATTERN_WITHOUT_PAYMENTS یا CASH_SETTLEMENT است (صورتحساب نوع ۲ هم CASH_SETTLEMENT می‌گیرد) و توضیح در message می‌آید.
INVOICE_PAYMENT_DATE_BEFORE_ISSUE$.payments[i].dateTimeتاریخ و زمان پرداخت قبل از تاریخ و زمان صدور صورتحساب است؛ سازمان چنین پرداختی را نمی‌پذیرد (کد رسمی 10014).
INVOICE_PAYMENT_DATE_IN_FUTURE$.payments[i].dateTimeتاریخ و زمان پرداخت بعد از زمان حال (به وقت تهران، با چند دقیقه اغماض) است؛ پرداختی که هنوز انجام نشده ثبت نمی‌شود (کد رسمی 10013).
INVOICE_PAYMENT_ROW_LOCKED$.paymentsردیفی که سازمان دارد تغییر کرده یا حذف شده است؛ فقط افزودن پرداخت جدید ممکن است.
INVOICE_PAYMENT_DUPLICATE_REQUEST$.uuiduuid قبلاً برای این شرکت استفاده شده است (result: -2)؛ وضعیت را با inquiryPayment ببینید و با uuid تازه فقط پرداخت‌های ثبت‌نشده را بفرستید.
INVOICE_PAYMENT_REGISTRATION_DISABLED$ثبت پرداخت در کارپوشه موقتاً در سامانه غیرفعال است.
INVOICE_PAYMENT_INTERNAL_ERROR$خطای داخلی؛ با traceId به پشتیبانی مراجعه کنید.

کدهای خطای تکراری بودن درخواست و صورتحساب

پیام این خطاها تغییری نکرده است؛ برای تشخیص آن‌ها کد ثابت errors[].code را بخوانید، نه متن پیام. پاسخ HTTP 200 است. در ثبت گروهی، عضو ردشده در data[i] با status: 3 و همان پیام در error[] برمی‌گردد و سایر اعضا جداگانه ثبت می‌شوند؛ result اگر هیچ عضوی ثبت نشود 0 و در غیر این صورت 1 است.

codepathمعنا و اقدام
INVOICE_DUPLICATE_REQUEST$.uuiduuid قبلاً برای این شرکت استفاده شده است و کل درخواست رد می‌شود (result: -2). برای درخواست تازه uuid تازه بسازید. در ثبت پرداخت و ویرایش، کدهای INVOICE_PAYMENT_DUPLICATE_REQUEST و INVOICE_EDIT_DUPLICATE_REQUEST همین معنا را دارند.
INVOICE_INTERNAL_ID_DUPLICATE$.data[i].internalId؛ در cancelInvoice مسیر $.internalIdصورتحسابی با این internalId قبلاً برای این شرکت ثبت شده است؛ فقط همین عضو رد می‌شود. در cancelInvoice، کد داخلی ابطالی (cancelInternalId) تکراری است و کل درخواست با result: -2 رد می‌شود.
INVOICE_INTERNAL_ID_REPEATED_IN_REQUEST$.data[i].internalIdهمین internalId پیش‌تر در همین درخواست آمده است؛ عضو اول بررسی می‌شود و عضو تکراری رد می‌شود.
پاسخ نرسید؟ پیش از ارسال دوباره استعلام کنید. اگر پاسخ یک درخواست ثبت به دستتان نرسید (قطع ارتباط یا پایان زمان انتظار)، صورتحساب را با POST /api/invoice/inquiryInternalId استعلام کنید. اگر ثبت شده بود، دوباره نفرستید؛ اگر ثبت نشده بود، با uuid تازه و همان internalId بفرستید. پاسخ INVOICE_INTERNAL_ID_DUPLICATE به ارسال دوباره یعنی صورتحساب پیش‌تر ثبت شده است.

خریدار حقیقی با کد ملی: پرونده مالیاتی و هشدارهای ثبت

این بخش فقط برای کسب‌وکاری است که سرویس ارزش‌افزوده «استعلام پرونده مالیاتی خریدار» را خودش در پنل («تنظیمات کسب‌وکار ← سرویس‌ها و تعرفه‌ها») فعال کرده باشد. تا سرویس فعال نشده، استعلامی انجام نمی‌شود و صورتحساب‌ها مثل قبل ثبت می‌شوند؛ هیچ‌کدام از کدهای زیر هم برنمی‌گردد.

اگر خریدار صورتحساب اصلی (ins: 1) نوع ۱ شخص حقیقی باشد و فقط کد ملی او بدون شماره اقتصادی (tinb) ارسال شود، پیش از ثبت، پرونده مالیاتی او از سامانه مؤدیان استعلام می‌شود:

  • یک پرونده: شماره اقتصادی همان پرونده روی خریدار ثبت می‌شود و صورتحساب نوع ۱ ثبت می‌شود. اگر کارپوشه یا ثبت‌نام آن پرونده فعال نباشد، هشدار آن هم برمی‌گردد، چون صورتحساب ممکن است در سامانه مؤدیان رد شود.
  • چند پرونده: صورتحساب با کد BUYER_TAX_FILE_AMBIGUOUS رد می‌شود و پیام خطا شماره اقتصادی هر پرونده را می‌آورد. شماره اقتصادی پرونده مربوط به این فروش را در tinb بفرستید.
  • بدون پرونده: صورتحساب حتی با کد پستی با کد BUYER_TAX_FILE_NOT_FOUND رد می‌شود. برای این خریدار صورتحساب نوع ۲ بفرستید.
  • استعلام انجام نشد (سامانه مؤدیان پاسخ نداد): صورتحساب مثل قبل ثبت می‌شود و هشدار «استعلام نشد» برمی‌گردد.
codepathمعنا و اقدام
BUYER_TAX_FILE_NOT_FOUND$.data[i]خریدار حقیقی با این کد ملی در سامانه مؤدیان پرونده مالیاتی ندارد و برای او صورتحساب نوع ۱ صادر نمی‌شود؛ صورتحساب را نوع ۲ ثبت کنید.
BUYER_TAX_FILE_AMBIGUOUS$.data[i]خریدار چند پرونده مالیاتی دارد؛ شماره اقتصادی پرونده مربوط را مستقیم در tinb (یا buyer.economicCode در ورودی ساده) بفرستید.
BUYER_TAX_FILE_LIMIT$.data[i]در هر درخواستِ چندصورتحسابی حداکثر ۵ کد ملیِ بدون شماره اقتصادی استعلام می‌شود و کد ملی این عضو از این سقف بیشتر است؛ شماره اقتصادی خریدار را بفرستید یا این صورتحساب را در درخواست جداگانه ثبت کنید. فقط همین عضو رد می‌شود.
BUYER_TAX_FILE_SERVICE_OFF$.data[i]سرویس ارزش‌افزوده «استعلام پرونده مالیاتی خریدار» فعال است ولی موجودی کیف پول کسب‌وکار برای هزینه یک استعلام کافی نیست؛ کیف پول را شارژ کنید یا شماره اقتصادی خریدار را بفرستید.

سقف هر درخواست: درخواستی که بیش از یک صورتحساب دارد حداکثر ۵ کد ملیِ متمایز (به ترتیب آرایه data) را استعلام می‌کند؛ صورتحساب‌های نوع ۱ بعد از آن با BUYER_TAX_FILE_LIMIT رد می‌شوند و بقیه ثبت می‌شوند. درخواست تک‌صورتحسابی سقفی ندارد.

سرویس ارزش‌افزوده: «استعلام پرونده مالیاتی خریدار» سرویس ارزش‌افزوده است و کسب‌وکار باید خودش آن را فعال کند. هزینهٔ آن طبق تعرفهٔ پنل برای هر استعلامی است که به سامانه مؤدیان می‌رود و از کیف پول کسب‌وکار کم می‌شود؛ پاسخ همان کد ملی در ۱۲ ساعت گذشته و استعلامی که انجام نشد هزینه ندارد.

در صورتحساب نوع ۲ با خریدار حقیقی و کد ملی، استعلام پس از ثبت و در پس‌زمینه انجام می‌شود. اگر خریدار پرونده داشته باشد، هشدار «می‌توانستید صورتحساب نوع ۱ صادر کنید» فقط در تاریخچه صورتحساب در پنل ثبت می‌شود و در پاسخ همین درخواست نمی‌آید. در درخواست چندصورتحسابی این بررسی فقط وقتی انجام می‌شود که فیلد اختیاری ریشه "checkTypeTwoBuyers": true فرستاده شود، و آن‌وقت در همان سقف ۵ کد ملی حساب می‌شود.

در ورودی ساده، اگر stuffId یک قلم خالی باشد ولی کالا/خدمتی با همان internalId از قبل در کسب‌وکار ثبت شده و شناسه کالا/خدمت دارد، همان شناسه استفاده می‌شود و صورتحساب با هشدار ثبت می‌شود.

در ورودی ساده، اگر unit یک قلم به‌جای کد رسمی، شناسه داخلی واحد باشد، یا واحد کد رسمی نداشته باشد و ردیف بدون mu برود، صورتحساب ثبت می‌شود و هشدار آن همراه کد رسمی درست برمی‌گردد (واحد اندازه‌گیری در مدل ساده).

هشدارهای ثبت در فیلد اختیاری warnings عضو موفق پاسخ send و سرویس‌های ورودی ساده برمی‌گردند و در تاریخچه صورتحساب هم ثبت می‌شوند. اگر هشداری نباشد، این فیلد در پاسخ نمی‌آید؛ کلاینتی که آن را نمی‌شناسد بدون تغییر کار می‌کند.

عضو موفق با هشدار ثبت
{
  "asatspId": 105236,
  "status": 0,
  "issue": 1,
  "internalId": "INV-2001",
  "warnings": [
    "شماره اقتصادی خریدار با کد ملی 0012345678 وارد نشده بود و از پرونده‌ی مالیاتی او برداشته شد: شماره اقتصادی 00123456780001 (کارپوشه فعال)."
  ]
}

برای دیدن پرونده‌های مالیاتی خریدار پیش از صدور صورتحساب، یا انتخاب بین چند پرونده، سرویس جداگانه استعلام پرونده مالیاتی (/api/v2/tax-file-inquiry) را به کار ببرید.

کدهای خطای ویرایش صورتحساب

این کدها در پاسخ editInvoice و simple/editInvoice در errors[].code می‌آیند و در همهٔ آن‌ها چیزی ثبت نشده است. خطای ثبت صورتحساب (مثلاً خریدار اصلاحی که با مرجع یکی نیست، INVOICE_REFERRAL_BUYER_MISMATCH) با همان کد سامانه برمی‌گردد؛ خطاهای ساختار صورتحساب همان خطاهای /send با مسیر $.data… هستند.

codepathمعنا و اقدام
INVOICE_CORRECTION_CONFIRMATION_REQUIRED$تغییرات صورتحساب اصلاحی صادر می‌کند و تأیید نداشت؛ همان درخواست را همراه edit.confirmationToken یا با confirmCorrection: true دوباره بفرستید.
INVOICE_EDIT_CONFIRMATION_INVALID$.confirmationTokenتوکن معتبر نیست؛ همان مقدار پاسخ قبلی را بفرستید.
INVOICE_EDIT_CONFIRMATION_EXPIRED$.confirmationTokenمهلت ۱۵ دقیقه‌ای توکن تمام شده است؛ بدون توکن بفرستید تا تأیید تازه بگیرید.
INVOICE_EDIT_CONFIRMATION_STALE$.confirmationTokenصورتحساب پس از صدور توکن تغییر کرده است (مثلاً از پنل یا با درخواستی دیگر)؛ وضعیت را استعلام کنید و بدون توکن بفرستید.
INVOICE_EDIT_CONFIRMATION_MISMATCH$.confirmationTokenمحتوای درخواست با محتوایی که توکن برای آن صادر شده یکی نیست.
INVOICE_EDIT_FIELD_NOT_CORRECTABLE$.data.Header.inty، $.data.Header.inp، $.data.Body یا $.data.itemsنوع، الگو، شناسهٔ کالا/خدمت یا نرخ مالیات بر ارزش افزودهٔ اصلاحی با مرجع فرق دارد (نام فیلد در field)؛ صورتحساب را ابطال و صورتحساب جدید صادر کنید.
INVOICE_EDIT_SEND_IN_PROGRESS$.internalId یا $.taxIdصورتحساب در صف ارسال یا در انتظار پاسخ سامانهٔ مؤدیان است؛ پس از مشخص شدن نتیجه دوباره تلاش کنید.
INVOICE_EDIT_RESULT_PENDING$.internalId یا $.taxIdنتیجهٔ ثبت صورتحساب هنوز مشخص نیست؛ ابتدا وضعیت آن را استعلام کنید.
INVOICE_SEND_RESULT_UNKNOWN$صورتحساب ارسال شده و پاسخ آن هنوز نرسیده است؛ تا روشن شدن نتیجه ویرایش نمی‌شود.
INVOICE_EDIT_CANCELLED$.internalId یا $.taxIdصورتحساب ابطال شده است و ویرایش نمی‌شود؛ در صورت نیاز صورتحساب جدید ثبت کنید.
INVOICE_EDIT_CANCELLATION$.internalId یا $.taxIdصورتحساب ابطالی ویرایش نمی‌شود.
INVOICE_EDIT_NOT_CURRENT$.internalId یا $.taxIdصورتحساب نسخهٔ جاری خود نیست یا وضعیتش ویرایش را مجاز نمی‌کند.
INVOICE_EDIT_REFERENCE_NOT_ALLOWED$.internalId یا $.taxIdزنجیرهٔ صورتحساب اصلاح را مجاز نمی‌کند، مثلاً اصلاحیِ قبلی هنوز تأیید نشده یا ارجاع مؤثر دیگری روی آن هست؛ دلیل در message و کد آن در field. برای الگوی ۱۱ به‌جای این کد، کدهای EXCHANGE_ANNOUNCEMENT_* برمی‌گردد.
INVOICE_REFERENCE_STATUS_UNAVAILABLE، INVOICE_REFERENCE_STATUS_REFRESH_FAILED$.internalId یا $.taxIdوضعیت صورتحساب از کارپوشه دریافت نشد؛ کمی بعد دوباره تلاش کنید.
INVOICE_EDIT_DUPLICATE_REQUEST$.uuidبا این uuid قبلاً ویرایشی ثبت شده است (result: -2)؛ وضعیت را استعلام کنید و برای ویرایش تازه uuid تازه بفرستید.
INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE$خطای گذرای پایگاه داده؛ ویرایش انجام نشده است. پس از استعلام، دوباره بفرستید.
INVOICE_EDIT_INTERNAL_ERROR$ یا $.dataخطای داخلی؛ با traceId به پشتیبانی مراجعه کنید.

کدهای خطای صورتحساب ارجاعی (اصلاحی، ابطالی، برگشت از فروش)

پیش از ثبت صورتحساب ارجاعی در /send (ins برابر ۲، ۳ یا ۴)، مسیرهای مدل ساده (invoiceSubject برابر ۲، ۳ یا ۴) و cancelInvoice، وضعیت زنجیرهٔ صورتحساب مرجع مانند پنل از کارپوشه گرفته می‌شود: آخرین استعلامِ کمتر از ۲ ساعت مستقیم استفاده می‌شود، بین ۲ تا ۲۴ ساعت دوباره استعلام می‌شود (اگر کارپوشه پاسخ ندهد، همان آخرین استعلام مبناست) و بیش از ۲۴ ساعت یا بدون استعلام قبلی حتماً استعلام می‌شود. این کدها در errors[].code همان عضو می‌آیند و آن عضو ثبت نشده است.

codepathمعنا و اقدام
INVOICE_REFERENCE_ACTION_NOT_ALLOWED$.data[i].data.Header.irtaxid، $.data[i].sourceTaxId یا $.data[i].sourceInternalId، $.internalIdزنجیرهٔ صورتحساب مرجع این عملیات را مجاز نمی‌کند، مثلاً مرجع ابطال شده یا اصلاحیِ قبلی هنوز تأیید نشده است؛ دلیل در message و کد آن در field. برای الگوی ۱۱ به‌جای این کد، کدهای EXCHANGE_ANNOUNCEMENT_* برمی‌گردد.
INVOICE_REFERENCE_STATUS_UNAVAILABLEهمان مسیرهاوضعیت صورتحساب مرجع از کارپوشه دریافت نشد و چیزی ثبت نشده است؛ چند دقیقه بعد همان درخواست را با uuid تازه دوباره بفرستید.

برگشت از فروش (ins=4 و invoiceSubject=4)

طبق جدول ۱ دستورالعمل RC_IITP.IS_V7.9 (صفحه‌های ۱۴ تا ۱۸)، اقلام برگشت از فروش از صورتحساب مرجع می‌آیند: ردیف تازه اضافه نمی‌شود، ردیفی که کامل برگشت خورده حذف می‌شود و مقدار هیچ ردیفی از مرجع بیشتر نیست. بنابراین Body در /send (و items در مدل ساده) اقلام باقی‌مانده پس از برگشت است، نه مقدار برگشتی. مثلاً اگر از ۳ عدد، ۱ عدد برگشت بخورد، ردیف با am=2 فرستاده می‌شود.

  • irtaxid (یا sourceTaxId/sourceInternalId) باید آخرین صورتحساب ثبت‌شدهٔ زنجیره در سامانه مؤدیان باشد.
  • هر ردیف با ردیفی از مرجع که همان شناسه کالا/خدمت را دارد جفت می‌شود؛ اگر fee، vra یا bsrn فرستاده شود باید با همان ردیف مرجع یکی باشد. ردیف‌های هم‌شناسه به ترتیب مرجع جفت می‌شوند.
  • واحد، مبلغ واحد، نرخ مالیات بر ارزش افزوده، سایر مالیات‌ها، قرارداد حق‌العمل‌کاری و اطلاعات ارزی هر ردیف از مرجع می‌آید؛ مقدار (am)، تخفیف (dis) و شرح (sstt) از درخواست. تخفیف ردیفی که مقدارش کم نشده تغییر نمی‌کند.
  • اطلاعات خریدار در برگشت از فروش خارج از الگو است و از مرجع می‌آید: در /send فیلدهای tob، tinb، bid، bbc، bpn و sbc را در Header نفرستید. مسیرهای مدل ساده این فیلدها را خودشان از JSON ساخته‌شده حذف می‌کنند؛ مسیرهای نوع ۱ مانند /api/invoice/salesWithBuyerData همچنان شیء buyer را می‌پذیرند (باید همان خریدار مرجع باشد) و در مسیرهای نوع ۲ مانند /api/invoice/salesEndUser می‌توانید آن را حذف کنید. روش تسویه، cap/insp و پرداخت‌ها از درخواست خوانده می‌شوند.
  • برای برگشت همهٔ اقلام، صورتحساب ابطالی بفرستید (cancelInvoice یا ins=3).

ارسال اقلام برگشتی (returnRows: "returned")

اگر نرم‌افزار شما سند برگشت از فروش را با اقلام برگشتی نگه می‌دارد، در /send کنار internalId فیلد اختیاری returnRows را با مقدار returned بفرستید تا تطبیق با ردیف‌های مرجع و ساخت اقلام باقی‌مانده در معتمد آسا انجام شود. مقدار پیش‌فرض remaining همان رفتار بالاست و درخواست‌های فعلی تغییری نمی‌کنند. این فیلد فقط با Header.ins=4 پذیرفته می‌شود.

  • Body اقلام برگشتی سند شماست: sstid، مقدار برگشتی در am، و برای شناسایی دقیق ردیف، fee، vra و در صورت وجود bsrn همان ردیف فروش. dis تخفیفی است که همراه کالای برگشتی کم می‌شود؛ اگر نفرستید، تخفیف ردیف به نسبت مقدار باقی‌مانده حفظ می‌شود. جمع‌های Header مانند همیشه با همین Body کنترل می‌شوند.
  • irtaxid می‌تواند شماره مالیاتی هر صورتحساب ثبت‌شدهٔ زنجیره (مثلاً فروش اصلی) باشد؛ مرجع، آخرین صورتحساب ثبت‌شدهٔ همان زنجیره است.
  • اگر یک کالا/خدمت در مرجع چند ردیف با مبلغ واحد، نرخ یا تخفیفِ هر واحد متفاوت داشته باشد، ردیف با همین مشخصات پیدا می‌شود. اگر باز بیش از یک نوع ردیف بماند، آن عضو با INVOICE_RETURN_ROW_AMBIGUOUS رد می‌شود و حدس زده نمی‌شود. ردیف‌های کاملاً یکسان به ترتیب مرجع با هم برگشت می‌خورند.
  • ردیف‌های باقی‌مانده، مبالغ، مالیات‌ها و دیگر فیلدهای مالیاتی از ردیف‌های ثبت‌شدهٔ مرجع ساخته می‌شوند؛ اگر چیزی باقی نماند، INVOICE_RETURN_NEEDS_CANCELLATION برمی‌گردد.
codepathمعنا و اقدام
INVOICE_RETURN_REFERENCE_INVALID$.data[i].data.Header.irtaxid، $.data[i].sourceTaxId یا $.data[i].sourceInternalIdمرجع در صورتحساب‌های فعال کسب‌وکار یافت نشد، هنوز در حال ارسال است یا در سامانه مؤدیان ثبت نشده است.
INVOICE_RETURN_ROW_INVALID$.data[i].data.Body[j].<field> یا $.data[i].items[j].<field>ردیف با هیچ ردیف مرجع جفت نشد یا فیلدی را تغییر داده که در برگشت از فروش ثابت است؛ نام فیلد در field و مقدار مرجع در message می‌آید. مقدار بیشتر از مرجع معمولاً یعنی مقدار برگشتی به‌جای مقدار باقی‌مانده فرستاده شده است.
INVOICE_RETURN_NOTHING_RETURNED$.data[i].data.Body یا $.data[i].itemsمقدار هیچ ردیفی کمتر از مرجع نیست و ردیفی هم حذف نشده است.
INVOICE_RETURN_NEEDS_CANCELLATIONهمان مسیرهابا این برگشت چیزی از مرجع باقی نمی‌ماند؛ صورتحساب ابطالی بفرستید.
INVOICE_RETURN_ROW_AMBIGUOUS$.data[i].data.Body[j].sstidفقط با returnRows: "returned": این کالا/خدمت در مرجع چند ردیف با مبلغ، نرخ یا تخفیف متفاوت دارد و مشخص نیست برگشت از کدام است؛ fee، vra و dis ردیف برگشتی را مطابق همان ردیف بفرستید.
INVOICE_RETURN_ROWS_MODE_INVALID$.data[i].returnRowsreturnRows فقط remaining یا returned و فقط برای Header.ins=4 است.

نمونه پاسخ جزئی: یک ثبت موفق و یک خطا

Partial batch response
{
  "result": 1,
  "traceId": "d36131a5-11e0-402b-9b0b-4a921333c317",
  "message": "1 صورتحساب ثبت شد و 1 مورد دارای خطا بود.",
  "errors": [
    {
      "path": "$.data[1].data.Header.tbill",
      "message": "مجموع صورتحساب باید با جمع مقادیر متناظر در Body برابر باشد. مقدار صحیح: 5500000"
    }
  ],
  "data": [
    {
      "asatspId": 105234,
      "status": 0,
      "issue": 1,
      "internalId": "1000001"
    },
    {
      "status": 3,
      "error": [
        "$.data[1].data.Header.tbill: مجموع صورتحساب باید با جمع مقادیر متناظر در Body برابر باشد. مقدار صحیح: 5500000"
      ],
      "internalId": "1000002"
    }
  ]
}

نمونه رد کامل به‌دلیل عبور از سقف batch

Batch limit error
{
  "result": 0,
  "traceId": "17f35c78-58b2-4f8f-8d5d-5e1ea281c1af",
  "message": "ساختار کلی درخواست معتبر نیست. تعداد خطا: 1",
  "errors": [
    {
      "path": "$.data",
      "message": "آرایه data نمی‌تواند بیشتر از 250 صورتحساب داشته باشد."
    }
  ]
}

نمونه پاسخ موفق ثبت صورتحساب

Send success response
{
  "result": 1,
  "traceId": "5f1ca11c-56d0-4420-8f72-7d0ef41751f1",
  "message": "صورتحساب‌ها با موفقیت ثبت شدند.",
  "data": [
    {
      "asatspId": 105234,
      "status": 0,
      "issue": 1,
      "internalId": "1000001"
    },
    {
      "asatspId": 105235,
      "status": 0,
      "issue": 1,
      "internalId": "1000002"
    }
  ]
}
25نمونه‌ها

نمونه کد ثبت مشتری

cURL / register
curl -X POST "https://api-v2.asatsp.ir/api/register" \
  -H "Authorization: Bearer <AccessToken with v2.register>" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "type": 2,
    "fiscalId": "A1B2C3",
    "economicCode": "12345678901234",
    "name": "شرکت نمونه",
    "nationalCode": "10100000000",
    "mobile": "09120000000",
    "autoSend": true,
    "valueAddedNotCalled": true
  }'
JavaScript fetch / register
const response = await fetch("https://api-v2.asatsp.ir/api/register", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <AccessToken with v2.register>",
    "Content-Type": "application/json; charset=utf-8"
  },
  body: JSON.stringify({
    type: 2,
    fiscalId: "A1B2C3",
    economicCode: "12345678901234",
    name: "شرکت نمونه",
    nationalCode: "10100000000",
    mobile: "09120000000",
    autoSend: true,
    valueAddedNotCalled: true
  })
});

const result = await response.json();
if (![1, 2, 3].includes(result.result)) {
  // 0، -1 یا -2: کد خطا در result.error و توضیح در result.message
  throw new Error((result.error || "") + " " + result.message);
}
const auth = result.data && result.data.serviceAuth;
if (auth && auth.client_secret) {
  // فقط در پاسخی می‌آید که اعتبارنامه در آن ساخته شده است؛ همین حالا با تابع ذخیره‌سازی خودتان در محل امن رمزهای سرور نگه دارید.
  await secretStore.save(auth.client_id, auth.client_secret);
}
C# HttpClient / register
// .NET 6 یا بالاتر
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

string json = JsonSerializer.Serialize(new
{
    type = 2,
    fiscalId = "A1B2C3",
    economicCode = "12345678901234",
    name = "شرکت نمونه",
    nationalCode = "10100000000",
    mobile = "09120000000",
    autoSend = true,
    valueAddedNotCalled = true
});

using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<AccessToken with v2.register>");

using var response = await client.PostAsync(
    "https://api-v2.asatsp.ir/api/register",
    new StringContent(json, Encoding.UTF8, "application/json"));

using JsonDocument answer = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
JsonElement root = answer.RootElement;
int result = root.GetProperty("result").GetInt32();
if (result is not (1 or 2 or 3))
{
    // 0، -1 یا -2: کد خطا در error و توضیح در message
    throw new InvalidOperationException(root.GetProperty("message").GetString());
}
if (root.TryGetProperty("data", out JsonElement data) && data.ValueKind == JsonValueKind.Object &&
    data.TryGetProperty("serviceAuth", out JsonElement auth) && auth.ValueKind == JsonValueKind.Object &&
    auth.TryGetProperty("client_secret", out JsonElement secret) && secret.ValueKind == JsonValueKind.String)
{
    // فقط در پاسخی می‌آید که اعتبارنامه در آن ساخته شده است؛ همین حالا با تابع ذخیره‌سازی خودتان در محل امن رمزهای سرور نگه دارید.
    SaveSecret(auth.GetProperty("client_id").GetString(), secret.GetString());
}
Python requests / register
import requests

payload = {
    "type": 2,
    "fiscalId": "A1B2C3",
    "economicCode": "12345678901234",
    "name": "شرکت نمونه",
    "nationalCode": "10100000000",
    "mobile": "09120000000",
    "autoSend": True,
    "valueAddedNotCalled": True,
}

response = requests.post(
    "https://api-v2.asatsp.ir/api/register",
    headers={"Authorization": "Bearer <AccessToken with v2.register>"},
    json=payload,
    timeout=30,
)

response.raise_for_status()          # 403 محدودیت IP و 404 نشانی ناموجود
result = response.json()
if result.get("result") not in (1, 2, 3):
    # 0، -1 یا -2: کد خطا در error و توضیح در message
    raise RuntimeError(str(result.get("error")) + " " + str(result.get("message")))
auth = (result.get("data") or {}).get("serviceAuth") or {}
if auth.get("client_secret"):
    # فقط در پاسخی می‌آید که اعتبارنامه در آن ساخته شده است؛ همین حالا با تابع ذخیره‌سازی خودتان در محل امن رمزهای سرور نگه دارید.
    save_secret(auth["client_id"], auth["client_secret"])
PHP cURL / register
$payload = [
    "type" => 2,
    "fiscalId" => "A1B2C3",
    "economicCode" => "12345678901234",
    "name" => "شرکت نمونه",
    "nationalCode" => "10100000000",
    "mobile" => "09120000000",
    "autoSend" => true,
    "valueAddedNotCalled" => true,
];

$ch = curl_init("https://api-v2.asatsp.ir/api/register");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer <AccessToken with v2.register>",
        "Content-Type: application/json; charset=utf-8",
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
    CURLOPT_TIMEOUT => 60,
]);

$text = curl_exec($ch);
if ($text === false) {
    throw new RuntimeException('خطای ارتباط: ' . curl_error($ch));
}
curl_close($ch);

$result = json_decode($text, true);
if (!in_array($result['result'] ?? null, [1, 2, 3], true)) {
    // 0، -1 یا -2: کد خطا در error و توضیح در message
    throw new RuntimeException(($result['error'] ?? '') . ' ' . ($result['message'] ?? ''));
}
$auth = $result['data']['serviceAuth'] ?? [];
if (!empty($auth['client_secret'])) {
    // فقط در پاسخی می‌آید که اعتبارنامه در آن ساخته شده است؛ همین حالا با تابع ذخیره‌سازی خودتان در محل امن رمزهای سرور نگه دارید.
    save_secret($auth['client_id'], $auth['client_secret']);
}

نمونه پاسخ سرویس ثبت مشتری

Register response
{
  "result": 1,
  "traceId": "6f9d0c76-1e78-4a61-9ec5-c63e38b49e3f",
  "message": "مشتری با موفقیت ایجاد شد.",
  "data": {
    "companyId": 1250,
    "fiscalId": "A1B2C3",
    "economicCode": "12345678901234",
    "valueAddedNotCalled": true,
    "taxFileState": "active",
    "taxFileStatus": "ACTIVE",
    "taxFileStatusTitle": "فعال",
    "taxFileMessage": "کارپوشه مؤدی در سامانه مؤدیان فعال است.",
    "customerApiKey": null,
    "serviceAuth": {
      "credential_type": "customer",
      "client_id": "v2-customer-1250",
      "client_secret": "shown-only-once",
      "allowed_scopes": "v2.invoice.cancel v2.invoice.read v2.invoice.send v2.lookup.read",
      "token_endpoint": "/api/auth/v2/token",
      "expires_in": 3600,
      "legacy_api_key_sunset_utc": "2026-12-01T20:30:00Z"
    },
    "created": true,
    "updated": false
  }
}
client_secret فقط در پاسخی می‌آید که اعتبارنامه مشتری در آن ساخته شده است. در فراخوانی‌های بعدی همان کسب‌وکار، و وقتی کسب‌وکار پیش‌تر اعتبارنامه داشته است، مقدار آن null است. آن را همان لحظه در محل امن ذخیره کنید؛ اگر از دست برود، مدیر کسب‌وکار باید از پنل («تنظیمات ← اتصال API v2») Client Secret تازه بسازد.
وضعیت کارپوشه مؤدی: برای شناسه حافظه عملیاتی (sandBox نبودن)، پاسخ موفق وضعیت کارپوشه مشتری در سامانه مؤدیان را هم برمی‌گرداند: taxFileState یکی از active، notActive، notFound یا unavailable (استعلام انجام نشد)، همراه taxFileStatus (مقدار سازمان مثل TEMPORARY_UNAUTHORIZE)، taxFileStatusTitle و taxFileMessage. این فیلدها فقط اطلاع‌رسانی‌اند و ثبت مشتری را رد نمی‌کنند؛ اما تا کارپوشه فعال نشود، صورتحساب‌های این مشتری به سامانه مؤدیان ارسال نمی‌شوند و هنگام ارسال با علت روشن به پیش‌نویس برمی‌گردند. برای شناسه آزمایشی این فیلدها null هستند.
  • اگر شناسه حافظه معتبر نباشد، result: 0 با error: "FISCAL_ID_INVALID" برمی‌گردد.
  • اگر استعلام شناسه حافظه از سامانه مؤدیان انجام نشود (قطعی یا کندی سرویس سازمان)، result: 0 با error: "FISCAL_ID_INQUIRY_UNAVAILABLE" و پیام «استعلام شناسه حافظه مالیاتی از سامانه مؤدیان انجام نشد؛ کمی بعد دوباره تلاش کنید.» برمی‌گردد؛ این پاسخ به معنای نامعتبر بودن شناسه نیست و همان درخواست را بعداً دوباره بفرستید.
26نمونه‌ها

نمونه کد ثبت صورتحساب

نمونه زیر ساختار یک درخواست گروهی دو عضوی را نشان می‌دهد. برای کوتاه ماندن نمونه، عضو دوم می‌تواند با همان ساختار عضو اول و با internalId و inno متفاوت ساخته شود. نمونه‌های cURL، C#، Python و PHP فایل invoice-batch.json را می‌خوانند؛ آن را از زبانه JSON بسازید.

اگر دست‌کم یک عضو ثبت شود، result برابر 1 است، حتی وقتی عضوهای دیگر خطا دارند. نتیجه هر صورتحساب را از data[i] بخوانید: status برابر 3 یعنی همان عضو ثبت نشده و علت آن در error[] آمده است. این نمونه برای آزمون است: indatim را زمان واقعی صدور به میلی‌ثانیه بگذارید و نمونه را ابتدا با sandBox: true بفرستید.
Group JSON / tax invoice registration
{
  "uuid": "9f806c1a-2c7e-4d1d-a3fa-2c65fd8c3210",
  "data": [
    {
      "internalId": "1000001",
      "send": true,
      "fiscalId": "PRD123",
      "sandBox": false,
      "description": "فروش نقدی نمونه",
      "data": {
        "Header": {
          "indatim": 1782940800000,
          "inty": 1,
          "inp": 1,
          "ins": 1,
          "inno": "A000000001",
          "tins": "12345678901234",
          "tob": 2,
          "tinb": "10987654321000",
          "bpc": "1234567890",
          "setm": 1,
          "tprdis": 10000000,
          "tdis": 0,
          "tadis": 10000000,
          "tvam": 1000000,
          "todam": 0,
          "tbill": 11000000,
          "cap": 11000000,
          "insp": 0,
          "tvop": 1000000
        },
        "Body": [
          {
            "sstid": "1234567890123",
            "sstt": "کالای نمونه",
            "mu": "1627",
            "am": 2,
            "fee": 5000000,
            "prdis": 10000000,
            "dis": 0,
            "adis": 10000000,
            "vra": 10,
            "vam": 1000000,
            "odam": 0,
            "olam": 0,
            "tsstam": 11000000
          }
        ],
        "Payments": [
          {
            "pdt": 1782940800000,
            "pmt": 3,
            "pv": 11000000
          }
        ]
      }
    },
    {
      "internalId": "1000002",
      "send": false,
      "fiscalId": "SND123",
      "sandBox": true,
      "description": "ثبت بدون صف ارسال خودکار",
      "data": {
        "Header": {
          "indatim": 1782940800000,
          "inty": 1,
          "inp": 1,
          "ins": 1,
          "inno": "A000000002",
          "tins": "12345678901234",
          "tob": 2,
          "tinb": "10987654321000",
          "bpc": "1234567890",
          "setm": 1,
          "tprdis": 5000000,
          "tdis": 0,
          "tadis": 5000000,
          "tvam": 500000,
          "todam": 0,
          "tbill": 5500000,
          "cap": 5500000,
          "insp": 0,
          "tvop": 500000
        },
        "Body": [
          {
            "sstid": "1234567890123",
            "sstt": "خدمت نمونه",
            "mu": "1627",
            "am": 1,
            "fee": 5000000,
            "prdis": 5000000,
            "dis": 0,
            "adis": 5000000,
            "vra": 10,
            "vam": 500000,
            "odam": 0,
            "olam": 0,
            "tsstam": 5500000
          }
        ],
        "Payments": [
          {
            "pdt": 1782940800000,
            "pmt": 2,
            "pv": 5500000
          }
        ]
      }
    }
  ]
}
cURL / register tax invoice
curl -X POST "https://api-v2.asatsp.ir/api/invoice/send" \
  -H "Authorization: Bearer <AccessToken with v2.invoice.send>" \
  -H "Content-Type: application/json; charset=utf-8" \
  --data-binary "@invoice-batch.json"
JavaScript fetch / register tax invoice
// Node.js 19 یا بالاتر (یا داخل تابع async)؛ این کد را فقط روی سرور اجرا کنید، چون توکن نباید به مرورگر برسد.
// invoiceDto همان شیء data (Header، Body و Payments) در زبانه JSON است.
const payload = {
  uuid: crypto.randomUUID(),
  data: [
    {
      internalId: "1000001",
      send: true,
      fiscalId: "SND123",
      sandBox: true,
      description: "فروش نقدی نمونه",
      data: invoiceDto
    }
  ]
};

const response = await fetch("https://api-v2.asatsp.ir/api/invoice/send", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <AccessToken with v2.invoice.send>",
    "Content-Type": "application/json; charset=utf-8"
  },
  body: JSON.stringify(payload)
});

const result = await response.json();
if (result.result === -2) {
  // این uuid پیش‌تر به کار رفته است؛ پیش از ارسال دوباره، صورتحساب‌ها را با inquiryInternalId استعلام کنید.
} else if (result.result !== 1) {
  console.table(result.errors || []);          // هیچ صورتحسابی ثبت نشد
}
for (const item of result.data || []) {
  if (item.status === 3) {
    console.error(item.internalId, item.error); // این عضو ثبت نشد؛ اصلاح کنید و با uuid تازه بفرستید
  } else {
    // item.asatspId و item.internalId را ذخیره کنید
  }
}
C# HttpClient / register tax invoice
// .NET 6 یا بالاتر
using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

string json = File.ReadAllText("invoice-batch.json");   // همان زبانه JSON، ذخیره‌شده در فایل

using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(120) };
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<AccessToken with v2.invoice.send>");

using var response = await client.PostAsync(
    "https://api-v2.asatsp.ir/api/invoice/send",
    new StringContent(json, Encoding.UTF8, "application/json"));

using JsonDocument answer = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
JsonElement root = answer.RootElement;
if (root.GetProperty("result").GetInt32() != 1 &&
    root.TryGetProperty("errors", out JsonElement errors) && errors.ValueKind == JsonValueKind.Array)
{
    // هیچ صورتحسابی ثبت نشد
    foreach (JsonElement error in errors.EnumerateArray())
        Console.WriteLine(error.GetProperty("path").GetString() + ": " + error.GetProperty("message").GetString());
}
if (root.TryGetProperty("data", out JsonElement data) && data.ValueKind == JsonValueKind.Array)
{
    foreach (JsonElement item in data.EnumerateArray())
    {
        string internalId = item.GetProperty("internalId").GetString();
        if (item.GetProperty("status").GetInt32() == 3)
            Console.WriteLine("ثبت نشد: " + internalId + " " + item.GetProperty("error").GetRawText());
        else
            Console.WriteLine("ثبت شد: " + internalId + " asatspId=" + item.GetProperty("asatspId").GetInt64());
    }
}
Python requests / register tax invoice
import json
import requests

with open("invoice-batch.json", "r", encoding="utf-8") as file:
    payload = json.load(file)

response = requests.post(
    "https://api-v2.asatsp.ir/api/invoice/send",
    headers={"Authorization": "Bearer <AccessToken with v2.invoice.send>"},
    json=payload,
    timeout=60,
)

response.raise_for_status()          # 403 محدودیت IP و 404 نشانی ناموجود
result = response.json()
if result.get("result") != 1:
    for error in result.get("errors") or []:
        print(error.get("path"), error.get("message"))
for item in result.get("data") or []:
    if item.get("status") == 3:
        print("ثبت نشد:", item.get("internalId"), item.get("error"))
    else:
        print("ثبت شد:", item.get("internalId"), item.get("asatspId"))
PHP cURL / register tax invoice
$payload = file_get_contents("invoice-batch.json");

$ch = curl_init("https://api-v2.asatsp.ir/api/invoice/send");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer <AccessToken with v2.invoice.send>",
        "Content-Type: application/json; charset=utf-8",
    ],
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_TIMEOUT => 60,
]);

$text = curl_exec($ch);
if ($text === false) {
    throw new RuntimeException('خطای ارتباط: ' . curl_error($ch));
}
curl_close($ch);

$result = json_decode($text, true);
if (($result['result'] ?? null) !== 1) {
    // هیچ صورتحسابی ثبت نشد
    foreach ($result['errors'] ?? [] as $error) {
        echo $error['path'], ': ', $error['message'], PHP_EOL;
    }
}
foreach ($result['data'] ?? [] as $item) {
    if (($item['status'] ?? null) === 3) {
        echo 'ثبت نشد: ', $item['internalId'], ' ', json_encode($item['error'] ?? [], JSON_UNESCAPED_UNICODE), PHP_EOL;
    } else {
        echo 'ثبت شد: ', $item['internalId'], ' asatspId=', $item['asatspId'], PHP_EOL;
    }
}
26Aنمونه‌ها

راهنمای آزمایش پیش از اتصال عملیاتی

پیش از ارسال صورتحساب واقعی، رفتار نرم‌افزار خود را در محیط آزمایشی (Sandbox) با موارد زیر بسنجید. نشانی و اعتبارنامه در دو محیط یکی است؛ فقط sandBox: true را در هر صورتحساب بفرستید و کسب‌وکار باید شناسه حافظه مالیاتی آزمایشی داشته باشد (حافظه مالیاتی و Sandbox). صورتحساب آزمایشی اثر مالیاتی ندارد.

مورد آزمایشچه بفرستیدپاسخ درست
۱. ثبت موفقنمونه شروع سریعresult: 1، و برای صورتحساب status: 0 همراه taxId.
۲. پیگیری تا پایاناستعلام با همان internalId هر چند دقیقه یک بارstatus از 0 به 1 و سپس 2 (موفق) یا 3 (خطا) می‌رسد. در وضعیت 2، refrenceNumber را ذخیره کنید.
۳. تکرار همان درخواستهمان بدنه با همان uuidresult: -2 با کد INVOICE_DUPLICATE_REQUEST در مسیر $.uuid. صورتحساب دوم ساخته نمی‌شود.
۴. خطای اعتبارسنجییک قلم بدون unitPriceresult: 0، خطا در errors[] با path دقیق، و برای صورتحساب status: 3. هیچ چیز ثبت نمی‌شود.
۵. ثبت گروهی با یک عضو نادرستدو صورتحساب، دومی با qty: -1result: 1: عضو اول ثبت می‌شود و عضو دوم با status: 3 و خطاهایش برمی‌گردد. فقط عضو دوم را اصلاح و با uuid تازه دوباره بفرستید.
۶. توکن نامعتبریک توکن ساختگیدر /api/v2/*: HTTP 401 با کد unauthorized. در سرویس‌های ثبت /api/invoice/*: HTTP 200 با result: -1 و خطا در مسیر headers.Authorization. نرم‌افزار شما باید توکن تازه بگیرد و درخواست را یک بار تکرار کند.
۷. قطع ارتباط پس از ارسالاتصال را پیش از رسیدن پاسخ قطع کنیدنرم‌افزار شما باید پیش از ارسال دوباره، وضعیت را با internalId استعلام کند و فقط اگر صورتحساب ثبت نشده بود، با uuid تازه بفرستد.

پاسخ‌های واقعی محیط آزمایشی

پاسخ‌های زیر از اجرای همین موارد در محیط آزمایشی برداشته شده‌اند؛ فقط شناسه‌ها با شما فرق دارند.

مورد ۳: تکرار همان uuid
{
  "result": -2,
  "traceId": "11148b37-3404-4ede-9d51-b184a1b5205a",
  "message": "ساختار کلی درخواست یا uuid معتبر نیست. تعداد خطا: 1",
  "errors": [
    {
      "code": "INVOICE_DUPLICATE_REQUEST",
      "path": "$.uuid",
      "message": "uuid ارسالی قبلاً برای این شرکت ثبت شده است."
    }
  ],
  "data": null
}
مورد ۵: ثبت گروهی با یک عضو نادرست
{
  "result": 1,
  "traceId": "600ecc41-cef1-451b-9a7c-147055a8a9e4",
  "message": "1 صورتحساب ثبت شد و 1 مورد دارای خطا بود.",
  "errors": [
    { "path": "$.data[1].items[0].qty", "message": "تعداد/مقدار qty باید بزرگ‌تر از صفر باشد." },
    { "path": "$.data[1].items[0].discount", "message": "مبلغ تخفیف نمی‌تواند از مبلغ قبل از تخفیف بیشتر باشد." }
  ],
  "data": [
    {
      "asatspId": 12020176,
      "taxId": "A1172Z0512500000F43531",
      "fiscalId": "A1172Z",
      "sandBox": true,
      "environment": "Sandbox",
      "status": 0,
      "issue": 1,
      "internalId": "QS-20261117001308-A"
    },
    {
      "status": 3,
      "error": [
        "$.data[1].items[0].qty: تعداد/مقدار qty باید بزرگ‌تر از صفر باشد.",
        "$.data[1].items[0].discount: مبلغ تخفیف نمی‌تواند از مبلغ قبل از تخفیف بیشتر باشد."
      ],
      "internalId": "QS-20261117001308-B"
    }
  ]
}

در این نمونه، برای کوتاه شدن، چند فیلد پاسخ عضو اول (مثل fiscalMemoryId و environmentTitle) حذف شده است. فهرست کامل فیلدهای پاسخ در ثبت با JSON سازمان آمده است.

استعلام پرونده مالیاتی محیط آزمایشی ندارد: هر فراخوانی آن از سامانه مؤدیان واقعی پاسخ می‌گیرد و هزینه سرویس از کیف پول کم می‌شود. آن را فقط با شناسه‌های واقعی و به تعداد لازم آزمایش کنید.
27نمونه‌ها

چک‌لیست پیش از ثبت یا ارسال

کنترلنتیجه مورد انتظار
هدر احراز هویتAuthorization: Bearer <AccessToken> ارسال شده باشد. در دوره مهاجرت، Customer API Key legacy هم تا تاریخ sunset پذیرفته می‌شود.
شناسه فروشندهHeader.tins با شماره اقتصادی کسب‌وکار احراز هویت‌شده برابر باشد.
یکتایی درخواستبرای هر درخواست جدید یک uuid تازه تولید شده باشد و همه internalIdها برای شرکت احراز هویت‌شده یکتا باشند.
ساختار صورتحسابهر عضو data[] دارای Header باشد و، جز صورتحساب ابطالی (ins=3)، Body با دست‌کم یک قلم داشته باشد. در صورتحساب ابطالی Body را نفرستید.
ماده ۹برای صورتحساب خارج از مهلت ۱۵ روز، Header.insr=1 و Header.indati2m معتبر را هم‌زمان ارسال کنید. صورتحساب عادی و کلاینت قدیمی به این دو فیلد نیاز ندارند.
جمع ردیف‌هاadis، tsstam و جمع‌های Header دقیقاً با Body برابر باشند.
تسویه و پرداختcap + insp <= tbill و مجموع پرداخت‌ها از tbill بیشتر نباشد.
الگوهای خاصفیلدهای اختصاصی ارز، طلا، پیمانکاری، قبوض، پرواز، صادرات، بارنامه، فرآورده‌های نفتی، اوراق بهادار مبتنی بر کالا، بیمه و فروش زنجیره تکمیل شده باشند.
الگوی ۱۱ (بورس کالا)adis (در مدل ساده amountAfterDiscount) دقیقاً برابر ارزش معامله در اعلامیه فروش بورس و Header.tadis برابر آن باشد؛ fee/unitPrice، prdis و dis ارسال نشده باشند. جزئیات در مبلغ واحد در الگوی ۱۱.
نگه‌داری شناسه‌هاuuid، internalId، traceId و در پاسخ موفق asatspId را ذخیره کنید.
28مرجع

تاریخچه تغییرات

تغییراتی که برای نرم‌افزار متصل اهمیت دارد، از جدیدترین. این تغییرات اتصال‌های موجود را از کار نمی‌اندازد. هر جا رفتار نادرستی اصلاح شده و پاسخ با گذشته فرق کرده است، در همان ردیف آمده است.

تاریختغییر
۱۴۰۵/۰۸/۲۷پیام خطای داخلی سیستم، مانند خطای اتصال شبکه یا پایگاه داده که متن انگلیسی دارد، دیگر در پاسخ نمی‌آید. به‌جای آن پیام فارسی سرویس همراه کد پیگیری برمی‌گردد. ساختار پاسخ و کدهای خطا تغییر نکرده است. در فایل OpenAPI، کدهای خطای هر سرویس، از جمله سرویس‌های کارپوشه مالیاتی، کامل فهرست شده است.
۱۴۰۵/۰۸/۲۶اصلاح چند رفتار نادرست:
  • صورتحساب اصلاحی، ابطالی یا برگشت از فروشی که fiscalId ندارد، با حافظه مالیاتی صورتحساب مرجع ثبت می‌شود، اگر آن حافظه در همان محیط درخواست باشد. پیش‌تر اگر صورتحساب مرجع روی حافظه‌ای جز حافظه پیش‌فرض بود، رد می‌شد.
  • inquiryNo و inquiryNos فقط صورتحسابی را پیدا می‌کنند که شماره آن کامل برابر شماره فرستاده‌شده باشد. پیش‌تر بخشی از شماره هم صورتحساب دیگری را برمی‌گرداند.
  • sendInvoice در هر درخواست حداکثر ۵۰۰ شناسه می‌پذیرد. اگر ارسال برخی شناسه‌ها انجام نشود، پاسخ در data وضعیت شناسه‌هایی را هم دارد که در صف قرار گرفتند.
  • در به‌روزرسانی کسب‌وکار با /api/register، اگر type، nationalCode یا autoSend فرستاده نشود، مقدار ثبت‌شده تغییر نمی‌کند. پیش‌تر نوع به ۰ تغییر می‌کرد، کد ملی پاک می‌شد و ارسال خودکار روشن می‌شد.
  • رد شدن به‌دلیل محدودیت IP در client-credentials پاسخ 403 با کد IP_NOT_ALLOWED است، مانند مسیر توکن (پیش‌تر 401). خطای احراز هویت در /api/Currency و /api/InvoiceItemUnit مانند سرویس‌های دیگر result: -1 است (پیش‌تر 0).
  • در کارپوشه مالیاتی، پاسخ 403 علت واقعی رد شدن را می‌گوید. خروجی Excel بدون پارامتر دیگر خطای 500 نمی‌دهد و خطای آماده نشدن فایل کد جداگانه tax_workspace_excel_unavailable دارد.
  • خطای ثبت ابطالی به‌دلیل نتیجه نامشخص ارسال قبلی یا خطای گذرای پایگاه داده، کد INVOICE_SEND_RESULT_UNKNOWN یا INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE دارد. زمان ۱۰ رقمی (ثانیه) در همه بررسی‌ها ثانیه خوانده می‌شود.
  • برای کارگزاران: تحویل اعتبارنامه‌ای که باطل یا غیرفعال شده، پاسخ 409 با کد credentials_withdrawn می‌گیرد و تحویل جلسه باز می‌ماند. در رویدادها، credentialsAvailable فقط وقتی true است که تحویل اعتبارنامه برای همکار فعال باشد. هشدار وبهوک، چه هنگام باز شدن و چه هنگام بسته شدن، فقط در پنل و اعلان‌ها می‌آید.
۱۴۰۵/۰۸/۲۶امنیت اعتبارنامه: اعتبارنامه باطل‌شده یا غیرفعال با ثبت مشتری یا مسیر client-credentials دوباره فعال نمی‌شود؛ پاسخ ثبت مشتری در serviceAuth فیلد تازه active را دارد و client-credentials در این حالت 409 با کد client_revoked برمی‌گرداند. ثبت دوباره کسب‌وکار شماره ورود کاربران آن را تغییر نمی‌دهد (امنیت و دسترسی).
۱۴۰۵/۰۸/۲۶مهلت کلید ثابت قدیمی (Customer API Key) و API نسخه ۱ پایان ۱۰ آذر ۱۴۰۵ به وقت تهران است و تمدید نمی‌شود. پیش از آن به Access Token مهاجرت کنید (احراز هویت).
۱۴۰۵/۰۸/۲۶سرویس تازه استعلام پرونده مالیاتی (POST /api/v2/tax-file-inquiry). در مستندات: شروع سریع با نمونه کامل به پنج زبان، قواعد مشترک، راهنمای آزمایش، فایل OpenAPI و مجموعه Postman و همین تاریخچه.
۱۴۰۵/۰۸/۱۷محدودیت IP اعتبارنامه بر همه درخواست‌های API نسخه ۲ اعمال می‌شود. در مسیرهای نوع ۲ مدل ساده، خریداری که فرستاده شود روی صورتحساب می‌ماند. سرویس خواندن شناسه کالا/خدمت (GET /api/v2/stuffid/{code}) اضافه شد.
۱۴۰۵/۰۸/۲۳صورتحساب ابطالی (ins: 3) فقط با فیلدهای سرآمد خودش (indatim، inno، tins و irtaxid) پذیرفته می‌شود؛ اگر setm نیاید، روش تسویه صورتحساب مرجع به کار می‌رود.
۱۴۰۵/۰۸/۱۲صورتحساب اصلاحی، برگشت از فروش یا ابطالی که فیلد خارج از الگوی خود را هم بفرستد، به‌جای رد شدن، بدون آن فیلدها و با هشدار در warnings پذیرفته می‌شود.
۱۴۰۵/۰۸/۱۱هشدار واحد کالا در مدل ساده و کدهای جدا برای تکرار uuid و internalId. cap و insp طبق دستورالعمل نسخه ۷.۹ محاسبه می‌شوند. کلید ثابت همکار (Partner API Key) دیگر پذیرفته نمی‌شود.
۱۴۰۵/۰۷/۳۰هشدارهای ثبت در فیلد warnings پاسخ. بررسی پرونده مالیاتی خریدار حقیقی هنگام ثبت (فقط برای کسب‌وکاری که سرویس را فعال کرده باشد) با کدهای BUYER_TAX_FILE_* و فیلد اختیاری checkTypeTwoBuyers. exr تا ۸ رقم اعشار پذیرفته می‌شود.
۱۴۰۵/۰۷/۲۹واحد اندازه‌گیری ناشناخته با فهرست کدهای مجاز رد می‌شود (GET /api/InvoiceItemUnit/codes).
۱۴۰۵/۰۷/۲۸برگشت از فروش در /api/invoice/send با ردیف‌های کالای برگشتی.
۱۴۰۵/۰۷/۲۶برای کارگزاران: لینک موقت ثبت‌نام، رویدادها و تحویل اعتبارنامه، و گزارش‌های همکاری. شناسه یکتای حافظه مالیاتی با API.
۱۴۰۵/۰۷/۲۵خواندن فهرست‌های کارپوشه مالیاتی با JSON. پاسخ ثبت مشتری وضعیت کارپوشه را هم برمی‌گرداند.
۱۴۰۵/۰۷/۲۱ثبت پیش‌فاکتور با proforma: true؛ استعلام آن وضعیت 7 را برمی‌گرداند.
۱۴۰۵/۰۷/۱۳ویرایش و اصلاح صورتحساب با editInvoice و simple/editInvoice.
۱۴۰۵/۰۶/۲۵ثبت پرداخت صورتحساب ارسال‌شده در کارپوشه.
۱۴۰۵/۰۶/۲۴الگوی بورس اوراق بهادار مبتنی بر کالا (الگوی ۱۱) و وضعیت اعلامیه فروش بورس.