Documentation Topics
ZATCA Invoice Download API
Comprehensive documentation for downloading ZATCA-compliant invoices from the system
Base URL: /api/InvoiceDownload Token Authentication
Overview
This API provides endpoints to retrieve and download ZATCA-compliant invoices that have been previously uploaded and stored in the system. It supports filtering by various criteria such as date range, document type, and document form.
Key Features
- Retrieve invoices by date range, document type, and document form
- Download specific invoices by invoice number
- Your license token allows yu to download invoices from your tenant
- Comprehensive error handling and validation
- ZATCA-compliant XML and QR code data
Authentication
All API endpoints require JWT (JSON Web Token) authentication. Include the token in the Authorization header of your requests.
Endpoints
Download Invoices by Criteria
Retrieves a list of invoices for a specific tenant and unit, filtered by optional criteria.
GET /api/InvoiceDownload/tenant/{tenantId}/unit/{unitId}
GETURL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
tenantId | string | Yes | The unique identifier for the tenant |
unitId | string | Yes | The unique identifier for the unit/branch |
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
startDate | string | No | Start date for filtering (yyyy-MM-dd) |
endDate | string | No | End date for filtering (yyyy-MM-dd) |
documentTypes | string[] | No | Array of document types (SIMPLIFIED, TAXINVOICE) |
documentForms | string[] | No | Array of document forms (INVOICE, CREDITNOTE, DEBITNOTE) |
Example Request
Example Response (200 OK)
Download a Specific Invoice by Number
Retrieves a single, specific invoice by its unique invoice number for a given tenant and unit.
GET /api/InvoiceDownload/tenant/{tenantId}/unit/{unitId}/invoice/{invoiceNumber}
GETURL Parameters
Parameter | Type | Required | Description |
---|---|---|---|
tenantId | string | Yes | The unique identifier for the tenant |
unitId | string | Yes | The unique identifier for the unit/branch |
invoiceNumber | string | Yes | The unique number of the invoice to retrieve |
Example Request
Example Response (200 OK)
Error Response (404 Not Found)
Data Models
Invoice Object
The Invoice object contains all the details of a ZATCA-compliant invoice.
Field | Type | Description |
---|---|---|
id | integer | Internal unique identifier for the invoice |
invoiceNumber | string | The unique business number for the invoice |
issueDate | string (ISO 8601) | The date and time the invoice was issued |
documentType | string | The ZATCA document type (SIMPLIFIED, TAXINVOICE) |
documentForm | string | The ZATCA document form (INVOICE, CREDITNOTE, DEBITNOTE) |
sellerName | string | The name of the selling party |
totalAmount | number | The total amount of the invoice including tax |
taxAmount | number | The total tax amount on the invoice |
zatcaStatus | string | The status of the invoice in the ZATCA system |
xmlContent | string (Base64) | The full ZATCA-compliant XML representation of the invoice, base64 encoded |
hash | string | The cryptographic hash of the invoice XML |
qrCode | string (Base64) | The QR code image as a base64 encoded string (typically PNG) |
xmlContent
and qrCode
fields are base64 encoded. Clients must decode these values to use them.
Code Examples
JavaScript (Fetch API)
C# (HttpClient)
- >();
Console.WriteLine($"Found {invoices.Count} invoices.");
// Process invoices
}
else
{
Console.WriteLine($"Request failed: {response.StatusCode}");
}
}
}
// Define a class to deserialize the response into
public class Invoice
{
public string InvoiceNumber { get; set; }
public string XmlContent { get; set; }
// ... other properties
}
Response Codes
HTTP Status Code | Description | Possible Reason |
---|---|---|
200 OK | The request was successful | - |
400 Bad Request | The request was malformed | Invalid date format, invalid documentType, invalid documentForm |
401 Unauthorized | Missing or invalid authentication | Missing or invalid JWT token |
404 Not Found | Resource not found | No invoices for the given criteria, invalid tenant/unit ID |
500 Internal Server Error | Server error | Database error, application exception |