KSA Examples
Saudi Arabia (KSA) Implementation Examples
Complete ZATCA-compliant examples using the canonical GETS structure. Includes both the final GETS JSON format and Java SDK payload examples. All examples provide 100% field coverage for KSA requirements with bilingual support (English/Arabic).
ZATCA Compliant
Phase 2 Ready
Bilingual Support
Arabic & English
10 Document Types
Complete Coverage
Available Document Types
All KSA document types with GETS canonical structure
B2B Tax Invoice
Business-to-business standard invoice
B2C Simplified Invoice
Business-to-consumer simplified invoice
B2B Credit Note
Business credit note document
B2C Credit Note
Consumer credit note document
B2B Debit Note
Business debit note document
B2C Debit Note
Consumer debit note document
B2B Prepayment Invoice
Prepayment invoice for B2B transactions
B2C Prepayment Invoice
Prepayment and adjusted invoices
Complete GETS Examples
Ready-to-use examples with full GETS structure and KSA compliance
B2B Tax Invoice
Most Popular
Standard business-to-business tax invoice with all required KSA fields, bilingual descriptions, and GETS canonical structure.
{
"header": {
"invoiceId": "INV-2024-001",
"issueDate": "2024-06-01",
"issueTime": "10:00:00Z",
"dueDate": "2024-06-15",
"documentCurrency": "SAR",
"supplyStartDate": "2024-06-01",
"supplyEndDate": "2024-06-30",
"documentType": "tax_invoice"
},
"parties": {
"seller": {
"name": { "en": "Acme Trading LLC", "ar": "شركة اكمي للتجارة" },
"identifications": [
{ "id": "310122393500003", "schemeId": "CRN" }
],
"taxSchemes": [
{ "companyId": "310122393500003", "taxScheme": { "id": "VAT" } }
],
"postalAddress": {
"streetName": { "en": "123 King Fahd Rd", "ar": "١٢٣ طريق الملك فهد" },
"buildingNumber": "1234",
"cityName": { "en": "Riyadh", "ar": "الرياض" },
"district": { "en": "Olaya", "ar": "العليا" },
"postalZone": "11564",
"country": { "identificationCode": "SA" }
}
},
"buyer": {
"name": { "en": "Global Imports Inc.", "ar": "شركة الاستيراد العالمية" },
"identifications": [
{ "id": "310122393500004", "schemeId": "CRN" }
],
"taxSchemes": [
{ "companyId": "310122393500004", "taxScheme": { "id": "VAT" } }
],
"postalAddress": {
"streetName": { "en": "456 Olaya St", "ar": "٤٥٦ شارع العليا" },
"buildingNumber": "5678",
"cityName": { "en": "Jeddah", "ar": "جدة" },
"district": { "en": "Al Hamra", "ar": "الحمرا" },
"postalZone": "22233",
"country": { "identificationCode": "SA" }
}
}
},
"items": [
{
"id": "1",
"description": { "en": "Premium Widget", "ar": "أداة مميزة" },
"quantity": 5,
"unitCode": "PCS",
"unitPrice": 100.00,
"taxTotal": { "taxAmount": 75.00 },
"item": {
"name": { "en": "Premium Widget", "ar": "أداة مميزة" },
"classifiedTaxCategory": {
"id": "S",
"percent": 15,
"taxScheme": { "id": "VAT" },
"taxExemptionReasonCode": "E1",
"taxExemptionReason": "Export of goods"
}
},
"discountPerUnit": 5.00,
"lineExtensionAmount": 500.00,
"netLineExtensionAmount": 475.00
}
],
"taxTotals": [
{
"taxAmount": 75.00,
"taxSubtotal": [
{
"taxableAmount": 500.00,
"taxAmount": 75.00,
"taxCategory": {
"id": "S",
"percent": 15,
"taxScheme": { "id": "VAT" }
}
}
]
}
],
"legalMonetaryTotal": {
"lineExtensionAmount": 500.00,
"taxExclusiveAmount": 500.00,
"taxInclusiveAmount": 575.00,
"payableAmount": 575.00,
"vatTotalAmount": 75.00
},
"meta": {
"customFields": {
"sa_isSimplifiedInvoice": false
}
}
}KSA-Specific Features
All examples include these essential KSA requirements
Required Fields
- Bilingual descriptions (English/Arabic)
- Supply start/end dates
- VAT total amounts
- Discount per unit calculations
- Line extension amounts
ZATCA Compliance
- Phase 2 integration ready
- VAT exemption reason codes
- Building numbers and postal codes
- District names in Arabic
- Custom fields for simplified invoices
Implementation Guide
How to use these examples in your application
1. Choose the Right LogicalDocType
// B2B Tax Invoices LogicalDocType.TAX_INVOICE // Standard B2B invoice LogicalDocType.TAX_INVOICE_CREDIT_NOTE // B2B credit note LogicalDocType.TAX_INVOICE_DEBIT_NOTE // B2B debit note LogicalDocType.TAX_INVOICE_PREPAYMENT // B2B prepayment LogicalDocType.TAX_INVOICE_EXPORT_INVOICE // B2B export invoice // B2C Simplified Invoices LogicalDocType.SIMPLIFIED_TAX_INVOICE // Standard B2C invoice LogicalDocType.SIMPLIFIED_TAX_INVOICE_CREDIT_NOTE // B2C credit note LogicalDocType.SIMPLIFIED_TAX_INVOICE_DEBIT_NOTE // B2C debit note // Special Cases LogicalDocType.TAX_INVOICE_THIRD_PARTY_INVOICE // Third party billing LogicalDocType.TAX_INVOICE_SELF_BILLED_INVOICE // Self-billed invoice LogicalDocType.TAX_INVOICE_NOMINAL_SUPPLY_INVOICE // Nominal supply LogicalDocType.TAX_INVOICE_SUMMARY_INVOICE // Summary invoice
Automatic Configuration: LogicalDocType automatically sets the correct meta.config flags (isB2B, documentType, etc.) and maps to the appropriate GETS structure. No manual flag setting required!
2. Submit via Java SDK
// Configure SDK
Source source = new Source("example-source", "1.1", SourceType.FIRST_PARTY);
SDKConfig config = new SDKConfig(
"ak_5ddc725b240f9fa39a336e65ceb4",
Environment.SANDBOX,
Arrays.asList(source)
);
GETSUnifySDK.configure(config);
// Create payload from KSA examples above
Map<String, Object> payload = createKSAInvoicePayload();
// Submit using LogicalDocType
UnifyResponse response = GETSUnifySDK.pushToUnify(
"example-source", // Source name
"1.1", // Source version
LogicalDocType.TAX_INVOICE, // B2B Tax Invoice
Country.SA, // Saudi Arabia
Operation.SINGLE, // Single document
Mode.DOCUMENTS, // Document mode
Purpose.INVOICING, // Full invoicing flow
payload // Business data
);Java SDK Payload Examples
Real payload structures from LogicalDocumentTypeFlowSample.java that work with the current Java SDK
Java Map structure for B2B Tax Invoice using LogicalDocType.TAX_INVOICE
Map<String, Object> payload = new HashMap<>();
// Invoice Data - Maps to GETS header fields
Map<String, Object> invoiceData = new HashMap<>();
invoiceData.put("invoice_number", "RETRTTESTNEW1124");
invoiceData.put("invoice_date", "2025-09-04");
invoiceData.put("invoice_time", "14:30:00");
invoiceData.put("currency_code", "SAR");
invoiceData.put("total_amount", 23000.00);
invoiceData.put("total_payable_amount", 23000.00);
invoiceData.put("tax_exclusive_amount", 20000.00);
invoiceData.put("line_extension_amount", 20000.00);
invoiceData.put("total_tax_amount", 3000.00);
payload.put("invoice_data", invoiceData);
// Seller Info - Maps to GETS seller party fields
Map<String, Object> sellerInfo = new HashMap<>();
sellerInfo.put("company_name", "Advanced Tech Solutions LLC");
sellerInfo.put("vat_registration", "310123456700003");
sellerInfo.put("tax_scheme", "VAT");
sellerInfo.put("street_address", "King Fahd Road");
sellerInfo.put("building_number", "1234");
sellerInfo.put("district_name", "Al Olaya");
sellerInfo.put("city_name", "Riyadh");
sellerInfo.put("postal_code", "11564");
sellerInfo.put("country_code", "SA");
sellerInfo.put("phone", "+966501234567");
sellerInfo.put("email", "contact@advancedtech.sa");
payload.put("seller_info", sellerInfo);
// Buyer Info - Maps to GETS buyer party fields
Map<String, Object> buyerInfo = new HashMap<>();
buyerInfo.put("buyer_name", "Global Manufacturing Co.");
buyerInfo.put("buyer_vat", "310987654300003");
buyerInfo.put("buyer_address", "Industrial City");
buyerInfo.put("buyer_building", "4567");
buyerInfo.put("buyer_district", "Industrial Area");
buyerInfo.put("buyer_city", "Dammam");
buyerInfo.put("buyer_postal", "31461");
buyerInfo.put("buyer_country", "SA");
payload.put("buyer_info", buyerInfo);