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.Learn more about ZATCA requirements →
Base URL
Base URL for all requests:
https://api.dawalconnect.sa/v1Authentication
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
Onboarding
Create a new account and activate the service
Register a new account in Dawal Connect
Request Body:
{
"company_name": "Example Company",
"tax_number": "123456789012345",
"email": "company@example.com",
"phone": "+966501234567",
"address": {
"street": "King Fahd Street",
"city": "Riyadh",
"postal_code": "12345",
"country": "SA"
},
"plan": "zatca_2"
}Response:
{
"success": true,
"data": {
"account_id": "acc_xxxxxxxxxxxxx",
"api_key": "sk_live_xxxxxxxxxxxxx",
"status": "pending_verification",
"verification_url": "https://dawalconnect.sa/verify/xxxxx"
}
}Test Endpoint
Check registration and activation status
Response:
{
"success": true,
"data": {
"account_id": "acc_xxxxxxxxxxxxx",
"status": "active",
"plan": "zatca_2",
"verified_at": "2024-01-15T10:30:00Z"
}
}Test Endpoint
Invoices
Create and submit electronic invoices that comply with ZATCA (General Authority of Zakat, Tax and Customs) requirements. All invoices are automatically formatted according to ZATCA standards and can be submitted directly to the ZATCA platform.
ZATCA Compliance Levels
- ZATCA Phase 1 (Generation): Generate and store compliant electronic invoices with mandatory fields, QR codes for simplified invoices, and anti-tampering features.
- ZATCA Phase 2 (Integration): Full integration with Fatoora platform, cryptographic digital signatures, real-time transmission to ZATCA, XML/UBL format, and PKI/AES-256 encryption compliance.
Note: Non-compliance may result in penalties ranging from SAR 1,000 to SAR 40,000.
Create a new invoice and submit it to ZATCA
Request Body:
{
"invoice_number": "INV-2024-001",
"invoice_date": "2024-01-15",
"due_date": "2024-02-15",
"seller": {
"name": "Example Company",
"tax_number": "123456789012345",
"address": "Riyadh, Saudi Arabia"
},
"buyer": {
"name": "Example Customer",
"tax_number": "987654321098765",
"address": "Jeddah, Saudi Arabia"
},
"items": [
{
"name": "Example Product",
"quantity": 2,
"unit_price": 100.00,
"tax_rate": 0.15,
"discount": 0
}
],
"notes": "Thank you for your business"
}Response:
{
"success": true,
"data": {
"invoice_id": "inv_xxxxxxxxxxxxx",
"invoice_number": "INV-2024-001",
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"qr_code": "https://zatca.gov.sa/qr/...",
"signed_xml": "<?xml version="1.0"?>...",
"status": "submitted",
"submitted_at": "2024-01-15T10:30:00Z"
}
}Test Endpoint
Get details of a specific invoice
Test Endpoint
Webhooks
Receive instant notifications when invoice status changes
Register a webhook URL to receive notifications
Request Body:
{
"url": "https://yourdomain.com/webhook",
"events": ["invoice.created", "invoice.submitted", "invoice.rejected"]
}Error Handling
All errors are returned in a unified JSON format:
{
"success": false,
"error": {
"code": "INVALID_REQUEST",
"message": "Invalid request data",
"details": {
"field": "tax_number",
"reason": "Tax number must be 15 digits"
}
}
}Common Error Codes:
- 400 - Bad Request: Invalid request data
- 401 - Unauthorized: Invalid or expired API key
- 403 - Forbidden: You don't have permission to access this resource
- 404 - Not Found: Resource not found
- 429 - Too Many Requests: Rate limit exceeded
- 500 - Server Error: Internal server error