Your API Key
Keep your API key secure and never share it
Getting Started
Dawal Connect API enables businesses in Saudi Arabia to generate and submit electronic invoices that comply with ZATCA (General Authority of Zakat, Tax and Customs - هيئة الزكاة والضريبة والجمارك) requirements. Our API supports both ZATCA Phase 1 (Generation Phase) and ZATCA Phase 2 (Integration Phase) compliance standards.
About ZATCA
ZATCA (هيئة الزكاة والضريبة والجمارك) is the General Authority of Zakat, Tax and Customs in Saudi Arabia. All businesses are required to issue electronic invoices that comply with ZATCA standards.
ZATCA Phase 1 (Generation Phase): Businesses must generate and store compliant tax invoices electronically with mandatory fields and QR codes for simplified invoices.
ZATCA Phase 2 (Integration Phase): Businesses must integrate with ZATCA's Fatoora platform, use cryptographic digital signatures, and transmit invoices in real-time to ZATCA for validation.
Playground — Try it out below uses mock responses only. Base URL and API keys are provided when you get the product. Contact us for production access.
Authentication
All requests require authentication using your API key in the request header:
Authorization: Bearer YOUR_API_KEYAuthentication
All API requests require authentication using an API key. Add the key in the request header.
Login and get a token to access the API
Request Body:
{
"email": "user@example.com",
"password": "your_password"
}Response:
{
"success": true,
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_in": 3600,
"api_key": "sk_live_xxxxxxxxxxxxx"
}
}Test Endpoint
Invoices
Submit electronic invoices that comply with ZATCA (General Authority of Zakat, Tax and Customs) requirements.
One endpoint — ZATCA Phase 2 compliant
Using 1 single endpoint you are compliant with ZATCA Phase 2. Submit an invoice with POST /api/Invoices/SubmitInvoice and we handle Fatoora integration, digital signatures, real-time transmission to ZATCA, and XML/UBL formatting for you.
Submit an invoice to ZATCA. No parameters — send the request body as application/json.
Request Body (application/json):
{
"invoiceNumber": "INV-2024-001",
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"invoiceType": 388,
"source": "WEB",
"qrCode": "",
"invoiceTypeCode": 388,
"transactionTypeCode": "0100000",
"notes": "Thank you for your business",
"order": 0,
"issueDate": "2024-01-15",
"issueTime": "10:30:00",
"previousInvoiceHash": "",
"lines": [
{
"id": "1",
"index": 1,
"productName": "Product or Service",
"quantity": 2,
"netPrice": 100,
"lineDiscount": 0,
"priceDiscount": 0,
"tax": 15,
"taxCategory": "S",
"taxCategoryReasonCode": "",
"taxCategoryReason": "",
"productCode": "PROD001"
}
],
"discount": 0,
"referenceId": "REF-001",
"paymentMeansCode": 30,
"sourceIP": "",
"customer": {
"identityType": "1",
"identityNumber": "300000000000003",
"streetName": "King Fahd Road",
"buildingNumber": "1234",
"cityName": "Riyadh",
"regionName": "Riyadh",
"districtName": "Al Olaya",
"additionalStreetAddress": "",
"vatRegNumber": "300000000000003",
"zipCode": "12345",
"customerName": "Example Customer",
"countryCode": "SA"
},
"deliveryDate": "2024-01-15",
"tax": 15,
"branchCode": "BR001"
}Schema (key fields):
- invoiceNumber, uuid, issueDate, issueTime — required invoice identifiers and dates
- invoiceType / invoiceTypeCode — e.g. 388 (Tax Invoice), 383 (Simplified)
- lines[] — productName, quantity, netPrice, tax, taxCategory, productCode
- customer — identityType, identityNumber, customerName, cityName, regionName, countryCode, vatRegNumber, streetName, buildingNumber, zipCode, etc.
- previousInvoiceHash — for clearance (Phase 2); empty for first or simplified
- paymentMeansCode — 10 Credit, 30 Cash, 48 Bank transfer, etc.
Response (200 OK):
{
"success": true,
"data": {
"invoiceId": "...",
"invoiceNumber": "INV-2024-001",
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"qrCode": "BASE64...",
"status": "submitted",
"submittedAt": "2024-01-15T10:30:00Z"
}
}