ClearTax Docs
Subscribe for Updates
  • Introduction to ClearTax APIs
  • ☁️Clear Finance Cloud
    • Introduction to Clear Finance Cloud
    • Learn Clear Finance Cloud Basics
      • API client
      • Access token
      • FTP client
      • How to get Custom Upload Template ID?
    • CFC API Reference
      • Resources and Masters
        • Sale Document Line Object
        • Purchase Document Line Object
      • Generate Access Token API
      • Ingestion API
        • Ingest Documents via File
          • Get Pre-signed URL
          • Upload File to Storage
          • Trigger File Ingestion
          • Get File Ingestion Status
        • (Deprecated) Ingest Documents via JSON
    • Notifications
  • 🇮🇳GLS API
    • GLS API Reference
      • Resources and Masters
      • Advanced Ingestion API Reference
        • Get Pre-signed URL
        • Upload File to Storage
        • Create Ingestion Activity
        • Get Ingestion Activity Status
  • 🇮🇳GST API
    • Introduction to GST API
    • GST 2.0 API Reference
      • Upload Documents
    • GST FTP Magnet
  • 🇮🇳Max ITC API
    • Introduction to Max ITC API
    • Getting Started with Max ITC API
    • Max ITC API Reference
      • Resources and Masters
        • Input and output templates
        • Error Code Master
        • Learn Max ITC API Architecture
      • Max ITC APIs
        • Fetch Max ITC Configuration
        • Upload Purchase Documents
          • Ingest PR via File
          • (Deprecated) Ingest PR via JSON
        • Trigger Max ITC Workflow
        • Get Max ITC Results
        • Postman Collection
    • Max ITC FTP Magnet
  • 🇮🇳TDS API
    • Introduction to TDS API
    • TDS API Reference
      • Resources and Masters
        • Deduction Document Line Objects
        • Output Template(Error)
      • TDS APIs
        • Upload Deductions
          • Ingest Deductions via File
            • Get Pre-signed URL
            • Upload File to Storage
            • Trigger File Ingestion
            • Get File Ingestion Status
          • (Deprecated) Ingest Deductions via JSON
  • 🇮🇳E-Invoicing API
    • Introduction to E-Invoicing API
    • Learn E-Invoicing API Basics
      • How to get E-Invoicing User Auth Token?
      • How to scan the E-Invoice QR code?
      • How to add GSTIN to E-Invoicing?
        • Clear IRP API Credentials
    • Learn E-waybill API Basics
    • E-Invoicing API Reference
      • Setting up your account
      • Clear Schema
        • Generate IRN
        • Cancel IRN
        • Get E-Invoice PDF
        • Get E-Invoice by IRN
        • Generate E-Waybill by IRN
        • Generate E-Waybill for Non-IRN documents
        • Bulk Generate E-Waybill for Non-IRN documents
        • Cancel E-Waybill
        • Get E-Waybill PDF
        • Update E-Waybill Transporter ID
        • Update E-Waybill Part-B
        • Extend E-Waybill Validity
        • Generate/Regenerate Consolidated EWB
        • Get Consolidated EWB PDF
        • Initiate Multi-Vehicle E-Waybills
        • Update EWB Status from NIC
        • Download E-waybills by Others
        • Get E-Waybill Download Status
        • Get E-Waybills
        • Get latest E-Waybill status from Government
        • Generate B2C Payment QR Code
          • Generate B2C Payment QR Code (Lite)
        • Get Signed PDF
        • Sign PDF API Base 64 Encoded
        • Send an E-Invoice via Email
        • Get Invoice Details
      • Government Schema
        • Generate IRN
        • Cancel IRN
        • Get Invoice by IRN
        • Generate E-Waybill by IRN
      • Resources and Masters
        • E-Invoice Object
        • Country Code Master
        • State Code Master
        • Pincode Master
        • Pincode State Mapping Pattern
        • Port Code Master
        • Currency Code Master
        • UQC Master
        • Tax Rates
        • Error Codes
    • E-Invoicing FTP Magnet
  • 🇮🇳Invoicing API
    • Invoicing API Reference
      • Create an Invoice
      • Create Document (Non-Sale)
      • Download PDF of a Document
      • Get Document details
      • Resources and Master
        • Country Master
        • State Master
        • Pincode Master
        • Port Master
        • Currency Master
        • Unit Master
        • Document Types
        • Supply Types
  • 🇲🇾E-INVOICING MALAYSIA API
    • E-Invoicing Malaysia API Reference
      • Resources and Masters
        • Error resolution guide
        • Frequently asked questions (FAQs)
        • E-Invoice Object
      • Generate Access Token API
      • Malaysia E-Invoicing APIs
        • Generate E-Invoice for a Document
        • Status Check for Submitted E-Invoice
        • Cancel E-Invoice
        • Upload E-Invoice
        • Get Documents
        • Get E-Invoice PDF
        • Get Document via UUID
        • Delete Invoice
        • Send Bulk Email
        • Search Taxpayer Tin API
  • E-Invoicing FTP Magnet (XML)
  • E-Invoicing FTP Magnet (Excel)
  • 🇸🇦E-Invoicing KSA API
    • Introduction to E-Invoicing KSA API
    • Learn E-Invoicing KSA API Basics
      • How to get E-Invoicing KSA Auth Token?
      • How to add a VAT number to KSA E-Invoicing Account?
      • How to add Branch for existing Vat to KSA E-Invoicing Account ?
      • How to register a device for a VAT?
      • How to generate OTP on ERAD Portal?
      • How to get Print Template ID?
      • KSA E-Invoicing Integration Architecture
    • E-Invoicing KSA API Reference
      • Resources and Masters
        • UAT Checklist
        • E-Invoice Object
        • Error Details Object
        • Data Types
        • Code Lists
        • Common Errors and Resolution
      • Authentication
      • Generate Access Token API
      • KSA E-Invoicing APIs
        • Generate E-Invoice
          • Additional Standard (B2B) E-Invoice Examples
          • Additional Simplified (B2C) E-Invoice Examples
        • Generate E-Invoice Async
        • Generate E-Invoice via XML
        • Send Signed E-Invoice XML To ZATCA
        • Get Bulk Invoice Lite
        • Get Invoice
        • Get E-Invoice PDF
        • Get E-Invoice PDF/A-3 with PDF API
        • Register Device
        • Get PCSID Generation Status
        • Renew PCSID
        • Generate E-Invoice (Phase I)
        • Generate QR Code (Phase I)
        • Generate Device ID
        • Generate CSID and PCSID
        • Send E-Invoice via Email
        • Add Business units API
    • E-Invoicing KSA FTP Magnet
    • E-Invoicing KSA XML reporting FTP Magnet
  • 🧩Add-ons and Extensions
    • SAP Add-on
      • SAP Connectivity Checklist
        • Steps to import SSL/TLS certificates in SAP
        • Steps to check ICM settings in SAP
        • Steps to test connectivity in SAP
        • Steps to troubleshoot connectivity issues in SAP
    • Tally Add-on
  • Microsoft Dynamics 365(F&O)
  • General
    • Go-Live Cutover Activity Checklist
    • How to check DNS resolution?
    • How to check hostname reachability?
    • How to check if hostname is trusted?
    • How to get the SSL certificate of a host?
  • ⭐GST GSP API
    • Introduction to GST GSP API
    • Getting Started with GST GSP API
    • GST GSP API Reference
      • Sample API
    • Migrating from Karvy GST GSP
  • ⭐E-Waybill GSP API
    • Introduction to E-Waybill GSP API
    • Getting Started with EWB GSP API
      • How to register EWB GSP on NIC?
      • Sandbox GSTIN for EWB GSP
    • E-Waybill GSP API Reference
      • Sample API
    • Migrating from Karvy EWB GSP
  • ⭐E-Invoicing GSP API
    • Introduction to E-Invoicing GSP API
    • Getting Started with EINV GSP API
      • How to register EINV GSP on IRP?
      • Sandbox GSTIN for EINV GSP
    • E-Invoicing GSP API Reference
      • Sample API
  • Subscribe for Updates
  • 🚫(Deprecated) GST 1.0 API
    • (Deprecated) Introduction to GST API
    • (Deprecated) Learn GST API Basics
    • (Deprecated) Getting Started with GST API
      • (Deprecated) How to set up ClearTax account?
      • (Deprecated) How to authenticate API requests?
      • (Deprecated) How to upload an invoice from File?
      • (Deprecated) How to create custom import template?
    • (Deprecated) GST 1.0 API Reference
      • Taxpayer Information
      • (Deprecated) Invoices
      • (Deprecated) Bills of Supply
      • (Deprecated) Credit Debit Notes (CDN)
      • (Deprecated) Advances
      • (Deprecated) Resources and Masters
        • (Deprecated) How to read GST error response
        • (Deprecated) Unit of Measurement master
        • (Deprecated) State master
        • (Deprecated) Document Classification/Section Name master
      • (Deprecated) Items
      • (Deprecated) Contacts
      • (Deprecated) GST File Upload API Reference
  • 🚫Deprecated E-Waybill API
    • (Deprecated) Introduction to E-Waybill API
    • (Deprecated) Learn E-Waybill API Basics
    • (Deprecated) Getting Started with E-Waybill API
    • (Deprecated) E-Waybill API Reference
      • (Deprecated) Resources and Masters
        • (Deprecated) Unit Master
        • (Deprecated) State Master
        • (Deprecated) Error Master
      • (Deprecated) E-Waybill JSON API Reference
        • (Deprecated) Generating E-Waybill
        • (Deprecated) Getting E-Waybill
        • (Deprecated) Updating E-Waybill
        • (Deprecated) Extending Validity of E-Waybill
        • (Deprecated) Multi-vehicle E-Waybill
        • (Deprecated) Printing E-Waybill
        • (Deprecated) Cancelling E-Waybill
        • (Deprecated) Generating Consolidated E-Waybill
        • (Deprecated) Getting Consolidated E-Waybill
        • (Deprecated) Regenerating Consolidated E-Waybill
        • (Deprecated) Printing Consolidated E-Waybill
      • (Deprecated) E-Waybill File Upload API Reference
        • (Deprecated) Creating or Updating Documents
        • (Deprecated) Getting Upload Status
        • (Deprecated) Getting Upload Validation
        • (Deprecated) Getting Upload History
        • (Deprecated) Rate Limiting & Best Practices
    • (Deprecated) E-Waybill FTP Magnet
Powered by GitBook
On this page
  • Request Method
  • Request URL
  • Request Headers
  • Request Path Params
  • Request Query Params
  • Request Body
  • Sample Request
  • Response Status Codes
  • Response Schema
  • Sample Response (Success)
  • Sample Response (Error)
  • API Validations
  • API Constraints

Was this helpful?

  1. E-Invoicing KSA API
  2. E-Invoicing KSA API Reference
  3. KSA E-Invoicing APIs

Get Bulk Invoice Lite

Get the E-Invoice status and error message details in bulk for invoices using unique identifiers of the invoice.

Request Method

POST

Request URL

{{BASE_URL}}/v3/einvoices/get-bulk

Replace the {{BASE_URL}} with the one mentioned here based on whether you are using sandbox or production.

Rate Limit : 10 API requests per minute

Request Headers

Parameter
Data Type
Field Validations
Description

x-cleartax-auth-token

String

Cannot be empty

Mandatory. User auth token.

vat

String

Cannot be empty

Mandatory. VAT or Group VAT of the entity.

Request Path Params

There are no path parameters for this API.

Request Query Params

There are no query parameters for this API.

Request Body

Parameter
Data Type
Field Validations
Description

Invoices

List

Maximum invoice list can be up to 500

Mandatory. List of Invoice

methodOfGeneration

String

Enum : ONLINE, OFFLINE

Optional: default is both OFFLINE and ONLINE

Invoices Object

User has to send either UniqueId or the four invoice parameters (Invoice number, Invoice type, Invoice issue date and VAT) to fetch the details.

Parameter
Data Type
Field Validations
Description

uniqueId

String

Should be present if the next 4 parameters are absent

Conditional.

Concat of seller vat + invoice id + invoice type code + issue year. All these entities are separated by underscore.

Either unique id or invoice details are required to fetch the details.

invoiceNumber

String

NA

Conditional. Document Number (Invoice Reference Number).

invoiceType

String

Enum: INV, CRN, DBN

Conditional. INV - Invoice, CRN - Credit Note, DBN - Debit Note

issueDate

String

yyyy-mm-dd

Conditional. Document Date

vat

String

NA

Conditional. VAT Number.

Sample Request

Request Body

(Without MethodOfGeneration)

{
    "Invoices": [
           {
                "invoiceNumber": "RR-INV-0001",
                "invoiceType": "INV",
                "issueDate": "2022-08-13",
                "vat": "12345678901234"
           },
           {
                "uniqueId": "12345678901234_RR-INV-0002_388_2022"
           },
           {
                "uniqueId": "12345678901234_RR-INV-0013_388_2022"
           }

    ]
}

Request Body

(With MethodOfGeneration)

Method of generation is an optional field but giving this will help in querying and fetching the details of the invoices faster.

{
    "Invoices": [
           {
                "invoiceNumber": "RR-INV-0001",
                "invoiceType": "INV",
                "issueDate": "2022-08-13",
                "vat": "12345678901234"
           },
           {
                "uniqueId": "12345678901234_RR-INV-0002_388_2022"
           },
           {
                "uniqueId": "12345678901234_RR-INV-0013_388_2022"
           }

    ],
   "methodOfGeneration": "ONLINE"
}

Response Status Codes

HTTP Status Code
Description

200

For successful retrieval

401

If the user is not authenticated for the operation

403

If the user is not authorized for the operation

429

Too many requests

5XX

Unhandled exception

Response Schema

Parameter
Data Type
Field Validations
Description

invoiceNumber

String

Cannot be null

Mandatory.

Invoice number (ID) as per the input.

einvoiceStatus

Object

PENDING / REPORTED / NOT_REPORTED / ACCEPTED_WITH_WARNING /

CLEARED /

NOT_CLEARED

For clearance: CLEARED, NOT_CLEARED, ACCEPTED_WITH_WARNING

For reported: REPORTED, NOT_REPORTED, ACCEPTED_WITH_WARNING

errorCode

String

Can be empty in case of no error

This field is not empty in case of any error at the time of reporting/clearance. Gives the error code for the error. Error source maybe ClearTax/ZATCA.

errorMessage

String

Can be empty in case of no error

Human readable error message in case of any error at the time of reporting/clearance. Error source maybe ClearTax/ZATCA.

Sample Response (Success)

Success - HTTP Status Code - 200

[
    {
        "invoiceNumber": "INVKSA2218811366",
        "einvoiceStatus": "CLEARED",
        "errorCode": "",
        "errorMessage": ""
    }
]
[
    {
         {
         "invoiceNumber": "13",
         "einvoiceStatus": "NOT_REPORTED"
         "errorCode": "BR-KSA-17, BR-CO-15",
         "errorMessage": "Debit and credit note (invoice type code (BT-3) is equal to 383 or 381) must contain the reason (KSA-10) for this invoice type issuing., Invoice total amount with VAT (BT-112) = Invoice total amount without VAT (BT-109) + Invoice total VAT amount (BT-110).",
    }

    }
]

Sample Response (Error)

[
    {
        "invoiceNumber": "RR-INV-0001",
        "einvoiceStatus": "FAILED",
        "errorCode": "300102",
        "errorMessage": "You don't have any data present for the selected Document Details"
    }
]

API Validations

  1. The uniqueIdentifier passed in request params should be valid and must be present in ClearTax datastore.

  2. Four invoice info fields passed to identify the invoice or the UniqueId passed should belong to the user.

API Constraints

  1. This API needs to be authenticated with a valid user authentication token. If the auth token is not present or is invalid, the API will return HTTP Status Code 401.

  2. Each customer is allowed to send a limited number of requests per minute to prevent server overload. If the limit is exceeded, the server will respond with a 429 Too Many Requests status code.

  3. The API will accept only 500 invoices in a single request and the API will allow 10 threads running parallel. Hence, data for 5000 invoices can be requested in parallel.

  4. The API works for only those invoices present in the CT data store.

  5. Plan this API call 1 hour after sending the invoice to ClearTax. If the invoice is still in pending status then plan the subsequent calls 2, 4, 8, 16 and 30 hours. The invoice will have a terminal status as ‘Failed’ max by 30 hours if ZATCA is continuously non-responsive.

  6. If the auth token is valid, but the user does not have the authorization to fetch invoice details, then the API will return HTTP Status Code 403. The user, whose auth token is used, should have an “Admin” role for the particular VAT used in the request.

PreviousSend Signed E-Invoice XML To ZATCANextGet Invoice

Last updated 8 months ago

Was this helpful?

🇸🇦