هر آنچه نرمافزار شما برای ثبت صورتحساب در سامانهٔ مؤدیان از راه معتمد آسا لازم دارد: مسیر اتصال مشتری مستقیم و کارگزار، توکن، ثبت گروهی با JSON سازمان یا مدل ساده، پیگیری وضعیت و کارپوشهٔ مالیاتی؛ با شماتیک و نمونهکد آماده.
نتیجهای پیدا نشدبرای «» بخشی پیدا نشد. عبارت کوتاهتر یا نام فیلد دیگری را امتحان کنید.
00شروع
قرارداد عمومی API
API نسخه ۲ صورتحساب را در قالب JSON سازمان امور مالیاتی یا در مدل ساده میگیرد، آن را پیش از ثبت با قواعد دستورالعمل سامانه مؤدیان بررسی میکند، ثبت میکند و به سامانه مؤدیان میفرستد. هر خطا با پیامی روشن، مسیر فیلد و شناسه پیگیری برمیگردد و جزئیات فنی سرور در پاسخ نمیآید.
Base URLhttps://api-v2.asatsp.ir
Content-Typeapplication/json; charset=utf-8
AuthenticationAuthorization: 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;
پس از موفق شدن این آزمایش، همین کد را برای محیط عملیاتی به کار ببرید: 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 و مجموعه آماده درخواستها را دریافت کنید. این فایلها با همین مستندات بهروز میشوند.
توصیف API به استاندارد OpenAPI 3.0: همه مسیرها، فیلدهای درخواست و پاسخ، scopeها و کدهای خطا. آن را در Swagger Editor، Postman یا Insomnia باز کنید، یا با ابزارهایی مثل OpenAPI Generator برای زبان نرمافزار خود کد اتصال بسازید.
مجموعه Postman با همه درخواستها و نمونه بدنهها. فقط متغیرهای client_id و client_secret را پر کنید؛ درخواست «دریافت توکن» مقدار توکن را خودش در متغیر access_token میگذارد و درخواستهای دیگر آن را به کار میبرند.
نمونه کامل توکن، ثبت و پیگیری به زبانهای cURL، JavaScript، C#، Python و PHP که در محیط آزمایشی اجرا و آزموده شدهاند.
توصیف OpenAPI برای ساختن کد و آزمایش سریع است. قواعد کامل هر فیلد، مثل الزام شرطی فیلدها در هر الگو، در همین مستندات و در اعتبارسنجی JSON آمده است.
01شروع
مسیر اتصال: مشتری مستقیم یا کارگزار
پیش از شروع، مسیر اتصال خود را انتخاب کنید. هر دو مسیر از همین API استفاده میکنند و تفاوت آنها در محل دریافت اعتبارنامه و تعداد کسبوکارهایی است که نرمافزار شما برایشان صورتحساب میفرستد.
مسیر ۱
مشتری مستقیم
نرمافزار یک کسبوکار (حسابداری، فروشگاه یا ERP خودش) که صورتحسابهای همان کسبوکار را میفرستد.
اعتبارنامه از پنلمدیر کسبوکار در «تنظیمات › اتصال API v2» آن را صادر میکند: v2-customer-{شناسه} و client_secret.
گرفتن توکنPOST /api/auth/v2/token؛ توکن ۶۰ دقیقه اعتبار دارد.
ثبت صورتحساب/api/invoice/send با JSON سازمان، یا مسیرهای مدل ساده؛ ۱ تا ۲۵۰ صورتحساب در هر درخواست.
پیگیری نتیجهبا internalId، شماره یا taxId از مسیرهای inquiry*.
فیلدی را که path نام برده اصلاح کنید و فقط همان را با uuid تازه دوباره بفرستید (رفتار ثبت گروهی).
پاسخ نرسید (timeout یا قطع ارتباط)
معلوم نیست ثبت شده یا نه.
اول با internalId استعلام کنید؛ فقط ثبتنشدهها را دوباره بفرستید.
استعلام status: 1 میدهد
صورتحساب در صف ارسال است یا سامانه مؤدیان هنوز پاسخ نداده است.
چند دقیقه بعد دوباره استعلام کنید و صورتحساب را دوباره نفرستید.
استعلام status: 0 میدهد
صورتحساب ثبت شده ولی هنوز در صف ارسال قرار نگرفته است. صورتحسابی که با send: false یا با ارسال خودکار خاموش ثبت شده باشد، تا ارسال دستی در همین وضعیت میماند.
اگر صورتحساب با send: false یا با ارسال خودکار خاموش ثبت شده است، آن را با /api/invoice/sendInvoice بفرستید؛ ثبت دوباره لازم نیست. در غیر این صورت چند دقیقه بعد دوباره استعلام کنید.
صورتحسابی که سامانهٔ مؤدیان پذیرفته باید تغییر کند
محل دیدن خطای هر مرحله، و جایی که کارگزار همه آنها را یکجا میبیند، در محل دیدن خطاها آمده است.
03احراز هویت و امنیت
احراز هویت
هر درخواست با یک Access Token کوتاهمدت فرستاده میشود. توکن را نرمافزار شما با client_id و client_secret (الگوی client_credentials) میگیرد، تا نزدیک پایان ۶۰ دقیقه برای همهٔ درخواستها به کار میبرد و بعد توکن تازه میگیرد. کلید ثابت قدیمی فقط تا پایان دورهٔ مهاجرت پذیرفته میشود.
گرفتن و بهکاربردن توکنیک توکن برای همهٔ درخواستهای ۶۰ دقیقه؛ نه یک توکن برای هر درخواست.
سرور شما ← سرویسهای APIهر درخواست با همان توکنAuthorization: Bearer <AccessToken>
سرویسهای API ← سرور شماپاسختوکن نامعتبر یا scope ناکافی: در /api/invoice/* و /api/register مقدار result: -1، در /api/v2/* پاسخ 401 یا 403
سرور شمانزدیک پایان اعتبارتوکن تازه بگیرید و جایگزین کنید
درخواستپاسخکار درون همان سرور
محل دریافت Client ID و Client Secret:
وارد پنل کنترل معتمد آسا شوید، از منوی «کسبوکارها» کسبوکار موردنظر را انتخاب کنید و در «تنظیمات ← اتصال API v2» اعتبارنامه را صادر کنید. مسیر مستقیم هر کسبوکار نیز /apps/taxpayer-management/setting/{companyId}/api-v2 است. مقدار Client Secret فقط هنگام صدور یا چرخش نمایش داده میشود؛ همان لحظه آن را در Secret Manager سرور ذخیره کنید. اعتبارنامهٔ همکار (کارگزار) از «پیشخوان همکاری › سلامت اتصال» صادر میشود (اعتبارنامه همکار و اعتبارنامه مشتری).
توکن کوتاهمدت 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" دیگر پذیرفته نمیشود؛ اعتبارنامهٔ همکار فقط از «پیشخوان همکاری» صادر میشود. برای راهاندازیهای جدید از پنل کنترل استفاده کنید.
اگر برای این کسبوکار پیشتر اعتبارنامه ساخته شده باشد (مثلاً هنگام ثبت با /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 استفاده میشود.
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 منتقل کنید (احراز هویت).
کارگزار نرمافزاری است (حسابداری، فروشگاهی یا ERP) که مشتریان خودش را در معتمد آسا ثبت میکند و صورتحساب هر کدام را از راه API نسخه ۲ میفرستد. همهٔ کار کارگزار در همین بخش است: دو شماتیک اتصال، راهاندازی، دو اعتبارنامه، مهاجرت از کلید ثابت، جای هر خطا، و پایش در «پیشخوان همکاری».
فقط روش این راهنما:
کارگزار فقط با اعتبارنامهٔ همکار و اعتبارنامهٔ هر مشتری کار میکند. Partner API Key دیگر در هیچ مسیری پذیرفته نمیشود و پاسخ ثبت مشتری هم کلید ثابت (customerApiKey) نمیدهد. Customer API Keyهایی که پیشتر گرفتهاید فقط تا پایان ۱۰ آذر ۱۴۰۵ به وقت تهران (2026-12-01T20:30:00Z) کار میکنند و این مهلت تمدید نمیشود؛ پس از آن هر درخواستی که با آنها بیاید با خطای احراز هویت رد میشود (در مسیرهای صورتحساب result: -1) و ثبت نمیشود. راه مهاجرت در مهاجرت از کلید ثابت آمده است.
شماتیک اتصال کارگزار
اتصال خود کارگزار یک بار انجام میشود: ثبت همکاری، صدور اعتبارنامهٔ همکار و یک آزمایش. از آن پس هر مشتری با یکی از دو مسیر اتصال مشتری اضافه میشود.
اتصال کارگزار به معتمد آسایک بار برای هر کارگزار.
کارگزارسرور نرمافزار شما
پشتیبانی معتمد آسا«همکاران API»
پنل معتمد آسا«پیشخوان همکاری»
API نسخه ۲api-v2.asatsp.ir
کارگزار ← پشتیبانیدرخواست همکاریکسبوکار کارگزار در معتمد آسا ثبت شده است
پشتیبانیثبت در «همکاران API»دسترسیها و دامنههای مجاز بازگشت
کارگزار ← APIآزمایش اتصالGET /api/v2/partner/profile · POST /api/v2/partner/webhook/test
درخواستپاسخکار درون همان بخش
شماتیک اتصال مشتری از طریق کارگزار
هر مشتری از یکی از دو مسیر به معتمد آسا وصل میشود. نتیجهٔ هر دو یکی است: کسبوکار مشتری با حافظهٔ مالیاتیاش ثبت میشود و کارگزار اعتبارنامهٔ همان مشتری را برای ارسال صورتحساب دارد.
مسیر
کی
مؤدی چه میکند
الف. ثبت مستقیم با /api/register
کارگزار اطلاعات مشتری و شناسهٔ حافظهٔ مالیاتی را دارد و کسبوکار پیشتر در معتمد آسا ثبت نشده است.
کاری لازم نیست.
ب. لینک موقت ثبتنام
پاسخ ثبت مستقیم business_registered_elsewhere است، یا میخواهید خود مالک با تأیید سامانهٔ مؤدیان اجازه بدهد.
با موبایل وارد میشود و مالکیت را با رمز سامانهٔ مؤدیان تأیید میکند.
مسیر الف: ثبت مستقیم مشتریاز ثبت مشتری تا پاسخ سازمان به نخستین صورتحساب.
کارگزارسرور نرمافزار شما
API نسخه ۲معتمد آسا
صف ارسالمعتمد آسا
سامانهٔ مؤدیانسازمان امور مالیاتی
کارگزار ← APIثبت مشتری با توکن همکارPOST /api/register
API ← سامانهٔ مؤدیانبررسی حافظهٔ مالیاتی و کارپوشهکسبوکار مشتری ساخته یا بهروز میشود
API ← کارگزاراعتبارنامهٔ مشتریserviceAuth: v2-customer-{شناسه} + client_secretفقط وقتی کسبوکار پیشتر اعتبارنامه نداشته باشد؛ در Secret Manager نگه دارید
کارگزار ← APIتوکن مشتری، سپس ارسال صورتحسابPOST /api/invoice/send
API ← کارگزارنتیجهٔ هر صورتحساب در همان پاسخdata[] · errors[]ثبتشده، یا ردشده پیش از ثبت با مسیر فیلد
API ← صف ارسالصورتحساب ثبتشده به صف میرودبا send یا تنظیم ارسال خودکار کسبوکار
صف ارسال ← سامانهٔ مؤدیانارسال به سامانهٔ مؤدیان
سامانهٔ مؤدیان ← صف ارسالپاسخ سازمانپذیرفته، یا رد با کد خطای سازمان
کارگزار ← APIپیگیری نتیجهPOST /api/invoice/inquiry*یا در «پیشخوان همکاری»
درخواستپاسخ
مسیر ب: لینک موقت ثبتنام با رضایت مالککارگزار هیچ رمز یا اطلاعات هویتی را خودش جمع نمیکند.
کارگزارسرور نرمافزار شما
API نسخه ۲معتمد آسا
مؤدیصفحهٔ ثبتنام معتمد آسا
سامانهٔ مؤدیانسازمان امور مالیاتی
کارگزار ← APIساخت لینک با توکن همکارPOST /api/v2/partner/onboarding-sessionsبا requestCredentials: true، اگر اعتبارنامهٔ مشتری را میخواهید
API ← کارگزارلینک موقت201 · url
کارگزار ← مؤدیرساندن لینک به مؤدیمثل یک رمز؛ لینک به نخستین کاربری که وارد شود گره میخورد
مؤدی ← سامانهٔ مؤدیانورود با موبایل و تأیید مالکیتبا رمزی که سامانهٔ مؤدیان به موبایل ثبتشده در کارپوشه میفرستد
مؤدیساخت پنل و شناسهٔ یکتای حافظهو رضایت برای تحویل اعتبارنامه
مؤدی ← کارگزاربازگشت به نشانی کارگزارreturnUrl?session_id=…&status=completed
API ← کارگزاروبهوک یا فهرست رویدادهاonboarding.session.business_ready
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 یا مسیرهای مدل ساده بفرستید. توکن هر کسبوکار فقط برای همان کسبوکار کار میکند.
ثبت، ارسال، ابطال و پیگیری صورتحسابهای همان مشتری
serviceAuth نخستین ثبت؛ تحویل در لینک ثبتنام (فقط برای کسبوکاری که هنوز اعتبارنامه ندارد)؛ «اتصال API v2» پنل مالک؛ تا پایان مهلت، با Customer API Key همان مشتری
توکن همکار برای ثبت صورتحساب پذیرفته نمیشود و توکن مشتری برای مسیرهای همکار؛ هر کدام را برای کار خودش بگیرید. هر دو client_secret را مثل رمز، فقط در Secret Manager سرور نگه دارید. هر کسبوکار فقط یک اعتبارنامه مشتری دارد؛ اگر Client Secret آن را بچرخانید، مقدار قبلی برای همه نرمافزارهایی که با همین اعتبارنامه کار میکنند، از جمله نرمافزار خود مالک، از کار میافتد.
مهاجرت از کلید ثابت
Partner API Key دیگر در هیچ مسیری پذیرفته نمیشود. Customer API Keyهایی که پیشتر برای مشتریان گرفتهاید تا پایان مهلت کار میکنند و پاسخها هدرهای Deprecation، Sunset و Warning دارند. پیش از پایان مهلت، این چهار کار را انجام دهید:
اعتبارنامهٔ همکار را از «پیشخوان همکاری › سلامت اتصال» صادر کنید (قدم دوم راهاندازی) و ثبت مشتری و مسیرهای همکار را با توکن آن بفرستید.
برای هر مشتری، با 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 است.
هر client_id و client_secret را کنار شناسهٔ کسبوکار در Secret Manager نگه دارید.
در کد، بهجای کلید ثابت، توکن هر اعتبارنامه را در Authorization: Bearer بفرستید. بدنهٔ هیچ درخواستی عوض نمیشود.
دریافت اعتبارنامهٔ یک مشتری با Customer API Key آن (فقط تا پایان مهلت)
تا وقتی کسبوکاری از شما در هفت روز گذشته بدون Access Token صورتحساب فرستاده باشد، «پیشخوان همکاری › نمای کلی» یافتهٔ «کلید ثابت قدیمی مشتریان تا پایان … کار میکند» را با تعداد آن کسبوکارها نشان میدهد. پس از پایان مهلت، این مسیر بسته میشود و Client Secret تازه مشتری را فقط مالک کسبوکار در «اتصال API v2» پنل خود میسازد. لینک ثبتنام فقط برای کسبوکاری اعتبارنامه میسازد که هنوز اعتبارنامه ندارد.
همین فهرست را از API هم میگیرید: پاسخ GET /api/v2/partner/reports/overview (و /reports/health) در data.legacyKeys برای هر کسبوکاری که در هفت روز گذشته بدون Access Token درخواست فرستاده است، این موارد را دارد:
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 کنار گذاشته میشود.
هشدارهای «پیشخوان همکاری» برای تیم فنی در تلگرام روشن است.
نرمافزار همکار با یک درخواست، برای مؤدی لینک موقت ثبتنام میسازد و مؤدی را به آن میفرستد. مؤدی در صفحه معتمد آسا با موبایل وارد میشود، مالکیت کسبوکار را با رمزی که سامانه مؤدیان به موبایل ثبتشده در کارپوشه میفرستد تأیید میکند، پنل ساخته میشود و شناسه یکتای حافظه مالیاتی هم گرفته میشود. در پایان، مؤدی به نشانی بازگشت همکار برمیگردد و همکار نتیجه را از وبهوک، فهرست رویدادها یا خواندن جلسه میگیرد. همکار هیچ رمز یا اطلاعات هویتی را خودش جمع نمیکند.
پیشنیاز:
کسبوکار همکار باید در فهرست همکاران معتمد آسا ثبت و فعال باشد و «لینک موقت ثبتنام» برایش روشن باشد. دامنههای مجاز نشانی بازگشت را پشتیبانی معتمد آسا ثبت میکند. نشانی وبهوک را کاربر با دسترسی کامل در «پیشخوان همکاری › سلامت اتصال» تنظیم میکند و کلید امضای آن همانجا ساخته و فقط یک بار نمایش داده میشود. همه درخواستها با اعتبارنامه همکار و 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
/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
تنظیمات همکار: دسترسیها، دامنههای مجاز، وبهوک و سقفها.
همه فیلدها اختیاریاند. با economicCode مؤدی فقط همان کسبوکار را میتواند ثبت کند؛ با nationalId (۱۰، ۱۱ یا ۱۲ رقم) پروندههای او فهرست میشود؛ بدون هیچکدام، مؤدی خودش شماره را وارد میکند.
returnUrl باید https و روی یکی از دامنههای مجاز همکار باشد. اگر خالی بماند، نشانی بازگشت پیشفرض همکار به کار میرود.
اعتبار لینک از ۱۰ دقیقه تا ۷ روز است و پیشفرض آن را پشتیبانی برای همکار تعیین میکند. وقتی مؤدی وارد شود، لینک دستکم یک ساعت دیگر باز میماند.
idempotencyKey (۸ تا ۶۴ نویسه، یا سرآیند Idempotency-Key): درخواست تکراری همان جلسه را برمیگرداند. اگر لینک هنوز باز نشده باشد، لینک تازه میدهد و لینک قبلی باطل میشود. همان کلید با اطلاعات دیگر پاسخ 409 idempotency_conflict میگیرد.
mobile فقط در مرحله ورود پیشنهاد میشود. ورود و تأیید مالکیت همیشه با خود مؤدی است.
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 میآید.
امضا روی بایتهای بدنه همانطور که رسیده ساخته میشود؛ بدنه را پیش از بررسی امضا پردازش یا دوباره سریال نکنید. برای آزمودن کد خود این مقدارها را به کار ببرید: کلید 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= است. زمان این نمونه عمداً قدیمی است؛ هنگام آزمودن با آن، بررسی پنجدقیقهای را کنار بگذارید.
ظرف ۱۰ ثانیه با کد 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 میگیرد.
خطاها
HTTP
code
معنا
400
validation_failed
فیلدی نادرست است؛ نام فیلد در fieldErrors میآید (مثلاً returnUrl بیرون از دامنههای مجاز).
اعتبارنامه API کسبوکار باطل یا غیرفعال شده است و تحویل داده نمیشود. تحویل این جلسه باز میماند و پس از آنکه مالک اعتبارنامه را در پنل دوباره صادر کند، ممکن میشود.
429
rate_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 میآید. اعداد دوره جاری (و فصل قبل تا ۱۵ روز پس از پایان آن) حداکثر دو دقیقه و دورههای قدیمیتر حداکثر ۳۰ دقیقه پس از هر تغییر بهروز میشوند.
بازهٔ گزارش
پارامتر
مقدار
نمونه
period
season (پیشفرض)، month، year یا range
period=month
key
فصل، ماه یا سال شمسی؛ بدون آن، فصل جاری
1405-3، 1405-07، 1405
from / to
برای range: روز شمسی، حداکثر ۳۶۶ روز
from=1405/07/01&to=1405/07/26
بازهای که هنوز شروع نشده یا پیش از ۱۳۹۸ است، پاسخ 400 period_invalid میگیرد. روز هر صورتحساب، تاریخ خود صورتحساب است، نه زمان ارسال آن.
Endpointها
Method
Endpoint
کاربرد
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/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 — بخشی از پاسخ
معتمد آسا هر پنج دقیقه این شاخصها را برای هر همکار میسنجد. وقتی هشداری باز یا بسته میشود، کاربران کسبوکار همکار در مرکز اعلان پنل و تلگرام (و طبق تنظیم هر کاربر، پیامک) باخبر میشوند و رویداد آن به وبهوک و فهرست رویدادها هم فرستاده میشود.
هشدار
باز میشود وقتی
بسته میشود وقتی
error_rate
از صورتحسابهای API سه ساعت گذشته که نتیجه گرفتهاند (دستکم ۲۰ صورتحساب)، ۲۰٪ یا بیشتر رد شده باشد.
سهم خطا زیر ۱۰٪ برگردد.
rejected_requests
در سه ساعت گذشته دستکم ۳ صورتحساب (غیر از Sandbox و ارسال تکراری) پیش از ثبت رد شده باشد. متن هشدار پرتکرارترین علت را هم میگوید.
سه ساعت هیچ صورتحسابی پیش از ثبت رد نشود.
result_delay
دستکم ۱۰ صورتحساب API بیش از دو ساعت منتظر پاسخ سامانهٔ مؤدیان مانده باشد.
کمتر از ۳ صورتحساب منتظر بماند.
webhook
رویدادی دو بار یا بیشتر بیپاسخ موفق مانده باشد، یا تلاشهای رویدادی در ساعت گذشته تمام شده باشد.
تحویل دوباره موفق شود. (این هشدار فقط در پنل و اعلانها میآید، نه در خود وبهوک.)
{ "month": "1405-07", "title": "مهر 1405" }؛ سه روز اول هر ماه، یک بار.
خطاها
HTTP
code
شرح
400
period_invalid / validation_failed
بازه، ماه یا فیلتر معتبر نیست؛ نام پارامتر در fieldErrors میآید.
401 / 403
unauthorized / forbidden
توکن نیست یا توکن همکار با v2.register نیست.
403
business_not_yours
businessId از کسبوکارهای این همکار نیست.
404
partner_not_found
این اعتبارنامه به همکار ثبتشده در «همکاران API» تعلق ندارد.
همین گزارشها در پنل معتمد آسا، بخش «پیشخوان همکاری»، با نمودار و خروجی Excel (از جمله گزارش ماهانهٔ چندبرگه) در دسترس کاربران کسبوکار همکار است.
08ثبت و پیگیری صورتحساب
ثبت یا بهروزرسانی مشتری
POST/api/register
این سرویس با Access Token دارای scope v2.register فراخوانی میشود و پس از اعتبارسنجی شناسه حافظه مالیاتی، مشتری را ایجاد یا بهروزرسانی میکند. توکن را با اعتبارنامهٔ همکار بگیرید؛ Partner API Key قدیمی دیگر پذیرفته نمیشود (راهنمای کارگزاران). customerApiKey در پاسخ برای سازگاری میماند ولی همیشه null است و اعتبارنامهٔ مشتری فقط در serviceAuth میآید.
فیلد
نوع
الزامی
توضیح
type
number
بله
1 حقیقی، 2 حقوقی، 3 مشارکت مدنی، 4 اتباع غیر ایرانی. در ثبت مشتری تازه این فیلد را بفرستید؛ مقدار آن بررسی نمیشود و اگر فرستاده نشود، صفر ذخیره میشود. در بهروزرسانی مشتری، ارسالنشدن این فیلد مقدار فعلی را تغییر نمیدهد.
fiscalId
string(6)
بله
شناسه حافظه مالیاتی مشتری که باید در همان محیط درخواست اخذ و قابل استعلام باشد.
sandBox
boolean
خیر
true برای ثبت و استعلام در Sandbox؛ مقدار پیشفرض false و به معنی محیط عملیاتی است.
economicCode
string
بله
شماره اقتصادی مشتری؛ با شناسه حافظه مالیاتی کنترل میشود.
name
string
خیر
نام شخص یا شرکت.
nationalCode
string
خیر
کد ملی یا شناسه ملی. در بهروزرسانی مشتری، ارسالنشدن این فیلد (یا مقدار null) کد ملی ثبتشده را تغییر نمیدهد؛ مقدار ارسالشده، حتی رشته خالی، جای مقدار قبلی را میگیرد.
mobile
string
خیر
شماره تلفن همراه مالک. فقط وقتی همین درخواست کسبوکار را تازه ثبت میکند، بهعنوان شماره ورود او به پنل ثبت میشود. برای کسبوکاری که پیشتر ثبت شده، شماره ورود کاربران از این سرویس تغییر نمیکند و message پاسخ این را میگوید؛ هر کاربر شماره خود را در پنل با کد تأیید عوض میکند.
autoSend
boolean
خیر
تنظیم عمومی ارسال خودکار کسبوکار. اگر در پنل برای «API نسخه ۲» تنظیم جداگانهای ثبت شده باشد، همان تنظیم مبناست. در ثبت مشتری تازه، نبودن این فیلد یعنی true؛ در بهروزرسانی مشتری، ارسالنشدن آن مقدار فعلی را تغییر نمیدهد.
valueAddedNotCalled
boolean
خیر
معادل گزینه «مشمول فراخوان مالیات بر ارزش افزوده نیست» در پنل است. با مقدار 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):
code
path
معنا
ARTICLE9_FEATURE_DISABLED
.insr
قابلیت صورتحساب موضوع ماده ۹ برای این کسبوکار فعال نیست.
ARTICLE9_REGISTER_WITHOUT_SEND_RULE
.indati2m
indati2m فقط همراه 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
هنگام ارسال
مهلت ارسال صورتحساب گذشته است و ماده ۹ برای آن فرستاده نشده است.
تاریخها و شناسههای نمونههای این صفحه فقط قالب را نشان میدهند و صورتحسابی که با تاریخ نمونهها فرستاده شود، خارج از مهلت ۱۵ روزه ارسال است. پیش از ارسال، 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/send
fee خارج از الگوست؛ ارسال نکنید. اگر ارسال شود باید عدد صحیح غیرمنفی باشد (مقدار اعشاری یا منفی خطا میگیرد)؛ سپس نادیده گرفته میشود و ذخیره نمیشود.
adis الزامی: عدد صحیح بزرگتر از صفر برابر ارزش معامله در اعلامیه فروش بورس؛ از fee یا prdis محاسبه نمیشود. Header.tadis برابر آن است.
adis و am عیناً؛ fee، prdis و dis ارسال نمیشوند.
مدل ساده: /api/invoice/commoditySecurities و /api/invoice/simple/type/1/template/11
unitPrice فقط در نبود 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] پیدا کنید. ابطال، برگشت از فروش و سایر اعضای درخواست گروهی تحت تأثیر قرار نمیگیرند.
نمونه کامل درخواست الگوی بورس اوراق بهادار مبتنی بر کالا
در این نمونه 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 خارج از الگو هستند و نباید ارسال شوند.
نمونه اصلاحی الگوی بورس اوراق بهادار مبتنی بر کالا
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 شرکت، شناسه یا اطلاعات صورتحسابهای قبلی را تغییر نمیدهد.
فیلدهای درخواست
فیلد
نوع
الزام
قاعده
fiscalId
string(6)
اختیاری
شناسه یکتای ششکاراکتری حافظه مالیاتی؛ باید متعلق به همان کسبوکار، فعال و با محیط درخواست سازگار باشد. در صورت ارسال، همان شناسه روی Invoice تثبیت میشود.
sandBox
boolean
اختیاری
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 هم همان محیط مرجع را نشان دهد. در غیر این صورت صورتحساب ثبت نمیشود.
این پیامها عین پیامهای 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 کلاینت را کنترل کنید.
مقدار result
result: 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 نادیده گرفته نمیشود و در صورت ارسال باید کد واقعی شعبه خریدار با دقیقاً ۴ رقم باشد.
قاعده تکرار امن درخواست
uuid را برای هر درخواست جدید یکتا تولید کنید و internalId هر صورتحساب را ثابت و یکتا نگه دارید.
اگر پاسخ شامل نتیجه جزئی بود، اعضای دارای status: 3 را اصلاح کنید؛ اعضای موفق را دوباره نفرستید.
اگر result: 0 دریافت شد، هیچ عضوی ثبت نشده است؛ خطاهای ریشه یا تمام اعضای ناموفق را بررسی کنید.
اگر timeout، قطع ارتباط یا خطای اجرایی رخ داد، ابتدا با Endpointهای استعلام، وضعیت تکتک internalIdها را بررسی کنید.
فقط صورتحسابهای ثبتنشده را با 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 سازمان
no
Header.inno
dateTime
Header.indatim
invoiceSubject
Header.ins
sourceTaxId / sourceInternalId
Header.irtaxid
settlement
Header.setm
payment
Header.cap
contractCode
Header.crn
billNo
Header.billid
tax17
Header.tax17
cottageNo
Header.cdcn
cottageDate
Header.cdcd
saleAnnNo
Header.asn
saleAnnDate
Header.asd
insPolicyNo
Header.in
extInsPolicyNo
Header.an
declarationNo
Header.scln
officeCode
Header.scc
buyer.type
Header.tob
buyer.economicCode
Header.tinb
buyer.nationalCode
Header.bid
buyer.zipCode
Header.bpc
buyer.branchCode
Header.bbc
buyer.passportNumber
Header.bpn
items[].stuffId
Body[].sstid
items[].description
Body[].sstt
items[].unit
Body[].mu
items[].qty
Body[].am
items[].unitPrice
Body[].fee
items[].discount
Body[].dis
items[].vatRate
Body[].vra
items[].otherTaxDescription
Body[].odt
items[].otherTaxRate
Body[].odr
items[].govTaxDescription
Body[].olt
items[].govTaxRate
Body[].olr
items[].contractNo
Body[].bsrn
items[].currencyCode
Body[].cut
items[].amountCurrency
Body[].cfee
items[].currencyRate
Body[].exr
items[].currencyValue
Body[].sscv
items[].currencyPurchaseRate
Body[].cpr
items[].vatBaseAmount
Body[].sovat (الگوی ۲) یا Body[].vba (الگوی ۹)
items[].netWeight
Body[].nw
items[].wage
Body[].consfee
items[].profit
Body[].spro
items[].commission
Body[].bros
items[].carat
Body[].cui
payments[].type
Payments[].pmt
payments[].dateTime
Payments[].pdt
payments[].price
Payments[].pv
payments[].traceNo
Payments[].trn
payments[].cardNo
Payments[].pcn
payments[].payerNationalCode
Payments[].pid
payments[].terminalNumber
Payments[].trmn
payments[].acquirerNumber
Payments[].acn
payments[].switchNumber
Payments[].iinn
قرارداد کامل اطلاعات خریدار (buyer)
شیء buyer در هر عضو data قرار میگیرد. نام فیلدها را مطابق جدول زیر ارسال کنید. همه شناسهها و شمارههای تماس باید از نوع JSON string باشند تا صفر ابتدای مقدار حذف نشود.
فیلد
نوع
الزام
قالب و توضیح
type
number
خیر؛ پیشفرض 1
1 حقیقی، 2 حقوقی، 3 مشارکت مدنی، 4 اتباع غیر ایرانی. برای جلوگیری از برداشت نادرست، ارسال صریح آن توصیه میشود.
nationalCode
string
شرطی
فقط رقم؛ در قرارداد ورودی 5 تا 14 رقم. برای شخص حقیقی ایرانی کد ملی معتبر 10 رقمی و برای شخص حقوقی شناسه ملی 11 رقمی ارسال شود. در صورت نداشتن economicCode الزامی است.
economicCode
string
برای نوع 2 الزامی
فقط رقم، 11 تا 14 رقم. حداقل یکی از nationalCode یا economicCode باید موجود باشد.
zipCode
string
خیر
کد پستی 10 رقمی؛ بدون خط تیره یا فاصله.
name
string
خیر
نام شخص یا عنوان خریدار. حداکثر ظرفیت ذخیرهسازی 4000 کاراکتر است.
mobile
string
خیر
شماره همراه ایران با قالب پیشنهادی 09xxxxxxxxx و 11 رقم. مقدار معتبر به همین قالب نرمال میشود.
شماره تلفن ثابت همراه پیششماره؛ الگوی عددی جداگانهای در endpoint اعمال نمیشود و حداکثر ظرفیت ذخیرهسازی 1024 کاراکتر است.
branchCode
number
خیر
کد شعبه خریدار بهصورت عدد صحیح.
passportNumber
string
شرطی
شماره گذرنامه خریدار غیرایرانی که کد فراگیر ندارد؛ حداکثر ۹ حرف و رقم لاتین. فقط با type=4 در الگوی فروش ارز (template=2) پذیرفته میشود و بهجای nationalCode بهعنوان header.bpn ارسال میشود.
فیلدهای mobile، address و phone اطلاعات تکمیلی هستند و جایگزین شناسههای هویتی خریدار نمیشوند. برای خریدار حقوقی، economicCode حتی در صورت ارسال nationalCode همچنان الزامی است.
هر قلم آرایه items کالا یا خدمت را با فیلدهای زیر معرفی میکند. مبالغ، تخفیف و مالیاتهای قلم در فیلدهای صورتحساب در مدل ساده و فیلدهای هر الگو در جدول «فیلدهای اختصاصی هر الگو» آمدهاند.
فیلد
نوع
الزام
قالب و توضیح
items[].internalId
string
خیر
کد یا شناسه کالا/خدمت در سامانه مبدأ شما، حداکثر ۲۵۴ کاراکتر. API کالا/خدمت را با این کد شناسایی یا ایجاد میکند و مقدار را بهعنوان کد داخلی آن ذخیره میکند. برای حفظ صفرهای ابتدایی باید بهصورت JSON string ارسال شود. رفتار کد تکراری در کالا/خدمتِ از قبل ثبتشده آمده است.
items[].description
string
خیر
شرح همین قلم روی صورتحساب. همین متن بهعنوان شرح کالا/خدمت (Body[].sstt) به سامانه مؤدیان میرود و نام کالا/خدمت در پنل هم میشود. سامانه مؤدیان حداکثر ۴۰۰ کاراکتر میپذیرد و بیش از آن کوتاه میشود.
items[].unit
string
بله، جز الگوی فروش ارز (template=2)
کد رسمی واحد اندازهگیری، یعنی مقدار code از GET /api/InvoiceItemUnit/codes؛ برای «عدد» "1627" و برای «کیلوگرم» "164". همین کد در Body[].mu به سامانه مؤدیان میرود. جزئیات در واحد اندازهگیری در مدل ساده.
items[].stuffId
string
بله، مگر از 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 را هم میپذیرد. مقدار به این ترتیب خوانده میشود:
کد رسمی یا نام واحد؛
اگر هیچکدام نبود، شناسه داخلی واحد. در این حالت صورتحساب ثبت میشود و هشداری با کد رسمی همان واحد در 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.
مقادیر شمارشی مدل ساده
فیلد
مقادیر مجاز
نکته
invoiceSubject
1 اصلی، 2 اصلاحی، 3 ابطالی، 4 برگشت از فروش
برای موضوعهای غیر اصلی، ارسال sourceInternalId یا sourceTaxId الزامی است. در برگشت از فروش، items اقلام باقیمانده پس از برگشت است (برگشت از فروش).
isArticle9
true یا false (اختیاری)
در حالت true، فیلد invoiceRegistrationDateTime اجباری است؛ حذف فیلد یا false رفتار قبلی را حفظ میکند.
invoiceRegistrationDateTime
Unix Time میلیثانیهای، حداکثر ۱۳ رقم
تاریخ و زمان ثبت صورتحساب موضوع ماده ۹؛ با تاریخ صدور dateTime متفاوت است.
settlement
1 نقدی، 2 نسیه، 3 نقدی/نسیه
در حالت 3، مقدار payment سهم نقدی تسویه است.
buyer.type
1 حقیقی، 2 حقوقی، 3 مشارکت مدنی، 4 اتباع غیر ایرانی
برای خریدار حقوقی، economicCode الزامی است.
payments[].type
1 چک، 2 تهاتر، 3 وجه نقد، 4 کارتخوان (POS)، 5 درگاه پرداخت اینترنتی، 6 کارتبهکارت، 7 انتقال به حساب، 8 سایر
این مقدار به Payments[].pmt نگاشت میشود. برای پرداخت کارتخوانی نوع 4، شماره پذیرنده، پایانه و کارت الزامی است.
فیلدهای اختصاصی هر الگو
الگو
فیلدهای ساده
توضیح
inp=1 فروش
declarationNo, officeCode
اختیاری و فقط برای صورتحساب نوع ۱: شماره پروانه گمرکی (header.scln، حداکثر 14 رقم) و کد گمرک محل اظهار (header.scc، دقیقاً 5 رقم).
نرخ خرید ارز باید کوچکتر از نرخ فروش ارز باشد. declarationNo و officeCode مثل الگوی ۱. خریدار غیرایرانی فاقد کد فراگیر با buyer.type=4 و buyer.passportNumber ثبت میشود.
inp=3 طلا، جواهر و پلاتین
items[].wage, profit, commission, carat
اجرت ساخت، سود فروشنده و حقالعمل الزامی و غیرمنفی هستند.
inp=4 پیمانکاری
contractCode
شناسه یکتای ثبت قرارداد پیمانکاری، 12 رقم.
inp=5 قبوض خدماتی
billNo
شناسه قبض یا شماره اشتراک بهرهبردار، حداکثر 19 رقم.
اگر تاریخ کوتاژ ارسال شود، شماره کوتاژ هم الزامی است. officeCode (کد گمرک محل اظهار، header.scc) اختیاری و دقیقاً 5 رقم است؛ شماره پروانه گمرکی در این الگو خارج از الگوست. نرخ مالیات بر ارزش افزوده (vatRate) در این الگو ۰ است و نرخ بیشتر از صفر رد میشود.
inp=8 بارنامه
shipmentInfo
شماره بارنامه، مبدأ/مقصد، فرستنده/گیرنده، نوع حمل، ناوگان و وزن کل کنترل میشوند. driverIdCode (شماره ملی یا کد فراگیر اتباع غیرایرانی راننده، header.did) در حمل جادهای transportType=1 الزامی است و در هر حال باید 10 رقم (شماره ملی) یا 12 رقم (کد فراگیر) باشد؛ شناسه ملی 11 رقمی اشخاص حقوقی پذیرفته نمیشود. کشور و شهر با کدهای جدول کدینگ کشورها و شهرهای دستورالعمل (پیوستهای ۹-۴ و ۹-۵) ارسال میشوند؛ کد ایران 033 است (نه 364) و برای ایران شهر الزامی است، مثلاً تهران 284 و تبریز 12.
inp=9 فرآوردههای نفتی پالایش و پخش
فیلدهای عمومی کالا/خدمت و مالیات، items[].vatBaseAmount
vatBaseAmount مبلغ پایه مالیات بر ارزش افزوده (body[].vba) است؛ اگر بزرگتر از صفر باشد، مالیات ردیف از همین مبلغ محاسبه میشود و در غیر این صورت مبلغ بعد از تخفیف مبناست.
شماره اعلامیه فروش باید عددی باشد و تاریخ اعلامیه الزامی است. تاریخ تقویمی بدون جابهجایی روز به 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) در این الگو ۰ است و نرخ بیشتر از صفر رد میشود.
1 شماره ملی، 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 را حذف کنید؛ مبلغ واحد نمایشی از همین مبلغ محاسبه میشود (جدول مبالغ الگوی ۱۱).
برای ابطال، 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/sendInvoice
v2.invoice.send
{ "internalIds": ["INV-10001"] }
صورتحسابهای ثبتشده بهصورت دستی در صف ارسال به سازمان امور مالیاتی قرار میگیرند. برای هر internalId، آخرین صورتحساب زنجیره آن در نظر گرفته میشود؛ یعنی اگر برای آن اصلاحی، ابطالی یا برگشت از فروش ثبت شده باشد (حتی ارسالنشده)، همان آخرین صورتحساب در صورت ارسالنشده بودن در صف ارسال قرار میگیرد و اگر قبلاً ارسال شده باشد فقط وضعیت آن برمیگردد. اگر حتی یک شناسه خطا بگیرد، پاسخ result: 0 است و خطای آن شناسه در errors میآید. شناسههای سالم همان درخواست در صف ارسال قرار میگیرند و وضعیت آنها در data همین پاسخ برمیگردد؛ اگر هیچ شناسهای به این مرحله نرسد، data برابر null است.
POST/api/invoice/cancelInvoice
v2.invoice.cancel
internalId مرجع، 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 رد میشود. هر شناسه جداگانه ارسال میشود، پس برای کوتاه ماندن زمان پاسخ، شناسههای زیاد را در چند درخواست بفرستید.
ابطال برای آخرین صورتحساب زنجیره internalId ثبت میشود و آن صورتحساب باید ارسالشده و دارای شماره مالیاتی باشد؛ اگر آخرین صورتحساب زنجیره اصلاحی ارسالنشده یا بینتیجه باشد، درخواست با خطا در مسیر $.internalId رد میشود.
پیش از ثبت، وضعیت زنجیره مانند «ابطال» پنل از کارپوشه گرفته میشود (کدهای خطا).
تاریخ صدور ابطالی ابتدای دقیقه پیش از زمان ثبت است تا در ارسال فوری، تفاوت ساعت سرورها آن را «آینده» نشان ندهد، ولی هیچگاه پیش از تاریخ و ساعت دقیق صورتحساب مرجع (تا ثانیه، با گرد شدن رو به بالا) نیست؛ طبق RC_IITP.IS_V7.9 (قاعده ۳ فیلد indatim) تاریخ صدور ابطالی نباید از تاریخ صدور مرجع کوچکتر باشد. ساعت سرور ممکن است چند ده ثانیه از ساعت واقعی عقب باشد؛ برای همین، ابطالی مرجعی که تازه ثبت شده با همان تاریخ و ساعت مرجع صادر میشود.
اگر آخرین صورتحساب زنجیره ابطالی ثبتنشده همین زنجیره باشد، ابطال دوم کنار آن ثبت نمیشود: ابطالی ردشده حذف و ابطال تازه ثبت میشود و ابطالی ارسالنشده یا بینتیجه با کد خطا رد میشود (ابطالی ناموفق، ارسالنشده یا بینتیجه).
فقط همراه کلید ثابت قدیمی معنا دارد و با 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 هیچگاه ابطال دومی کنار آن نمیسازد. رفتار به وضعیت همان ابطالی بستگی دارد:
ردشده (آخرین نتیجهٔ ارسال آن شکست قطعی است، مثلاً خطای 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/inquiryInternalId
internalId
پیگیری با کد داخلی ارسالی.
POST/api/invoice/inquiryInternalIds
internalIds[]
پیگیری گروهی با کدهای داخلی؛ حداکثر ۲۵۰ مقدار.
POST/api/invoice/inquiryNo
no
پیگیری با شماره صورتحساب یا inno.
POST/api/invoice/inquiryNos
nos[]
پیگیری گروهی با شمارههای صورتحساب یا inno؛ حداکثر ۲۵۰ مقدار.
POST/api/invoice/inquiryTaxId
taxId
پیگیری با شماره منحصر به فرد مالیاتی.
POST/api/invoice/inquiryTaxIds
taxIds[]
پیگیری گروهی با شمارههای منحصر به فرد مالیاتی؛ حداکثر ۲۵۰ مقدار.
پیگیری وضعیت آخرین صورتحساب زنجیره را برمیگرداند. اگر برای صورتحسابی اصلاحی، ابطالی یا برگشت از فروش ثبت شده باشد، پیگیری با internalId یا taxId صورتحساب اصلی، taxId و status همان آخرین صورتحساب را برمیگرداند و internalId پاسخ همان مقداری است که فرستادهاید. موضوع صورتحساب برگشتی در فیلد issue میآید: 1 اصلی، 2 اصلاحی، 3 ابطالی و 4 برگشت از فروش. پیش از ذخیره taxId پاسخ، issue را بررسی کنید تا شماره مالیاتی صورتحساب ارجاعی بهجای شماره صورتحساب اصلی ثبت نشود.
inquiryNo فقط یک صورتحساب برمیگرداند. فاصلههای ابتدا و انتهای شماره در نظر گرفته نمیشود. شماره عددی با مقدار عددی آن مقایسه میشود و شماره غیرعددی باید با کل شماره صورتحساب یکسان باشد؛ بخشی از شماره (مثلاً A1 برای A10) صورتحسابی پیدا نمیکند. اگر چند صورتحساب این شماره را داشته باشند (مثلاً در دو سال مالی)، مانند گذشته نخستین صورتحسابی که ثبت شده انتخاب میشود و وضعیت آخرین صورتحساب زنجیره آن برمیگردد. پاسخ inquiryNo فیلد no (همان مقدار ارسالی) را دارد و پاسخ inquiryNo و inquiryTaxId فیلد internalId ندارد. برای پیگیری قطعی از internalId یا taxId استفاده کنید. کد داخلی عددی با مقدار عددی آن مقایسه میشود؛ برای نمونه "001" و "1" یک صورتحساب به حساب میآیند.
اگر با send: false یا با ارسال خودکار خاموش ثبت شده است، sendInvoice را فراخوانی کنید؛ در غیر این صورت چند دقیقه بعد دوباره پیگیری کنید.
1
در صف ارسال یا ارسالشده و در انتظار پاسخ سامانه مؤدیان
پس از چند دقیقه، وضعیت را دوباره پیگیری کنید.
2
موفق
شماره مرجع و taxId را ذخیره کنید.
3
دارای خطا
پیام خطا را در error بررسی کنید؛ در این وضعیت json برنمیگردد. اگر سامانه مؤدیان صورتحساب را رد کرده است، آن را با editInvoice اصلاح و دوباره ارسال کنید. پاسخ بدون asatspId یعنی صورتحساب پیدا نشد یا خود درخواست رد شد.
ارسال نمیشود و 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) تغییر میکند و اصلاحی فقط با تأیید صریح شما صادر میشود. هر ویرایش نسخهٔ تازهای میسازد و نسخهٔ قبلی در سوابق میماند.
دو راه دارد. دو مرحلهای: درخواست را بدون تأیید بفرستید؛ اگر تغییرات اصلاحی صادر کند، چیزی ثبت نمیشود و پاسخ با 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 یا false
true: اگر تغییرات صورتحساب اصلاحی صادر کند، در همین درخواست صادر شود. روی صورتحساب ارسالنشده اثری ندارد.
confirmationToken
اختیاری
توکن پاسخ confirmationRequired برای صدور همان اصلاحی، حداکثر تا ۱۵ دقیقه. با confirmCorrection: true لازم نیست.
description
اختیاری، فقط در editInvoice
توضیح صورتحساب؛ اگر نفرستید، توضیح فعلی میماند. در مدل ساده همان data.description است.
پاسخ در قالب همیشگی با HTTP 200 برمیگردد. در موفقیت، result برابر 1 و data[0] اطلاعات استعلام نسخهٔ جاری صورتحساب است (برای اصلاحی، issue: 2 و شماره مالیاتی تازه). در خطا، result برابر 0 (احراز هویت -1، تکراری -2) و کد خطا در errors[].code است. شیء edit فقط در پاسخ این دو سرویس میآید:
فیلد
توضیح
edit.outcome
draftUpdated، 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/inquiryExchangeAnnouncement
v2.invoice.read
internalId یا taxId
استعلام وضعیت فعلی زنجیره.
POST/api/invoice/exchangeAnnouncement
v2.invoice.send
internalId یا 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 یا false
true یعنی اعلامیه فروش بورس تأیید شده و false یعنی تأیید نشده است.
note
اختیاری، حداکثر ۵۰۰ کاراکتر
توضیح تغییر؛ در تاریخچه ثبت میشود.
expectedVersion
اختیاری
همان version پاسخ استعلام.
مقادیر وضعیت
status
معنا
اثر بر اصلاحی
notRecorded
هنوز وضعیتی ثبت نشده است.
اصلاحی مانند گذشته مجاز است.
notConfirmed
اعلامیه فروش بورس تأیید نشده است.
اصلاحی مجاز است.
confirmed
اعلامیه فروش بورس تأیید شده است.
فقط ابطال؛ اصلاحی با EXCHANGE_ANNOUNCEMENT_CONFIRMED رد میشود.
منبع و کانال ثبت
فیلد
مقدار
معنا
source
manual
ثبت دستی (پنل، API نسخه ۲ یا اسکریپت پشتیبانی).
source
orgApi
دریافتشده از API آتی سازمان. تغییر دستی آن فقط برای مدیر سامانه و با توضیح مجاز است؛ در API نسخه ۲ خطای EXCHANGE_ANNOUNCEMENT_FORBIDDEN برمیگردد.
channel
panel، 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
شماره مالیاتی و شناسه صورتحساب اصلی زنجیره (کلید وضعیت).
status
notRecorded، 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? } اضافه میشود. برای سایر الگوها، یا اگر وضعیت قابل خواندن نباشد، این فیلد در پاسخ وجود ندارد.
با این مسیرها، نرمافزار شما همان کارهای بخش «کارپوشه مالیاتی» پنل را انجام میدهد: فهرست صورتحسابهای خرید، فروش و مجازی و قراردادهای شخص ثالث را از سامانه مؤدیان میخواند، صورتحسابهای در انتظار واکنش و قراردادها را بهصورت گروهی تأیید یا رد میکند و همین کارها را با فایل 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ها
Method
Endpoint
Scope
کاربرد
GET
/api/v2/tax-workspace/invoices/{kind}
v2.invoice.read
خواندن یک صفحه (حداکثر ۱۰ ردیف) از فهرست صورتحسابهای کارپوشه با JSON.
دریافت فایل نتیجه با 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 است.
مانند فهرست صورتحساب؛ 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 بفرستید.
در حالت ساده فقط kind، آرایه taxIds و action ارسال میشود. Backend روز صدور و دوره مالیاتی را از بخش روز رسمی TaxId استخراج میکند، حداکثر دو تاریخ محتمل تهران را در فهرست واگذارشده همان کارپوشه استعلام میگیرد و فقط TaxId دقیق با وضعیت AWAITING_REACTION را قبل از PUT میپذیرد. بنابراین Client برای تأیید نیازی به ارسال period یا تاریخ ندارد و TaxId نیز نمیتواند کارپوشه دیگری را انتخاب کند.
Action فقط APPROVE یا REJECT است. دلیلهای مجاز: NOT_INFORMED، BUYER، SELLER، PRODUCT، AMOUNT، PAYMENT و OTHER. برای OTHER توضیح الزامی است. برای Actionهای متفاوت در یک درخواست، شکل تفصیلی سازگار با نسخه قبل یعنی operations[] همچنان پشتیبانی میشود؛ در این شکل period و issuanceDate اختیاریاند و در صورت حذف از TaxId استخراج میشوند. ارسال همزمان taxIds و operations با invalid_bulk_shape رد میشود.
برای انتخاب همه، فقط قراردادهای 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: دریافت فایل، پیشنمایش، اجرا و فایل نتیجه
فایل واقعی Filterشده یا Template را دانلود کنید.
نمونه صورتحساب فقط چهار ستون فارسی «شناسه یکتای مالیاتی»، «عملیات»، «دلایل رد» و «توضیحات رد» دارد. نمونه قرارداد فقط «شماره قرارداد» و «عملیات» دارد. چند دلیل فارسی با ; جدا میشوند؛ مانند «کالا یا خدمت;مبلغ صورتحساب».
برای واکنش به همه قراردادهای قابل اقدام همین کارپوشه، در ستون «شماره قرارداد» مقدار «همه» را بنویسید. فایل هیچ کد اقتصادی یا شناسه Tenant دریافت نمیکند.
فایل را با multipart/form-data و نام فیلد file برای Preview ارسال کنید. Preview هیچ واکنشی اجرا نمیکند.
Summary شامل قابل اجرا، Approve، Reject، بدون Action و خطادار را بررسی کنید.
previewToken کوتاهعمر را با endpoint Execute ارسال کنید.
پس از اجرا، فایل نتیجه را با resultToken دریافت کنید.
Workbook جدید بهصورت راستبهچپ و با Sheetهای فارسی دادهها، راهنما و فهرستها تولید میشود. عنوان ستونها، وضعیتها، نوعها، نقشها، عملیات «تأیید/رد» و دلیلهای رد با اصطلاحات فارسی مستندات نمایش داده میشوند و Backend آنها را پیش از اجرا به کدهای فنی ثابت تبدیل میکند. فایلهای قدیمی دارای Sheet Data و عنوانها یا کدهای انگلیسی همچنان قابل بارگذاریاند. فایل نتیجه ستونهای فارسی «نتیجه عملیات»، «زمان پردازش»، «کد پاسخ»، «پیام پاسخ» و «شناسه رهگیری» را اضافه میکند. هیچ Token، Secret یا Authorization Header در فایل نوشته نمیشود. Claim اجرای Excel با تنظیم TaxWorkspace.ExcelExecutionRetentionHours در بازه 3..168 ساعت نگهداری میشود و مقدار پیشفرض آن 24 ساعت است.
previewStatus هر ردیف یکی از این مقدارهاست: EXECUTABLE (اجرا میشود)، SKIPPED (بدون عملیات)، VALIDATION_ERROR (خطای ردیف؛ متن آن در errors[])، NOT_ACTIONABLE، PERMISSION_DENIED، FEATURE_DISABLED (تأیید و رد قرارداد فعال نیست)، FAILED یا AMBIGUOUS. فقط ردیفهای EXECUTABLE با previewToken اجرا میشوند.
فقط فایل .xlsx با Content-Type برابر application/vnd.openxmlformats-officedocument.spreadsheetml.sheet یا application/octet-stream پذیرفته میشود و سرور ساختار آن را هم بررسی میکند. هدر Content-Length الزامی است؛ ارسال تکهای (chunked) بدون آن با HTTP 411 رد میشود. حجم فایل بهطور پیشفرض حداکثر ۵ مگابایت و تعداد ردیفها حداکثر ۵۰۰ است. کل فایل رد میشود اگر رمزدار باشد، ماکرو داشته باشد، در عنوان ستونها فرمول باشد یا ستونی غیر از ستونهای نمونه و خروجی داشته باشد. فرمول در یک سلول داده یا شناسه تکراری فقط همان ردیف را نامعتبر میکند. حداکثر عملیات قابل اجرای صورتحساب و قرارداد در هر نوبت بهطور پیشفرض ۲۰ است و previewToken پانزده دقیقه اعتبار دارد. نتیجه هر اجرا برای تکرار امن و دریافت فایل نتیجه بهطور پیشفرض ۲۴ ساعت نگهداری میشود.
خطای هر ردیف در نتیجه همان ردیف میآید و بقیه ردیفها اجرا میشوند: پیشنمایش در data.rows[].previewStatus و previewCode، واکنش گروهی JSON در data.results[] و اجرای Excel در data.summary.results[]. فقط در پیشنمایش Excel قرارداد، خاموش بودن تأیید و رد قرارداد و نبود مجوز آن هم در همین ستونها میآید.
Scope لازم در توکن نیست یا توکن برای این مسیر نیست (مثلاً توکن همکار)، Customer API Key قدیمی از نشانیای بیرون از محدودیت IP رسیده است، Token متعلق به Company، API Client، کارپوشه یا نوع عملیات جاری نیست، یا مجوز لازم آن فهرست (مثلاً مشاهده خرید یا قرارداد) در دسترسی واگذارشده کارپوشه نیست. علت در errors[].message میآید.
403
tax_workspace_contract_permission_missing
مجوز contract.brokerage:manage در دسترسی واگذارشده نیست؛ واکنش گروهی JSON و اجرای Excel قرارداد با همین پاسخ رد میشوند.
404
unsupported_invoice_kind
مقدار {kind} در مسیر پشتیبانی نمیشود.
408
request_cancelled / upstream_timeout
درخواست در زمان پردازش لغو شده یا زمان آن به پایان رسیده است؛ upstream_timeout یعنی سامانه مؤدیان بهموقع پاسخ نداد.
سقف نتیجه یا عملیات رد شده، اجرای همان Preview در حال انجام یا نتیجه قبلی نامشخص است، یا مهلت Preview/Result پایان یافته است. این پاسخها مجوز Retry کور PUT نیستند.
403
tax_workspace_permission_missing (همراه کد سازمان ACCESS_DENIED)
سامانه مؤدیان گفته است مجوز همین سرویس در تفویض نیست. فقط همین عملیات ناموفق است و دسترسی واگذارشده و دیگر مجوزهای آن سر جایشان میمانند؛ برای این بخش، مدیر کسبوکار باید از تنظیمات کسبوکار دسترسی را با همین مجوز دوباره بگیرد.
409
tax_workspace_reauthorization_required
دسترسی واگذارشده کارپوشه فعال نیست یا اعتبار آن تمام شده است؛ مدیر کسبوکار باید از تنظیمات کسبوکار در پنل دوباره دسترسی بگیرد. تکرار درخواست تا آن زمان نتیجهای ندارد.
تنظیمات سرور کامل نیست، سرویس در این محیط فعال نیست یا ارتباط با سامانه مؤدیان برقرار نشد.
503
tax_workspace_excel_unavailable
فایل Excel خروجی، نمونه یا نتیجه در سرور آماده نشد؛ درخواست شما ایرادی ندارد. کمی بعد دوباره تلاش کنید و اگر تکرار شد، correlationId را برای پشتیبانی بفرستید.
503
tax_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ها
Method
Endpoint
اعتبارنامه / Scope
کاربرد
GET
/api/v2/tax-workspace/delegation
Customer / v2.invoice.read
وضعیت دسترسی کارپوشه همین کسبوکار: usable، otpPending، maskedMobile، expiresAt، memoryPermissionGranted.
POST
/api/v2/tax-workspace/delegation/otp
Customer / v2.invoice.send
ارسال رمز سامانه مؤدیان به موبایل مالک. بدنه اختیاری: {"validityDurationDays": 365} (۱ تا ۳۶۵).
POST
/api/v2/tax-workspace/delegation/verify
Customer / v2.invoice.send
تأیید رمز: {"otp": "123456"}.
POST
/api/v2/tax-workspace/memory-unique-id
Customer / v2.invoice.send
دریافت شناسه یکتای تازه و ثبت آن روی کسبوکار. بدنه اختیاری: {"title": "..."}.
POST
/api/v2/tax-workspace/onboarding/otp
Partner / v2.register
ارسال رمز برای مؤدی ثبتنشده: {"economicCode": "14000000001"}.
دریافت شناسه یکتا برای همان شماره اقتصادی، فقط تا ۳۰ دقیقه پس از تأیید رمز توسط همین همکار.
روند همکار برای مؤدی تازه
POST /api/v2/tax-workspace/onboarding/otp با شماره اقتصادی مؤدی؛ پاسخ maskedMobile، otpLength و otpExpiresAt (epoch milliseconds) را برمیگرداند. تا پایان اعتبار، رمز دوباره فرستاده نمیشود.
مؤدی رمز پیامکشده را به شما میدهد؛ POST /api/v2/tax-workspace/onboarding/verify.
POST /api/v2/tax-workspace/onboarding/memory-unique-id؛ مقدار memoryUniqueId را بردارید.
POST /api/register با همان economicCode و fiscalId برابر memoryUniqueId. اگر environment در پاسخ مرحله ۳ برابر Sandbox بود، sandBox: true را هم بفرستید؛ شناسه Sandbox در محیط عملیاتی پذیرفته نمیشود.
سرویس کارپوشه یا دریافت شناسه در این محیط فعال نیست.
هر درخواست، با شماره اقتصادی و نتیجه، در گزارش عملیات کارپوشه ثبت میشود؛ رمز و توکن هرگز ذخیره یا برگردانده نمیشوند. قالب پاسخ همان Envelope بخش کارپوشه (status، data، errors[]، fieldErrors[]، correlationId) است.
19کارپوشهٔ مالیاتی
ثبت پرداخت صورتحساب ارسالشده در کارپوشه
برای صورتحسابی که با روش تسویه نسیه یا نقدی/نسیه به سامانه مؤدیان ارسال و در کارپوشه ثبت شده است، پرداختهای بعدی خریدار از طریق سرویس رسمی «ثبت پرداخت صورتحساب» (invoice-payment، مستند RC_TICS.IS) در کارپوشه ثبت میشوند. این سرویس همان کار را برای شما انجام میدهد: پرداختهای جدید روی آخرین صورتحساب زنجیره internalId ذخیره میشوند، نسخهٔ جدید صورتحساب با همان شماره مالیاتی ساخته میشود (اصلاحی صادر نمیشود) و هر ردیف جدید در همان درخواست به سامانه مؤدیان فرستاده میشود. اگر پاسخ سازمان به موقع نرسد یا خطای گذرا (مانند کد 10015) برگردد، ثبت بهصورت خودکار دوباره تلاش میشود و نتیجه را با /api/invoice/inquiryPayment پیگیری میکنید.
مسیر
scope
بدنه
کاربرد
POST/api/invoice/registerPayment
v2.invoice.send
uuid، internalId، payments[]
افزودن پرداختهای جدید به صورتحساب ارسالشده و ثبت آنها در کارپوشه.
POST/api/invoice/inquiryPayment
v2.invoice.read
internalId
وضعیت همهٔ ردیفهای پرداخت صورتحساب و وضعیت ثبت هر کدام در کارپوشه.
پیششرط صورتحساب
آخرین صورتحساب زنجیره باید ارسالشده و در سامانه مؤدیان ثبت شده باشد (وضعیت تأیید شده، تأیید سیستمی یا در انتظار واکنش)، ابطالی نباشد و روش تسویهای که به سازمان ارسال شده نقدی نباشد؛ الگوی بورس (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
الزامی
کد داخلی صورتحساب؛ آخرین صورتحساب زنجیرهٔ آن در نظر گرفته میشود.
همان کدهای روش پرداخت مدل ساده (جدول مقادیر شمارشی)؛ به ترتیب به 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 برمیگردد.
پاسخ در قالب همیشگی (result، traceId، message، errors، data) با HTTP 200 برمیگردد. عضو data[0] همان اطلاعات استعلام صورتحساب است بهعلاوهٔ paymentRegistration (قابلیت ثبت پرداخت روی این صورتحساب) و payments[] (همهٔ ردیفهای پرداخت صورتحساب با وضعیت هر کدام). در خطا، result برابر 0 (تکراری -2، احراز هویت -1) است و کدها در errors[].code میآیند.
فیلد
توضیح
paymentRegistration.eligible
true یعنی پرداختهای جدید روی این صورتحساب در کارپوشه ثبت میشوند؛ در غیر این صورت code و reason دلیل را میگویند.
paymentRegistration.rowsLocked
صورتحساب ارسالشده است و ردیفهای قبلی پرداخت آن قابل تغییر نیستند.
ردیف پرداخت. 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[] (مدل ساده) یا Payments (JSON سازمان) میفرستید همراه خود صورتحساب به سازمان میروند و در استعلام با وضعیت sentWithInvoice دیده میشوند.
19Aکارپوشه مالیاتی
استعلام پرونده مالیاتی
این سرویس پروندههای مالیاتی یک شخص یا شرکت را از سامانه مؤدیان استعلام میکند. شناسه میتواند کد ملی، شناسه ملی، کد فراگیر اتباع یا شماره اقتصادی باشد. پاسخ، هر پرونده را با شماره اقتصادی، وضعیت کارپوشه و نوع مؤدی برمیگرداند. کاربرد اصلی آن پیش از صدور صورتحساب نوع ۱ است: شماره اقتصادی خریدار را از پرونده او برمیدارید و میبینید کارپوشهاش فعال است یا نه.
مسیر
scope
بدنه
کاربرد
POST/api/v2/tax-file-inquiry
v2.lookup.read
identifier
فهرست پروندههای مالیاتی یک کد ملی، شناسه ملی، کد فراگیر اتباع یا شماره اقتصادی.
پیششرط: سرویس ارزشافزوده
این استعلام همان سرویس ارزشافزوده «استعلام پرونده مالیاتی خریدار» در پنل است. کسبوکار باید خودش آن را در پنل، بخش «تنظیمات کسبوکار ← سرویسها و تعرفهها»، فعال کند. تا سرویس فعال نشده، پاسخ 403 با کد tax_file_inquiry_not_active است و از سامانه مؤدیان چیزی پرسیده نمیشود.
هزینه هر استعلام
هزینه طبق تعرفه همین سرویس در پنل است و از کیف پول کسبوکار کم میشود. هر استعلامی که سامانه مؤدیان به آن پاسخ دهد یک بار هزینه دارد؛ پاسخ «پروندهای پیدا نشد» هم پاسخ سازمان است. شناسه نادرست و استعلامی که سازمان به آن پاسخ نداد هزینهای ندارد. اگر موجودی کیف پول به اندازه یک استعلام نباشد، پاسخ 402 با کد tax_file_inquiry_wallet_insufficient است.
تکرار استعلام
استعلام دوباره همان شناسه، استعلام تازهای است و دوباره هزینه دارد. پاسخ را در سامانه خودتان نگه دارید و فقط وقتی به وضعیت تازه نیاز دارید دوباره بپرسید.
سقف و درخواست همزمان
این سرویس سقف روزانه ندارد. استعلامهای هر کسبوکار یکی پس از دیگری انجام میشود: درخواست همزمان تا ۳۰ ثانیه منتظر نوبت میماند و اگر نوبت نرسد پاسخ 429 با کد tax_file_inquiry_busy میگیرد. درخواستها را پشت سر هم بفرستید و مهلت پاسخ را در سامانه خودتان دستکم ۶۰ ثانیه بگذارید.
فیلدهای درخواست
فیلد
قاعده
توضیح
identifier
الزامی
کد ملی (۱۰ رقم)، شناسه ملی (۱۱ رقم)، کد فراگیر اتباع (۱۲ رقم) یا شماره اقتصادی (۱۱ یا ۱۴ رقم). رقم فارسی و خط تیره پذیرفته میشود. با کد ملی، همه پروندههای آن شخص فهرست میشود. عدد ۱۱ رقمی ابتدا بهعنوان شماره اقتصادی و اگر پروندهای نداشت بهعنوان شناسه ملی پرسیده میشود.
شناسه فقط در بدنه درخواست میآید و در نشانی قرار نمیگیرد. کد ملی داده شخصی است؛ آن را در گزارشهای سامانه خودتان کامل ثبت نکنید.
پاسخ در همان Envelope سرویسهای کارپوشه است: status، data، errors[]، fieldErrors[] و correlationId. مقدار correlationId در هدر X-Correlation-ID هم برمیگردد و همین استعلام را در گزارش کارپوشه کسبوکار در پنل نشان میدهد؛ هنگام پیگیری از پشتیبانی آن را بفرستید.
فیلد
نوع
توضیح
data.identifier
string
شناسه پرسیدهشده با رقم لاتین و بدون جداکننده.
data.queriedBy
string
nationalId یا economicCode: شناسه با کدام عنوان از سازمان پرسیده شد.
data.found
boolean
true وقتی دستکم یک پرونده پیدا شده است. با false فهرست taxFiles خالی است و data.message توضیح میدهد.
data.taxFiles[]
array
پروندهها؛ پروندههای فعال اول میآیند.
taxFiles[].economicCode
string / null
شماره اقتصادی پرونده (۱۱ یا ۱۴ رقم). همین مقدار را در tinb یا buyer.economicCode صورتحساب بفرستید.
taxFiles[].nationalId
string / null
کد ملی، شناسه ملی یا کد فراگیر صاحب پرونده.
taxFiles[].brand
string / null
نام تجاری ثبتشده برای پرونده، اگر سازمان آن را برگرداند.
taxFiles[].taxFileStatus
string
وضعیت کارپوشه به مقدار سازمان: ACTIVE، NOT_ALLOCATED، TEMPORARY_UNAUTHORIZE یا PERMANENT_UNAUTHORIZE.
taxFiles[].taxFileStatusTitle
string
عنوان فارسی همان وضعیت: «فعال»، «تخصیص نیافته»، «غیرمجاز موقت» یا «غیرمجاز دائم».
taxFiles[].active
boolean
true فقط برای کارپوشه فعال.
taxFiles[].callStatusTitle
string / null
وضعیت فراخوان مؤدی: «مشمول» یا «غیرمشمول».
taxFiles[].registrationStatusTitle
string / null
وضعیت ثبتنام پرونده در سامانه مؤدیان: «ثبتنام فعال» یا «ثبتنام غیرفعال».
taxFiles[].buyerType
number / null
نوع مؤدی از روی شناسههای پرونده، با همان کدهای tob: 1 حقیقی، 2 حقوقی، 3 مشارکت مدنی، 4 اتباع غیرایرانی. اگر از شناسهها مشخص نشود null است.
taxFiles[].buyerTypeTitle
string / null
عنوان فارسی نوع مؤدی.
taxFiles[].warning
string / null
هشدار پیش از صدور صورتحساب نوع ۱ برای این پرونده، مثلاً وقتی کارپوشه فعال نیست و صورتحساب ممکن است در سامانه مؤدیان رد شود.
{
"status": "FORBIDDEN",
"data": null,
"errors": [
{
"code": "tax_file_inquiry_not_active",
"message": "«استعلام پرونده مالیاتی خریدار» سرویس ارزشافزوده است و برای این کسبوکار فعال نیست؛ آن را در پنل، بخش «تنظیمات کسبوکار ← سرویسها و تعرفهها»، فعال کنید."
}
],
"fieldErrors": [],
"correlationId": "6f1c2d0a8b7e4c1e9a3b5d7f0c2e4a63"
}
خطاها
کد خطا را از errors[0].code بخوانید و متن errors[0].message را به کاربر نشان دهید.
HTTP
Code
معنا و اقدام
هزینه
400
validation_failed
identifier خالی است یا تعداد رقمهای آن ۱۰، ۱۱، ۱۲ یا ۱۴ نیست. شناسه را اصلاح کنید.
ندارد
401
unauthorized
Access Token ارسال نشده، نامعتبر یا منقضی است. توکن تازه بگیرید.
ندارد
402
tax_file_inquiry_wallet_insufficient
سرویس فعال است ولی موجودی کیف پول کسبوکار به اندازه یک استعلام نیست. کیف پول را در پنل شارژ کنید.
ندارد
403
tax_file_inquiry_not_active
سرویس ارزشافزوده برای این کسبوکار فعال نیست. آن را در پنل فعال کنید.
ندارد
403
forbidden / IP_NOT_ALLOWED
توکن scope لازم را ندارد، یا درخواست از نشانیای خارج از محدودیت IP اعتبارنامه رسیده است.
ندارد
429
tax_file_inquiry_busy
استعلام قبلی همین کسبوکار هنوز در حال انجام است. همین درخواست را پس از تعداد ثانیهای که هدر Retry-After میگوید تکرار کنید.
ندارد
502
organization_unavailable
سامانه مؤدیان به استعلام پاسخ نداد. کمی بعد دوباره تلاش کنید.
ندارد
503
tax_file_lookup_unavailable
استعلام پرونده مالیاتی موقتاً در دسترس نیست. کمی بعد دوباره تلاش کنید.
ندارد
504
organization_timeout
پاسخ سامانه مؤدیان در مهلت ۱۵ ثانیه نرسید. کمی بعد دوباره تلاش کنید.
ندارد
اگر فقط میخواهید شماره اقتصادی خریدار حقیقی هنگام ثبت صورتحساب نوع ۱ خودکار پر شود، به این سرویس نیاز ندارید: با فعال بودن همین سرویس ارزشافزوده، کد ملی خریدار را بدون tinb بفرستید و بخش خریدار حقیقی با کد ملی را ببینید. این سرویس برای وقتی است که میخواهید پروندهها را پیش از صدور ببینید یا بین چند پرونده انتخاب کنید.
این فهرست مسیرهای اصلی را نشان میدهد. همه مسیرهای 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[].data
object شامل Header و Body.
فیلد data الزامی است.
Header
فیلد
قاعده
توضیح
indatim
Unix time عددی بر حسب میلیثانیه، حداکثر 13 رقم.
تاریخ و زمان صدور صورتحساب.
indati2m
تاریخ و زمان ثبت صورتحساب؛ Unix time عددی بر حسب میلیثانیه، حداکثر ۱۳ رقم و بدون اعشار.
فقط در ماده ۹ و همراه insr=1 لازم است؛ باید مستقل از indatim و بزرگتر یا مساوی آن باشد، از زمان ارسال جلوتر نباشد و فاصله آن تا ارسال بیش از ۱۵ روز نباشد.
insr
قاعده ارسال صورتحساب؛ در حالت ماده ۹ مقدار عددی 1.
برای صورتحساب خارج از مهلت ۱۵ روز همراه indati2m لازم است. برای صورتحساب عادی داخل مهلت، خارج از الگو است و در payload نهایی اعمال نمیشود.
inty
1 یا 2
نوع صورتحساب؛ در صورتحساب ابطالی نسخه ۷.۹ ارسال نمیشود و از مرجع دریافت میشود.
inp
1، 2، 3، 4، 5، 6، 7، 8، 9، 11، 13 یا 14
الگوی صورتحساب؛ در صورتحساب ابطالی نسخه ۷.۹ ارسال نمیشود و از مرجع دریافت میشود.
inty + inp
نوع ۱: همه الگوهای مجاز؛ نوع ۲: 1، 3، 9، 13
ترکیب نوع و الگو پیش از ثبت کنترل میشود و برای ترکیب نامعتبر خطای ساختیافته برمیگردد.
ins
1 اصلی، 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 رقم.
باید با شرکت احراز هویتشده برابر باشد.
tob
1 حقیقی، 2 حقوقی، 3 مشارکت مدنی، 4 اتباع غیر ایرانی
نوع شخص خریدار؛ برای صورتحساب نوع ۲ و الگوی صادرات اختیاری و برای صورتحساب ابطالی خارج از الگو است.
tinb
11 تا 14 رقم.
در صورت ارسال خریدار حقوقی الزامی است؛ در الگوی صادرات اختیاری و در صورتحساب ابطالی خارج از الگو است.
bid
5 تا 14 رقم.
برای نوع ۱ بهجز الگوی صادرات، حداقل tinb یا bid لازم است؛ در صورتحساب ابطالی خارج از الگو است.
bpc
در صورت ارسال دقیقاً 10 رقم.
کد پستی خریدار.
setm
1 نقدی، 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, scc
scln حداکثر 14 رقم؛ scc دقیقاً 5 رقم.
شماره پروانه گمرکی (نوع ۱، الگوهای ۱ و ۲) و کد گمرک محل اظهار (نوع ۱، الگوهای ۱، ۲ و ۷)؛ ذخیره و به سامانه مؤدیان ارسال میشوند. مقدار خارج از این قالب نادیده گرفته میشود.
cdcn, cdcd
cdcn حداکثر 14 رقم؛ cdcd روز Unix.
شماره و تاریخ کوتاژ اظهارنامه گمرکی در الگوی صادرات (inp=7).
in, an
9 تا 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 خارج از الگوست؛ فیلد را حذف کنید یا آرایه خالی بفرستید.
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/InvoiceItemUnit
v2.lookup.read
دیکشنری UnitId => Name: شناسه داخلی واحدها در معتمد آسا. این شناسه کد رسمی نیست و برای unit یا mu فرستاده نشود؛ از /api/InvoiceItemUnit/codes استفاده کنید (واحد اندازهگیری در مدل ساده).
GET/api/InvoiceItemUnit/codes
v2.lookup.read
آرایه [{ "code": "164", "name": "کیلوگرم" }]: کد رسمی هر واحد (سند واحدهای اندازهگیری سازمان، RC_UMGS_ST_V1_18)، همان مقداری که در Body[].mu و در مدل ساده در items[].unit فرستاده میشود؛ برای نمونه «عدد» 1627.
GET/api/Currency
v2.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 و مانند گذشته برمیگردند.
code
path
معنا و اقدام
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
$.uuid
uuid قبلاً برای این شرکت استفاده شده است (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 است.
code
path
معنا و اقدام
INVOICE_DUPLICATE_REQUEST
$.uuid
uuid قبلاً برای این شرکت استفاده شده است و کل درخواست رد میشود (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 رد میشود. برای این خریدار صورتحساب نوع ۲ بفرستید.
استعلام انجام نشد (سامانه مؤدیان پاسخ نداد): صورتحساب مثل قبل ثبت میشود و هشدار «استعلام نشد» برمیگردد.
code
path
معنا و اقدام
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… هستند.
code
path
معنا و اقدام
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_EDIT_DUPLICATE_REQUEST
$.uuid
با این uuid قبلاً ویرایشی ثبت شده است (result: -2)؛ وضعیت را استعلام کنید و برای ویرایش تازه uuid تازه بفرستید.
INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE
$
خطای گذرای پایگاه داده؛ ویرایش انجام نشده است. پس از استعلام، دوباره بفرستید.
INVOICE_EDIT_INTERNAL_ERROR
$ یا $.data
خطای داخلی؛ با traceId به پشتیبانی مراجعه کنید.
کدهای خطای صورتحساب ارجاعی (اصلاحی، ابطالی، برگشت از فروش)
پیش از ثبت صورتحساب ارجاعی در /send (ins برابر ۲، ۳ یا ۴)، مسیرهای مدل ساده (invoiceSubject برابر ۲، ۳ یا ۴) و cancelInvoice، وضعیت زنجیرهٔ صورتحساب مرجع مانند پنل از کارپوشه گرفته میشود: آخرین استعلامِ کمتر از ۲ ساعت مستقیم استفاده میشود، بین ۲ تا ۲۴ ساعت دوباره استعلام میشود (اگر کارپوشه پاسخ ندهد، همان آخرین استعلام مبناست) و بیش از ۲۴ ساعت یا بدون استعلام قبلی حتماً استعلام میشود. این کدها در errors[].code همان عضو میآیند و آن عضو ثبت نشده است.
code
path
معنا و اقدام
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 برمیگردد.
code
path
معنا و اقدام
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].returnRows
returnRows فقط 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 صورتحساب داشته باشد."
}
]
}
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']);
}
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 بفرستید.
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"))
پیش از ارسال صورتحساب واقعی، رفتار نرمافزار خود را در محیط آزمایشی (Sandbox) با موارد زیر بسنجید. نشانی و اعتبارنامه در دو محیط یکی است؛ فقط sandBox: true را در هر صورتحساب بفرستید و کسبوکار باید شناسه حافظه مالیاتی آزمایشی داشته باشد (حافظه مالیاتی و Sandbox). صورتحساب آزمایشی اثر مالیاتی ندارد.
status از 0 به 1 و سپس 2 (موفق) یا 3 (خطا) میرسد. در وضعیت 2، refrenceNumber را ذخیره کنید.
۳. تکرار همان درخواست
همان بدنه با همان uuid
result: -2 با کد INVOICE_DUPLICATE_REQUEST در مسیر $.uuid. صورتحساب دوم ساخته نمیشود.
۴. خطای اعتبارسنجی
یک قلم بدون unitPrice
result: 0، خطا در errors[] با path دقیق، و برای صورتحساب status: 3. هیچ چیز ثبت نمیشود.
۵. ثبت گروهی با یک عضو نادرست
دو صورتحساب، دومی با qty: -1
result: 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 مهاجرت کنید (احراز هویت).
محدودیت 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 با ردیفهای کالای برگشتی.