Documentation Topics
Quick Start Guide
Signup & Account Management
Free Tenant & Subscriptions
Add EGS Unit
Reporting Simplified Invoice
C# Code Samples of Reporting Api
Python Code Samples of Reporting Api
Clearing Standard Invoice
C# Code Samples of Clearing Api
Python Code Samples of Clearing Api
Additional Zatca Utiilities
Add Customers
Download Invoices
Subscriptions and License aqusition
Welcome to the system documentation. Select a topic from the sidebar to learn more.
Python Code Samples of Reporting Api - Documentation
About These Samples- Sample 01
This page demonstrates various ZATCA simplified invoice reporting scenarios with ready-to-use JSON samples. Additionally, we provided Python code to implement each scenario
Basic Simplified Invoice
A minimal simplified invoice with one standard-rated item (15% VAT).
{
"UnitId": "TST-C22FF20EFD-DIANA152",
"InvoiceNo": "000102",
"DocType": "SIMPLIFIED",
"DocForm": "INVOICE",
"IssueDate": "2025-08-14",
"IssueTime": "18:00:00",
"DocCurrency": "SAR",
"PaymentMethod": "Cash",
"CustomerName": "Cash Customer",
"InvoiceLines": [
{
"LineNo": 1,
"ItemName": "Laptop Dell Latitude E5450",
"Quantity": 1,
"UnitCode": "NOS",
"TaxCategory": "S",
"TaxRate": 15,
"ItemPrice": 750,
"Currency": "SAR"
}
]
}Invoice with Document-Level Allowances-Sample 02
An invoice with document-level discounts and charges applied to the total amount.
{
"UnitId": "TST-C22FF20EFD-DIANA152",
"InvoiceNo": "INV-2023-002",
"DocType": "SIMPLIFIED",
"DocForm": "INVOICE",
"Note": "Invoice with document-level allowances",
"IssueDate": "2025-08-14",
"IssueTime": "18:05:00",
"DocCurrency": "SAR",
"PaymentMethod": "CreditCard",
"CustomerName": "Cash Customer",
"AllowanceCharges": [
{
"Type": "ALLOWANCE",
"Reason": "Seasonal Discount",
"Amount": 50.00,
"TaxRate": 15.00,
"TaxCategory": "S"
},
{
"Type": "CHARGE",
"Reason": "Delivery Fee",
"Amount": 20.00,
"TaxRate": 15.00,
"TaxCategory": "S"
}
],
"InvoiceLines": [
{
"LineNo": 1,
"ItemName": "Premium Laptop",
"Quantity": 2,
"UnitCode": "NOS",
"TaxCategory": "S",
"TaxRate": 15,
"ItemPrice": 2500,
"Currency": "SAR"
}
]
}Mixed Tax Categories Invoice- Sample 03
An invoice containing items with different tax categories (Standard, Zero-rated, and Exempt).
{
"UnitId": "TST-C22FF20EFD-DIANA152",
"InvoiceNo": "INV-2023-003",
"DocType": "SIMPLIFIED",
"DocForm": "INVOICE",
"IssueDate": "2025-08-14",
"IssueTime": "18:45:00",
"DocCurrency": "SAR",
"PaymentMethod": "BankTransfer",
"CustomerName": "Cash Customer",
"InvoiceLines": [
{
"LineNo": 1,
"ItemName": "Consulting Services",
"Quantity": 10,
"UnitCode": "HUR",
"TaxCategory": "S",
"TaxRate": 15,
"ItemPrice": 200,
Currency = "SAR",
VatExemptionCode = "VATEX-SA-34-4",
VatExemptionReason = "Supply of a qualifying means of transport"
},
{
"LineNo": 2,
"ItemName": "Export Goods",
"Quantity": 2,
"UnitCode": "BOX",
"TaxCategory": "Z",
"TaxRate": 0,
"ItemPrice": 500,
"Currency": "SAR"
},
{
"LineNo": 3,
"ItemName": "Educational Books",
"Quantity": 15,
"UnitCode": "PCE",
"TaxCategory": "E",
"TaxRate": 0,
"ItemPrice": 50,
"Currency": "SAR",
"VatExemptionCode": "VATEX-SA-EDU",
"VatExemptionReason": "Educational materials exempt under VAT regulations"
}
]
}Credit Note with Reference - Sample 04
A credit note referencing the original invoice being credited.
{
"UnitId": "TST-C22FF20EFD-DIANA152",
"InvoiceNo": "CN-2023-004",
"DocType": "SIMPLIFIED",
"DocForm": "CREDITNOTE",
"Note": "Return of defective goods",
"IssueDate": "2025-08-14",
"IssueTime": "18:50:00",
"DocCurrency": "SAR",
"PaymentMethod": "Credit",
"CustomerName": "Cash Customer",
"PreviousInvoiceRef": "INV-2023-045",
"InvoiceLines": [
{
"LineNo": 1,
"ItemName": "Defective Smartphone",
"Quantity": 1,
"UnitCode": "PCE",
"TaxCategory": "S",
"TaxRate": 15,
"ItemPrice": 1200,
"Currency": "SAR"
}
]
}Debit Note with Reference - Sample 05
A debit note referencing the original invoice being debited.
{
"UnitId": "TST-C22FF20EFD-DIANA152",
"InvoiceNo": "DN-2023-005",
"DocType": "SIMPLIFIED",
"DocForm": "DEBITNOTE",
"Note": "Return of defective goods",
"IssueDate": "2025-08-14",
"IssueTime": "18:53:00",
"DocCurrency": "SAR",
"PaymentMethod": "DebitTransfer",
"CustomerName": "Cash Customer",
"PreviousInvoiceRef": "INV-2023-045",
"InvoiceLines": [
{
"LineNo": 1,
"ItemName": "Smartphone",
"Quantity": 1,
"UnitCode": "PCE",
"TaxCategory": "S",
"TaxRate": 15,
"ItemPrice": 1200,
"Currency": "SAR"
}
]
}Invoice with Line-Level Allowances - Sample 06
An invoice with discounts applied at the line-item level.
{
"UnitId": "TST-C22FF20EFD-DIANA152",
"InvoiceNo": "INV-2023-006",
"DocType": "SIMPLIFIED",
"DocForm": "INVOICE",
"IssueDate": "2025-08-14",
"IssueTime": "18:56:00",
"DocCurrency": "SAR",
"PaymentMethod": "Cash",
"CustomerName": "Cash Customer",
"InvoiceLines": [
{
"LineNo": 1,
"ItemName": "Office Chair",
"Quantity": 5,
"UnitCode": "PCE",
"TaxCategory": "S",
"TaxRate": 15,
"ItemPrice": 300,
"Currency": "SAR",
"AllowanceCharges": [
{
"Type": "ALLOWANCE",
"Reason": "Volume discount",
"Amount": 50
},
{
"Type": "ALLOWANCE",
"Reason": "Promotional discount",
"Amount": 25
}
]
}
]
}Sample with full json attrbutes set - Sample 07
This sample was not implemented in code. given here for your reference only
{
"UnitId": "TST-C22FF20EFD-DIANA152",
"InvoiceNo": "000101",
"DocType": "SIMPLIFIED",
"DocForm": "INVOICE",
"Note": "Direct Customer Sale",
"IssueDate": "2025-07-17",
"IssueTime": "03:06:14",
"DocCurrency": "SAR",
"ActualDelivery": "2025-07-17",
"LatestDelivery": "2025-07-17",
"PaymentMethod": "Cash",
"CustomerName": "Cash Customer",
"PreviousInvoiceRef": "INV-00020",
"AllowanceCharges": [
{
"Type": "ALLOWANCE",
"Reason": "Seasonal Discount",
"Amount": 1,
"TaxRate": 15,
"TaxCategory": "S"
},
{
"Type": "CHARGE",
"Reason": "Shipping Charge",
"Amount": 2,
"TaxRate": 15,
"TaxCategory": "S"
}
],
"InvoiceLines": [
{
"LineNo": 1,
"ItemName": "Documentation Charges",
"Quantity": 1,
"UnitCode": "NOS",
"TaxCategory": "E",
"TaxRate": 0,
"ItemPrice": 750,
"Currency": "SAR",
"BaseQuantity": 1,
"BaseUnitCode": "NOS",
"VatExemptionCode": "VATEX-SA-29",
"VatExemptionReason": "Financial services mentioned in Article 29 of the VAT Regulations",
"AllowanceCharges": [
{
"Type": "ALLOWANCE",
"Reason": "stock clearance",
"Amount": 5
}
]
},
{
"LineNo": 2,
"ItemName": "Laptop Dell Latitude E5450",
"Quantity": 1,
"UnitCode": "NOS",
"TaxCategory": "S",
"TaxRate": 15,
"ItemPrice": 850,
"Currency": "SAR",
"BaseQuantity": 1,
"BaseUnitCode": "NOS",
"AllowanceCharges": [
{
"Type": "CHARGE",
"Reason": "shipping charge",
"Amount": 5
}
]
}
],
"PrePayments": [
{
"Amount": 10,
"Quantity": 1,
"UnitCode": "PCE",
"ItemName": "Laptop Charger",
"TaxCategory": "S",
"Rate": "15",
"Currency": "SAR",
"BaseQuantity": 1,
"BaseUnit": "PCE",
"PrePaidInvoiceNo": "000454",
"PrePaidInvoiceIssueDate": "2025-07-17",
"PrePaidInvoiceIssueTime": "06:08:14"
}
]
}Python Code samples
Input and Output Data Classes
Samples provide all necessary classes to implement invoice objects
from dataclasses import dataclass, field
from typing import List, Optional
import datetime
import requests
import json
@dataclass
class InvoiceAllowanceChargeDto:
Type: str
Reason: str
Amount: float
TaxRate: float = 0.0
TaxCategory: str = ""
@dataclass
class InvoiceLineAllowanceChargeDto:
Type: str
Reason: str
Amount: float
@dataclass
class InvoiceLineDto:
LineNo: int
ItemName: str
Quantity: float
UnitCode: str
TaxCategory: str
TaxRate: float
ItemPrice: float
Currency: str
BaseQuantity: float = 1.0
BaseUnitCode: str = ""
VatExemptionCode: str = ""
VatExemptionReason: str = ""
AllowanceCharges: List[InvoiceLineAllowanceChargeDto] = field(default_factory=list)
@dataclass
class PrePaymentsDto:
Amount: float
Quantity: float
UnitCode: str
ItemName: str
TaxCategory: str
Rate: str
Currency: str
BaseQuantity: float
BaseUnit: str
PrePaidInvoiceNo: str
PrePaidInvoiceIssueDate: str
PrePaidInvoiceIssueTime: str
@dataclass
class SimplifiedInvoiceDto:
UnitId: str
InvoiceNo: str
DocType: str
DocForm: str
IssueDate: str
IssueTime: str
DocCurrency: str
PaymentMethod: str
CustomerName: str
Note: str = ""
ActualDelivery: str = ""
LatestDelivery: str = ""
PreviousInvoiceRef: str = ""
AllowanceCharges: List[InvoiceAllowanceChargeDto] = field(default_factory=list)
InvoiceLines: List[InvoiceLineDto] = field(default_factory=list)
PrePayments: List[PrePaymentsDto] = field(default_factory=list)
@dataclass
class ZatcaApiResponse:
Status: str
Message: str
Icv: str = ""
Hash: str = ""
Uuid: str = ""
QrCodeValue: str = ""Sample code of creating Invoice objects in each scenario
class ZatcaApiClient:
def __init__(self, base_url: str, jwt_token: str):
self.base_url = base_url
self.jwt_token = jwt_token
self.session = requests.Session()
self.session.headers.update({
"Authorization": f"Bearer {self.jwt_token}",
"Content-Type": "application/json"
})
def report_simplified_invoice(self, invoice: SimplifiedInvoiceDto) -> ZatcaApiResponse:
endpoint = f"{self.base_url}/api/ZatcaIntegration/ReportInvoice"
response = self.session.post(endpoint, json=self._to_dict(invoice))
if not response.ok:
raise Exception(f"API call failed with status code {response.status_code}. Response: {response.text}")
return ZatcaApiResponse(**response.json())
def _to_dict(self, obj):
if hasattr(obj, "__dataclass_fields__"):
return {k: self._to_dict(v) for k, v in obj.__dict__.items() if not k.startswith('_')}
elif isinstance(obj, list):
return [self._to_dict(item) for item in obj]
else:
return obj
# Sample invoice creation methods – Sample 01
def create_basic_invoice(self) -> SimplifiedInvoiceDto:
now = datetime.datetime.now()
return SimplifiedInvoiceDto(
UnitId="TST-C22FF20EFD-DIANA152",
InvoiceNo="000102",
DocType="SIMPLIFIED",
DocForm="INVOICE",
IssueDate=now.strftime("%Y-%m-%d"),
IssueTime=now.strftime("%H:%M:%S"),
DocCurrency="SAR",
PaymentMethod="Cash",
CustomerName="Cash Customer",
InvoiceLines=[
InvoiceLineDto(
LineNo=1,
ItemName="Laptop Dell Latitude E5450",
Quantity=1,
UnitCode="NOS",
TaxCategory="S",
TaxRate=15,
ItemPrice=750,
Currency="SAR"
)
]
)
# Sample invoice creation methods – Sample 02
def create_invoice_with_document_allowances(self) -> SimplifiedInvoiceDto:
now = datetime.datetime.now()
return SimplifiedInvoiceDto(
UnitId="TST-C22FF20EFD-DIANA152",
InvoiceNo="INV-2023-002",
DocType="SIMPLIFIED",
DocForm="INVOICE",
Note="Invoice with document-level allowances",
IssueDate=now.strftime("%Y-%m-%d"),
IssueTime=now.strftime("%H:%M:%S"),
DocCurrency="SAR",
PaymentMethod="CreditCard",
CustomerName="Cash Customer",
AllowanceCharges=[
InvoiceAllowanceChargeDto(
Type="ALLOWANCE",
Reason="Seasonal Discount",
Amount=50.00,
TaxRate=15.00,
TaxCategory="S"
),
InvoiceAllowanceChargeDto(
Type="CHARGE",
Reason="Delivery Fee",
Amount=20.00,
TaxRate=15.00,
TaxCategory="S"
)
],
InvoiceLines=[
InvoiceLineDto(
LineNo=1,
ItemName="Premium Laptop",
Quantity=2,
UnitCode="NOS",
TaxCategory="S",
TaxRate=15,
ItemPrice=2500,
Currency="SAR"
)
]
)
# Sample invoice creation methods – Sample 03
def create_mixed_tax_invoice(self) -> SimplifiedInvoiceDto:
now = datetime.datetime.now()
return SimplifiedInvoiceDto(
UnitId="TST-C22FF20EFD-DIANA152",
InvoiceNo="INV-2023-003",
DocType="SIMPLIFIED",
DocForm="INVOICE",
IssueDate=now.strftime("%Y-%m-%d"),
IssueTime=now.strftime("%H:%M:%S"),
DocCurrency="SAR",
PaymentMethod="BankTransfer",
CustomerName="Cash Customer",
InvoiceLines=[
InvoiceLineDto( # Standard rated
LineNo=1,
ItemName="Consulting Services",
Quantity=10,
UnitCode="HUR",
TaxCategory="S",
TaxRate=15,
ItemPrice=200,
Currency="SAR"
),
InvoiceLineDto( # Zero-rated
LineNo=2,
ItemName="Export Goods",
Quantity=2,
UnitCode="BOX",
TaxCategory="Z",
TaxRate=0,
ItemPrice=500,
Currency="SAR"
),
InvoiceLineDto( # Exempt
LineNo=3,
ItemName="Educational Books",
Quantity=15,
UnitCode="PCE",
TaxCategory="E",
TaxRate=0,
ItemPrice=50,
Currency="SAR",
VatExemptionCode="VATEX-SA-EDU",
VatExemptionReason="Educational materials exempt under VAT regulations"
)
]
)
# Sample invoice creation methods – Sample 04
def create_credit_note(self) -> SimplifiedInvoiceDto:
now = datetime.datetime.now()
return SimplifiedInvoiceDto(
UnitId="TST-C22FF20EFD-DIANA152",
InvoiceNo="CN-2023-004",
DocType="SIMPLIFIED",
DocForm="CREDITNOTE",
Note="Return of defective goods",
IssueDate=now.strftime("%Y-%m-%d"),
IssueTime=now.strftime("%H:%M:%S"),
DocCurrency="SAR",
PaymentMethod="Credit",
CustomerName="Cash Customer",
PreviousInvoiceRef="INV-2023-045",
InvoiceLines=[
InvoiceLineDto(
LineNo=1,
ItemName="Defective Smartphone",
Quantity=1,
UnitCode="PCE",
TaxCategory="S",
TaxRate=15,
ItemPrice=1200,
Currency="SAR"
)
]
)
# Sample invoice creation methods – Sample 05
def create_debit_note(self) -> SimplifiedInvoiceDto:
now = datetime.datetime.now()
return SimplifiedInvoiceDto(
UnitId="TST-C22FF20EFD-DIANA152",
InvoiceNo="DN-2023-005",
DocType="SIMPLIFIED",
DocForm="DEBITNOTE",
Note="Return of defective goods",
IssueDate=now.strftime("%Y-%m-%d"),
IssueTime=now.strftime("%H:%M:%S"),
DocCurrency="SAR",
PaymentMethod="DebitTransfer",
CustomerName="Cash Customer",
PreviousInvoiceRef="INV-2023-045",
InvoiceLines=[
InvoiceLineDto(
LineNo=1,
ItemName="Smartphone",
Quantity=1,
UnitCode="PCE",
TaxCategory="S",
TaxRate=15,
ItemPrice=1200,
Currency="SAR"
)
]
)
# Sample invoice creation methods – Sample 06
def create_invoice_with_line_allowances(self) -> SimplifiedInvoiceDto:
now = datetime.datetime.now()
return SimplifiedInvoiceDto(
UnitId="TST-C22FF20EFD-DIANA152",
InvoiceNo="INV-2023-006",
DocType="SIMPLIFIED",
DocForm="INVOICE",
IssueDate=now.strftime("%Y-%m-%d"),
IssueTime=now.strftime("%H:%M:%S"),
DocCurrency="SAR",
PaymentMethod="Cash",
CustomerName="Cash Customer",
InvoiceLines=[
InvoiceLineDto(
LineNo=1,
ItemName="Office Chair",
Quantity=5,
UnitCode="PCE",
TaxCategory="S",
TaxRate=15,
ItemPrice=300,
Currency="SAR",
AllowanceCharges=[
InvoiceLineAllowanceChargeDto(
Type="ALLOWANCE",
Reason="Volume discount",
Amount=50
),
InvoiceLineAllowanceChargeDto(
Type="ALLOWANCE",
Reason="Promotional discount",
Amount=25
)
]
)
]
)
# Sample invoice creation methods – Sample 07
def create_invoice_with_prepayments_and_mixed_items(self) -> SimplifiedInvoiceDto:
return SimplifiedInvoiceDto(
UnitId="TST-C22FF20EFD-DIANA152",
InvoiceNo="000101",
DocType="SIMPLIFIED",
DocForm="INVOICE",
Note="Direct Customer Sale",
IssueDate="2025-07-17",
IssueTime="03:06:14",
DocCurrency="SAR",
ActualDelivery="2025-07-17",
LatestDelivery="2025-07-17",
PaymentMethod="Cash",
CustomerName="Cash Customer",
PreviousInvoiceRef="INV-00020",
AllowanceCharges=[
InvoiceAllowanceChargeDto(
Type="ALLOWANCE",
Reason="Seasonal Discount",
Amount=1,
TaxRate=15,
TaxCategory="S"
),
InvoiceAllowanceChargeDto(
Type="CHARGE",
Reason="Shipping Charge",
Amount=2,
TaxRate=15,
TaxCategory="S"
)
],
InvoiceLines=[
InvoiceLineDto(
LineNo=1,
ItemName="Documentation Charges",
Quantity=1,
UnitCode="NOS",
TaxCategory="E",
TaxRate=0,
ItemPrice=750,
Currency="SAR",
BaseQuantity=1,
BaseUnitCode="NOS",
VatExemptionCode="VATEX-SA-29",
VatExemptionReason="Financial services mentioned in Article 29 of the VAT Regulations",
AllowanceCharges=[
InvoiceLineAllowanceChargeDto(
Type="ALLOWANCE",
Reason="stock clearance",
Amount=5
)
]
),
InvoiceLineDto(
LineNo=2,
ItemName="Laptop Dell Latitude E5450",
Quantity=1,
UnitCode="NOS",
TaxCategory="S",
TaxRate=15,
ItemPrice=850,
Currency="SAR",
BaseQuantity=1,
BaseUnitCode="NOS",
AllowanceCharges=[
InvoiceLineAllowanceChargeDto(
Type="CHARGE",
Reason="shipping charge",
Amount=5
)
]
)
],
PrePayments=[
PrePaymentsDto(
Amount=10,
Quantity=1,
UnitCode="PCE",
ItemName="Laptop Charger",
TaxCategory="S",
Rate="15",
Currency="SAR",
BaseQuantity=1,
BaseUnit="PCE",
PrePaidInvoiceNo="000454",
PrePaidInvoiceIssueDate="2025-07-17",
PrePaidInvoiceIssueTime="06:08:14"
)
]
)Code samples of calling Simplified invoice reporting API's
async def main():
api_base_url = "https://www.pristineinvoice.com"
jwt_token = "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6ImRpYW5hZ3VuYXdhcmRhbmEiLCJuYW1laWQiOiI5YzcxMzk1YS03ODBjLTQwOWYtYmYxNy01MDhlMzFkMDEwM2UiLCJlbWFpbCI6ImRpYW5hZ3VuYXdhcmRhbmFAZ21haWwuY29tIiwiVGVuYW50SWQiOiJDMjJGRjIwRUZEIiwiUHJvZHVjdCI6IlN1YnNjcmlwdGlvbiIsIm5iZiI6MTc1NDc4NTEzMywiZXhwIjoxNzU3NDYzNTMzLCJpYXQiOjE3NTQ3ODUxMzMsImlzcyI6Imh0dHBzOi8vd3d3LnByaXN0aW5laW52b2ljZS5jb20iLCJhdWQiOiJodHRwczovL3d3dy5wcmlzdGluZWludm9pY2UuY29tIn0.t1fV5Jh_3ZkMJo8_parPphuxiwgs5PHgdPNWpZz77HsLutUFYJP1rENF17y9UoGFdZyIIPFhk6Sf-DaF3FjVUw"
zatca_client = ZatcaApiClient(api_base_url, jwt_token)
try:
# Example 1: Basic invoice
basic_invoice = zatca_client.create_basic_invoice()
basic_response = zatca_client.report_simplified_invoice(basic_invoice)
print(f"Basic invoice reported. UUID: {basic_response.Status}\nMessage: {basic_response.Message}")
# Example 2: Invoice with document allowances
allowance_invoice = zatca_client.create_invoice_with_document_allowances()
allowance_response = zatca_client.report_simplified_invoice(allowance_invoice)
print(f"Allowance invoice reported. QR Code: {allowance_response.QrCodeValue}\nMessage: {basic_response.Message}")
# Example 3: Mixed tax invoice
mixed_tax_invoice = zatca_client.create_mixed_tax_invoice()
mixed_tax_response = zatca_client.report_simplified_invoice(mixed_tax_invoice)
print(f"Mixed tax invoice reported. Hash: {mixed_tax_response.Hash}\nMessage: {basic_response.Message}")
# Example 4: Credit note
credit_note = zatca_client.create_credit_note()
credit_note_response = zatca_client.report_simplified_invoice(credit_note)
print(f"Credit note reported. ICV: {credit_note_response.Icv}\nMessage: {basic_response.Message}")
# Example 5: Debit note
debit_note = zatca_client.create_debit_note()
debit_note_response = zatca_client.report_simplified_invoice(debit_note)
print(f"Credit note reported. ICV: {debit_note_response.Icv}\nMessage: {basic_response.Message}")
# Example 6: Invoice with line allowances
line_allowance_invoice = zatca_client.create_invoice_with_line_allowances()
line_allowance_response = zatca_client.report_simplified_invoice(line_allowance_invoice)
print(f"Line allowance invoice reported. Status: {line_allowance_response.Status}\nMessage: {basic_response.Message}")
# Example 7: Invoice with All attributes
# sample code to show all the attributes of the invoice
except Exception as ex:
print(f"Error: {ex}")
if __name__ == "__main__":
import asyncio
asyncio.run(main())