راهنمای فنی API نسخه ۲ آسا

Authorization: Bearer <AccessToken>
Content-Type: application/json; charset=utf-8

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

curl -X POST "https://api-v2.asatsp.ir/api/auth/v2/token" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "v2-customer-12345",
    "client_secret": "<client_secret>",
    "scope": "v2.invoice.send v2.invoice.read"
  }'

{
  "result": 1,
  "traceId": "6f9d0c76-1e78-4a61-9ec5-c63e38b49e3f",
  "message": "مشتری با موفقیت ایجاد شد.",
  "data": {
    "companyId": 1250,
    "fiscalId": "A1B2C3",
    "economicCode": "12345678901234",
    "valueAddedNotCalled": true,
    "customerApiKey": "9a1b2c3d4e5f",
    "serviceAuth": {
      "credential_type": "customer",
      "client_id": "v2-customer-1250",
      "client_secret": "shown-only-once",
      "allowed_scopes": "v2.invoice.cancel v2.invoice.read v2.invoice.send v2.lookup.read",
      "token_endpoint": "/api/auth/v2/token",
      "expires_in": 3600,
      "legacy_api_key_sunset_utc": "2026-10-08T00:00:00Z"
    },
    "created": true,
    "updated": false
  }
}

{
  "uuid": "2e4f2ce6-cc0e-447b-a697-204dc96ea6e8",
  "data": [{
    "internalId": "ARTICLE9-1001",
    "send": true,
    "fiscalId": "PRD123",
    "sandBox": false,
    "data": {
      "Header": {
        "indatim": 1782940800000,
        "indati2m": 1784146800000,
        "insr": 1,
        "inty": 1,
        "inp": 1,
        "ins": 1,
        "inno": "A000000009",
        "tins": "12345678901234",
        "tob": 2,
        "tinb": "10987654321000",
        "bpc": "1234567890",
        "setm": 1,
        "tprdis": 10000000,
        "tdis": 0,
        "tadis": 10000000,
        "tvam": 1000000,
        "todam": 0,
        "tbill": 11000000,
        "cap": 11000000,
        "insp": 0,
        "tvop": 1000000
      },
      "Body": [{
        "sstid": "1234567890123",
        "sstt": "کالای نمونه",
        "mu": "162",
        "am": 2,
        "fee": 5000000,
        "prdis": 10000000,
        "dis": 0,
        "adis": 10000000,
        "vra": 10,
        "vam": 1000000,
        "odam": 0,
        "olam": 0,
        "tsstam": 11000000
      }],
      "Payments": []
    }
  }]
}

{
  "uuid": "6b1f0f3e-3c8a-4c61-9f7e-3f2d7a5b9c11",
  "data": [{
    "internalId": "IME-1001",
    "send": true,
    "fiscalId": "PRD123",
    "sandBox": false,
    "data": {
      "Header": {
        "indatim": 1788271140000,
        "inty": 1,
        "inp": 11,
        "ins": 1,
        "inno": "A000000011",
        "tins": "12345678901234",
        "tob": 2,
        "tinb": "10987654321000",
        "setm": 3,
        "tadis": 1000001,
        "tvam": 0,
        "tbill": 1000001,
        "cap": 400000,
        "insp": 600001,
        "asn": "1405012345",
        "asd": 20697
      },
      "Body": [{
        "sstid": "1234567890123",
        "sstt": "کالای معامله‌شده در بورس کالا",
        "mu": "162",
        "am": 3,
        "adis": 1000001,
        "vra": 0,
        "vam": 0,
        "tsstam": 1000001
      }]
    }
  }]
}

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

{
  "uuid": "GUID یکتای درخواست",
  "data": [
    {
      "internalId": "کد داخلی یکتای صورتحساب",
      "send": true,
      "fiscalId": "SND123",
      "sandBox": true,
      "description": "توضیحات اختیاری",
      "data": {
        "Header": {},
        "Body": [],
        "Payments": []
      }
    }
  ]
}

{
  "uuid": "0df9e8c6-07ba-4dc6-93f2-c20f5f4aef08",
  "data": [{
    "internalId": "PROD-1001",
    "send": true,
    "fiscalId": "PRD123",
    "sandBox": false,
    "data": { "Header": {}, "Body": [], "Payments": [] }
  }]
}

{
  "uuid": "8fd4439c-7964-4ac4-aee0-f6fd2dfadff8",
  "data": [{
    "internalId": "SANDBOX-1001",
    "send": false,
    "fiscalId": "SND123",
    "sandBox": true,
    "data": { "Header": {}, "Body": [], "Payments": [] }
  }]
}

{
  "uuid": "5ec152a0-a8e8-4ee1-9bbf-73f7954b38ee",
  "data": [{
    "internalId": "SANDBOX-1002",
    "sandBox": true,
    "data": { "Header": {}, "Body": [], "Payments": [] }
  }]
}

{
  "uuid": "17c0f06d-5bf1-40dc-b3cc-61b76677d26e",
  "data": [{
    "internalId": "LEGACY-1001",
    "send": true,
    "data": { "Header": {}, "Body": [], "Payments": [] }
  }]
}

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

{
  "request": { "fiscalId": "ZZ9999", "sandBox": false },
  "error": "FiscalId حافظه مالیاتی انتخاب‌شده متعلق به این کسب‌وکار نیست."
}

{
  "request": { "fiscalId": "OFF123", "sandBox": false },
  "error": "شناسه حافظه مالیاتی انتخاب‌شده غیرفعال است و برای صورتحساب جدید قابل استفاده نیست."
}

{
  "request": { "fiscalId": "SND123", "sandBox": false },
  "error": "FiscalId حافظه مالیاتی انتخاب‌شده در محیط عملیاتی این کسب‌وکار ثبت نشده است."
}

{
  "request": { "sandBox": true },
  "error": "در محیط سندباکس چند شناسه حافظه مالیاتی فعال وجود دارد و هیچ شناسه پیش‌فرضی تعیین نشده است؛ شناسه حافظه مالیاتی باید صریح انتخاب شود."
}

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

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

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

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

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

{
  "uuid": "74ff263d-bf33-40df-a56d-91f07bb1624b",
  "internalId": "INV-10001",
  "cancelInternalId": "INV-10001-CANCEL",
  "send": true,
  "description": "ابطال به درخواست مشتری"
}

{
  "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"
    }
  ]
}

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

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

[
  {
    "asatspId": 105234,
    "taxId": "A1B2C304E7900000F42410",
    "status": 2,
    "internalId": "1000001"
  },
  {
    "status": 3,
    "error": ["صورتحساب یافت نشد"],
    "internalId": "1000002"
  }
]

{
  "taxId": "A1B2C304E7900000F42410"
}

{
  "internalId": "IME-1001",
  "confirmed": true,
  "note": "اعلامیه در سامانه بورس کالا تأیید شد.",
  "expectedVersion": "AAAAAAAAB9A="
}

{
  "result": 1,
  "traceId": "0c5d2a4e-6f1b-4c3e-9a57-2b8f4d1e7a90",
  "message": "وضعیت اعلامیه فروش بورس ثبت شد.",
  "data": [],
  "exchangeAnnouncement": {
    "invoiceId": 105234,
    "originTaxId": "A1B2C304E7900000F42410",
    "rootInvoiceId": 105234,
    "status": "confirmed",
    "source": "manual",
    "channel": "apiV2",
    "setBy": "API v2 (customer:81001)",
    "setAtUtc": "2026-09-15T06:30:00Z",
    "setAt": "1405/06/24 ساعت 10:00",
    "saleAnnNo": "1405012345",
    "saleAnnDate": "1405/06/10",
    "note": "اعلامیه در سامانه بورس کالا تأیید شد.",
    "version": "AAAAAAAAB9E=",
    "canChange": true,
    "pendingCorrectionDrafts": [
      { "invoiceId": 105240, "no": "A000000012", "hash": "9b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e" },
      { "invoiceId": 105241, "no": "A000000013", "hash": "0a1b2c3d4e5f60718293a4b5c6d7e8f9", "inFlight": true }
    ]
  }
}

{
  "uuid": "1f0c0f1e-6b1c-4c7b-9a2e-4d5a9d2f7a11",
  "internalId": "INV-10001",
  "payments": [
    {
      "type": 6,
      "dateTime": "1405/06/25 10:30",
      "price": 25000000,
      "traceNo": "13023878656431",
      "terminalNumber": "1302387",
      "description": "قسط دوم"
    }
  ]
}

{
  "result": 1,
  "traceId": "0f6c5f7a-2f6b-4a4f-9f5a-1b2c3d4e5f60",
  "message": "پرداخت‌ها ثبت شدند.",
  "data": [
    {
      "internalId": "INV-10001",
      "taxId": "A111H104EA6001D0B32AC6",
      "status": 3,
      "statusInquery": "AWAITING_REACTION",
      "paymentRegistration": { "eligible": true, "rowsLocked": true },
      "payments": [
        {
          "id": 50622,
          "type": 6,
          "dateTime": "1405/06/25 10:30",
          "timestamp": 1789446000000,
          "price": 25000000,
          "traceNo": "13023878656431",
          "terminalNumber": "1302387",
          "description": "قسط دوم",
          "locked": true,
          "registration": {
            "status": "registered",
            "registeredAt": 1789446065000,
            "taxCreateDate": 1789446064000,
            "registrationId": 12,
            "registeredAmount": 22727273
          }
        }
      ]
    }
  ]
}

{
  "kind": "purchase",
  "taxIds": ["<TaxId1>", "<TaxId2>"],
  "action": "APPROVE"
}

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

{
  "kind": "purchase",
  "operations": [
    {
      "taxId": "A111111111111111111111",
      "period": "140501",
      "issuanceDate": 1780000000000,
      "action": "APPROVE",
      "rejectReasons": [],
      "rejectDescription": null
    },
    {
      "taxId": "A222222222222222222222",
      "period": "140501",
      "issuanceDate": 1780000000000,
      "action": "REJECT",
      "rejectReasons": ["PRODUCT", "AMOUNT"],
      "rejectDescription": "مغایرت ردیف نمونه"
    }
  ]
}

{
  "status": "OK",
  "data": {
    "total": 2,
    "success": 1,
    "failed": 1,
    "skipped": 0,
    "results": [
      {
        "identifier": "A111111111111111111111",
        "period": "140501",
        "issuanceDate": 1780000000000,
        "action": "APPROVE",
        "status": "SUCCESS",
        "code": null,
        "message": "عملیات انجام شد.",
        "correlationId": "00000000-0000-0000-0000-000000000001"
      },
      {
        "identifier": "A222222222222222222222",
        "period": "140501",
        "issuanceDate": 1780000000000,
        "action": "REJECT",
        "status": "FAILED",
        "code": "invoice_not_actionable",
        "message": "صورتحساب در وضعیت قابل واکنش نیست.",
        "correlationId": "00000000-0000-0000-0000-000000000001"
      }
    ]
  },
  "errors": [],
  "fieldErrors": [],
  "correlationId": "00000000-0000-0000-0000-000000000001"
}

{
  "contractBrokerageNumbers": ["000000000001", "000000000002"],
  "action": "APPROVE"
}

{
  "allForCurrentEconomicNumber": true,
  "economicNumber": "<CurrentWorkspaceEconomicNumber>",
  "action": "APPROVE"
}

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

{
  "status": "OK",
  "data": {
    "batchCorrelationId": "00000000-0000-0000-0000-000000000001",
    "resultToken": "<ResultToken>",
    "summary": {
      "total": 2,
      "success": 1,
      "failed": 1,
      "skipped": 0,
      "batchCorrelationId": "00000000-0000-0000-0000-000000000001",
      "results": [
        {
          "identifier": "<SampleTaxId1>",
          "period": "140501",
          "issuanceDate": 1780000000000,
          "action": "APPROVE",
          "status": "SUCCESS",
          "code": null,
          "message": "عملیات انجام شد.",
          "correlationId": "00000000-0000-0000-0000-000000000001"
        },
        {
          "identifier": "<SampleTaxId2>",
          "action": "REJECT",
          "status": "VALIDATION_ERROR",
          "code": "invalid_excel_row",
          "message": "برای رد صورتحساب حداقل یک دلیل لازم است.",
          "correlationId": "00000000-0000-0000-0000-000000000001"
        }
      ]
    }
  },
  "errors": [],
  "fieldErrors": [],
  "correlationId": "00000000-0000-0000-0000-000000000001"
}

curl -X PUT "https://api-v2.asatsp.ir/api/v2/tax-workspace/invoices/bulk" \
  -H "Authorization: Bearer <AccessToken with v2.invoice.send>" \
  -H "X-Correlation-ID: 00000000-0000-0000-0000-000000000001" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"kind":"purchase","taxIds":["<TaxId1>","<TaxId2>"],"action":"APPROVE"}'

curl -X POST "https://api-v2.asatsp.ir/api/v2/tax-workspace/invoices/purchase/excel/preview" \
  -H "Authorization: Bearer <AccessToken with v2.invoice.send>" \
  -F "file=@operations.xlsx;type=application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"

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

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