Welcome to the system documentation. Select a topic from the sidebar to learn more.

Quick Start

Get up and running quickly with our step-by-step guides.

Get Started

Video Tutorials

Watch our video tutorials to see the system in action.

Watch Videos
ZATCA Invoice Download API Documentation

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.

// Example of including JWT token in a request fetch('https://www.pristineinvoice.com/api/InvoiceDownload/tenant/123/unit/456', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_JWT_TOKEN_HERE', 'Content-Type': 'application/json' } })
To obtain a License token, please refer to the. Signup Documentation.

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}
GET
URL 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
// Get invoices for a specific date range GET /api/InvoiceDownload/tenant/comp_123/unit/branch_456?startDate=2023-10-25&endDate=2023-10-26 // Get simplified tax invoices GET /api/InvoiceDownload/tenant/comp_123/unit/branch_456?documentTypes=SIMPLIFIED&documentForms=INVOICE
Example Response (200 OK)
[ { "id": 1001, "invoiceNumber": "INV-2023-1001", "issueDate": "2023-10-25T14:30:00Z", "documentType": "SIMPLIFIED", "documentForm": "INVOICE", "sellerName": "Company ABC", "totalAmount": 1150.00, "taxAmount": 150.00, "zatcaStatus": "VALID", "xmlContent": "PFNhbGRlc0ludm9pY2UgeG1sbnM9Imh0dHA6Ly9mYXR1cmEuZ292LnNh...", "hash": "a1b2c3d4e5f67890...", "qrCode": "iVBORw0KGgoAAAANSUhEUgAAA..." }, { "id": 1002, "invoiceNumber": "CN-2023-1001", "issueDate": "2023-10-26T10:15:00Z", "documentType": "TAXINVOICE", "documentForm": "CREDITNOTE", "sellerName": "Company ABC", "totalAmount": -500.00, "taxAmount": -65.22, "zatcaStatus": "REPORTED", "xmlContent": "PFNhbGRlc0ludm9pY2UgeG1sbnM9Imh0dHA6Ly9mYXR1cmEuZ292LnNh...", "hash": "z9y8x7w6v5u4t3...", "qrCode": "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAMAAAAoLQ9TAAAABlBMVEX///8AAABVwtN+AAABM0lEQVR4Xm..." } ]

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}
GET
URL 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
GET /api/InvoiceDownload/tenant/comp_123/unit/branch_456/invoice/INV-2023-1001
Example Response (200 OK)
{ "id": 1001, "invoiceNumber": "INV-2023-1001", "issueDate": "2023-10-25T14:30:00Z", "documentType": "SIMPLIFIED", "documentForm": "INVOICE", "sellerName": "Company ABC", "totalAmount": 1150.00, "taxAmount": 150.00, "zatcaStatus": "VALID", "xmlContent": "PFNhbGRlc0ludm9pY2UgeG1sbnM9Imh0dHA6Ly9mYXR1cmEuZ292LnNh...", "hash": "a1b2c3d4e5f67890...", "qrCode": "iVBORw0KGgoAAAANSUhEUgAAA..." }
Error Response (404 Not Found)
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found", "status": 404, "detail": "Invoice with number INV-2023-9999 not found for the specified unit and tenant.", "traceId": "00-1234567890abcdef1234567890abcdef-9876543210fedcba-00" }

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)
The xmlContent and qrCode fields are base64 encoded. Clients must decode these values to use them.

Code Examples

JavaScript (Fetch API)
// Fetch invoices from a specific date range const tenantId = 'comp_123'; const unitId = 'branch_456'; const authToken = 'your_jwt_token_here'; async function fetchInvoicesByDate() { const url = `https://www.pristineinvoice.com/api/InvoiceDownload/tenant/${tenantId}/unit/${unitId}?startDate=2023-10-01&endDate=2023-10-31`; const response = await fetch(url, { method: 'GET', headers: { 'Authorization': `Bearer ${authToken}` } }); if (response.ok) { const invoices = await response.json(); console.log('Fetched Invoices:', invoices); // Decode and use the base64 XML or QR code // const xmlString = atob(invoices[0].xmlContent); } else { console.error('Error:', response.status, await response.text()); } } // Fetch a single invoice async function fetchSingleInvoice() { const invoiceNumber = 'INV-2023-1001'; const url = `https://www.pristineinvoice.com/api/InvoiceDownload/tenant/${tenantId}/unit/${unitId}/invoice/${invoiceNumber}`; const response = await fetch(url, { method: 'GET', headers: { 'Authorization': `Bearer ${authToken}` } }); if (response.ok) { const invoice = await response.json(); console.log('Fetched Invoice:', invoice); } else { console.error('Error:', response.status); } }
C# (HttpClient)
using System; using System.Net.Http; using System.Threading.Tasks; public class InvoiceDownloadService { private readonly HttpClient _httpClient; private readonly string _baseUrl = "https://www.pristineinvoice.com/api/InvoiceDownload"; private readonly string _authToken = "your_jwt_token_here"; public InvoiceDownloadService(HttpClient httpClient) { _httpClient = httpClient; _httpClient.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", _authToken); } public async Task GetInvoicesAsync() { string url = $"{_baseUrl}/tenant/comp_123/unit/branch_456?startDate=2023-10-01&endDate=2023-10-31"; HttpResponseMessage response = await _httpClient.GetAsync(url); if (response.IsSuccessStatusCode) { var invoices = await response.Content.ReadAsAsync>(); 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

ZATCA Invoice Download API Documentation

© 2023 Your Company Name. All rights reserved.

}