Zatca Erpgulf Sync

bench get-app https://github.com/ERPGulf/zatca_erpgulf_sync

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=ERPGulf%2Fzatca_erpgulf_sync)](https://frappegems.com/gems/apps/ERPGulf/zatca_erpgulf_sync)

# ZATCA Invoice API Integration This document provides instructions for integrating with the ZATCA Invoice APIs for submitting sales invoices and generating PDF/A-3 invoices with embedded XML.These APIs provide functionality that can be used for submitting invoices to ZATCA from a third-party invoicing system. Users need to create an intermediary server on Claudion.com before proceeding with this. For more details and clarifications, please contact support@claudion.com. We also have a Swagger page on the Claudion.com portal to assist developers. ## 🔗 API References - 📘 **Postman Documentation**: [View the full API reference here](https://documenter.getpostman.com/view/36963652/2sAY518fmD) - 🧾 **Swagger UI Reference**: [Access Swagger docs here](https://saudi.claudion.com/swagger-zatca) ## 🔄 Cross References This repo is referenced in the Postman documentation. You can view it directly in Postman under: > **"You can see the GitHub repository for this app [here](https://github.com/ERPGulf/zatca_erpgulf_sync/tree/main)"** --- ## Submit Sales Invoice This API allows third-party systems to submit invoices to ZATCA through an intermediary server. It handles all cases, including the first submission and subsequent calls to check the status. On first submission, the intermediary server will attempt to post the invoice to ZATCA immediately. In case of success, the intermediary server will respond to the user with the QR code, XML, and full ZATCA response. If the intermediary server fails to receive a response from ZATCA immediately, it will respond with a "Waiting for Response" status. For any subsequent calls for the same invoice, the intermediary server will respond with the QR code, XML, and ZATCA response if available. Otherwise, it will return either a "Pending" or "Error" status. In such cases, the user needs to either re-submit (in case of "Pending") or correct the error (in case of "Error"). Details are as follows: As mentioned above, This API allows users to create and submit a Sales Invoice by providing customer details, a unique invoice number, items, taxes, and other relevant parameters. Upon successful creation, the invoice is submitted to ZATCA and the API returns the Sales Invoice number, UUID, ZATCA response, generated XML, and a link to download the QR code image. Functionality 1. If an invoice with the provided custom_user_invoice_number already exists in the system, the API will fetch the corresponding Sales Invoice, extract and decode the associated ZATCA XML, and retrieve the link to download the QR image . Instead of creating a new invoice, it returns the existing invoice details in the response with a 200 status, ensuring no duplicates are created and allowing clients to reuse previously submitted data. 2. If a customer with the provided name does not already exist, the API will automatically create a new Customer record, defaulting the customer type to "Individual" and assigning them to the "Demo Customer Group. 3. For each item in the provided list, the API checks whether the item exists in the system. If not, it automatically creates the item under the "All Item Groups" category. Key fields such as description, price, tax template, and income account are validated to ensure completeness before adding the item to the invoice. 4. The API constructs a new Sales Invoice using the provided customer, posting date, and due date. It includes all specified line items along with any tax configurations applied. Optional discounts can be set either as a percentage or a fixed amount. Additionally, custom fields such as custom_user_invoice_number and custom_zatca_tax_category are included to support personalized tracking and ZATCA compliance. 5. Once the invoice is submitted, the system reloads it to check for a ZATCA response. If ZATCA returns a "503 Service Unavailable" error, the API responds with a 503 status and includes the UUID along with the full ZATCA response. If there is no response from ZATCA yet, it returns a 202 Accepted status with the message "Waiting for response." In such cases, if the API is called again with the same custom_user_invoice_number, it will return the same invoice details. If ZATCA responds successfully, the API extracts and decodes the XML, embeds the QR image (via direct link), and returns all relevant fields in the final JSON response. 6. If is_return is set to 1, the API creates a Return Sales Invoice (Credit Note) linked to the original invoice using the return_against field. It ensures that return_against is provided, and automatically converts all item quantities to negative values to represent a return. This process maintains correct stock, customer balances, and full traceability between the original and returned invoices. 7. The API supports applying discounts at both the item level (per line item) and the document level (overall invoice discount). Taxes can be applied either through the Item Tax Template (specific to each item) or by setting a general Tax Category at the invoice level, along with an optional Exemption Reason Code to comply with specific tax regulations. 8. The API allows handling both tax-inclusive and tax-exclusive item rates. If the tax setting included_in_print_rate is set to 1, the item prices are treated as tax-inclusive (i.e., tax is already included in the item rate). If included_in_print_rate is 0 or not set, the item prices are considered tax-exclusive, and taxes are added separately on top of the item rate during invoice calculation.EndFragment 9. If income_account, charge_type, or account_head are not provided in the API request, the system will automatically fall back to values defined in the Intermediate Server Setting single Doctype. 10. In the create_simple_sales_invoice API, the tax_id parameter is used to set the customer's tax identification number. This field is applied when the invoice is for a business (i.e., is_b2c is set to 0). If the customer does not already exist, the API will create a new customer and assign the provided tax_id for B2B transactions. For B2C transactions (is_b2c = 1), the tax_id can be blank. ## Request Body ```bash curl --location 'https://zatca.erpgulf.com:3717/api/method/zatca_erpgulf_sync.zatca_erpgulf_sync.invoice_sync.create_simple_sales_invoice' \ --header 'Content-Type: application/json' \ --header 'Cookie: full_name=Guest; sid=Guest; system_user=yes; user_id=Guest; user_image=' \ --data '{ "customer_name": "customer1234", "custom_user_invoice_number": "IND-989098", "tax_id" : 311523216200003, "posting_date": "2025-11-06", "due_date": "2025-11-20", "discount_amount": 10, "tax_category": "Standard", "custom_exemption_reason_code":"Standard 15%", "is_b2c": false, "is_return": 0, "return_against": "ACC-SINV-2025-00815", "items": [ { "item_name": "Tpppshirt", "quantity": 1, "rate": 800, "income_account": "", "description": "High-quality T-shirt", "discount_amount": 20, "item_tax_template" : "zero rated - ZA" } ], "taxes": [ { "charge_type": "", "account_head": "", "rate": 0, "description": "VAT", "included_in_print_rate": 0 } ] } ' ``` ### Response ``` { "data": { "invoice_id": "ACC-SINV-2025-00826", "uuid": "2611e100-2598-11f0-b7e4-020017019f27", "zatca_full_response": "SUCCESS:

Status Code: 200

Zatca Response: {\"validationResults\":{\"infoMessages\":[{\"type\":\"INFO\",\"code\":\"XSD_ZATCA_VALID\",\"category\":\"XSD validation\",\"message\":\"Complied with UBL 2.1 standards in line with ZATCA specifications\",\"status\":\"PASS\"}],\"warningMessages\":[],\"errorMessages\":[],\"status\":\"PASS\"},\"clearanceStatus\":\"CLEARED\",\"clearedInvoice\":\"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPEludm9pY2UgeG1sbnM9InVybjpvYXNpczpuYW1lczpzcGVjaWZpY2F0aW9uOnVibDpzY2hlbWE6eHNkOkludm9pY2UtMiIgeG1sbnM6Y2FjPSJ1cm46b2FzaXM6bmFtZXM6c3BlY2lmaWNhdGlvbjp1Ymw6c2NoZW1hOnhzZDpDb21tb25BZ2dyZWdhdGVDb21wb25lbnRzLTIiIHhtbG5zOmNiYz0idXJuOm9hc2lzOm5hbWVzOnNwZWNpZmljYXRpb246dWJsOnNjaGVtYTp4c2Q6Q29tbW9uQmFzaWNDb21wb25lbnRzLTIiIHhtbG5zOmV4dD0idXJuOm9hc2lzOm5hbWVzOnNwZWNpZmljYXRpb246dWJsOnNjaGVtYTp4c2Q6Q29tbW9uRXh0ZW5zaW9uQ29tcG9uZW50cy0yIj48ZXh0OlVCTEV4dGVuc2lvbnM+CiAgICA8ZXh0OlVCTEV4dGVuc2lvbj4KICAgICAgICA8ZXh0OkV4dGVuc2lvblVSST51cm46b2FzaXM6bmFtZXM6c3BlY2lmaWNhdGlvbjp1Ymw6ZHNpZzplbnZlbG9wZWQ6eGFkZXM8L2V4dDpFeHRlbnNpb25VUkk+CiAgICAgICAgPGV4dDpFeHRlbnNpb25Db250ZW50PgogICAgICAgICAgICA8c2lnOlVCTERvY3VtZW50U2lnbmF0dXJlcyB4bWxuczpzaWc9InVybjpvYXNpczpuYW1lczpzcGVjaWZpY2F0aW9uOnVibDpzY2hlbWE6eHNkOkNvbW1vblNpZ25hdHVyZUNvbXBvbmVudHMtMiIgeG1sbnM6c2FjPSJ1cm46b2FzaXM6bmFtZXM6c3BlY2lmaWNhdGlvbjp1Ymw6c2NoZW1hOnhzZDpTaWduYXR1cmVBZ2dyZWdhdGVDb21wb25lbnRzLTIiIHhtbG5zOnNiYz0idXJuOm9hc2lzOm5hbWVzOnNwZWNpZmljYXRpb246dWJsOnNjaGVtYTp4c2Q6U2lnbmF0dXJlQmFzaWNDb21wb25lbnRzLTIiPgogICAgICAgICAgICAgICAgPHNhYzpTaWduYXR1cmVJbmZvcm1hdGlvbj4gCiAgICAgICAgICAgICAgICAgICAgPGNiYzpJRD51cm46b2FzaXM6bmFtZXM6c3BlY2lmaWNhdGlvbjp1Ymw6c2lnbmF0dXJlOjE8L2NiYzpJRD4KICAgICAgICAgICAgICAgICAgICA8c2JjOlJlZmVyZW5jZWRTaWduYXR1cmVJRD51cm46b2FzaXM6bmFtZXM6c3BlY2lmaWNhdGlvbjp1Ymw6c2lnbmF0dXJlOkludm9pY2U8L3NiYzpSZWZlcmVuY2VkU2lnbmF0dXJlSUQ+CiAgICAgICAgICAgICAgICAgICAgPGRzOlNpZ25hdHVyZSB4bWxuczpkcz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC8wOS94bWxkc2lnIyIgSWQ9InNpZ25hdHVyZSI+CiAgICAgICAgICAgICAgICAgICAgICAgIDxkczpTaWduZWRJbmZvPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgPGRzOkNhbm9uaWNhbGl6YXRpb25NZXRob2QgQWxnb3JpdGhtPSJodHRwOi8vd3d3LnczLm9yZy8yMDA2LzEyL3htbC1jMTRuMTEiLz4KICAgICAgICAgICAgICAgICAgICAgICAgICAgIDxkczpTaWduYXR1cmVNZXRob2QgQWxnb3JpdGhtPSJodHRwOi8vd3d3LnczLm9yZy8yMDAxLzA0L3htbGRzaWctbW9yZSNlY2RzYS1zaGEyNTYiLz4KICAgICAgICAgICAgICAgICAgICAgICAgICAgIDxkczpSZWZlcmVuY2UgSWQ9Imludm9pY2VTaWduZWREYXRhIiBVUkk9IiI+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgPGRzOlRyYW5zZm9ybXM+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDxkczpUcmFuc2Zvcm0gQWxnb3JpdGhtPSJodHRwOi8vd3d3LnczLm9yZy9UUi8xOTk5L1JFQy14cGF0aC0xOTk5MTExNiI+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICA8ZHM6WFBhdGg+bm90KC8vYW5jZXN0b3Itb3Itc2VsZjo6ZXh0OlVCTEV4dGVuc2lvbnMpPC9kczpYUGF0aD4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgPC9kczpUcmFuc2Zvcm0+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDxkczpUcmFuc2Zvcm0gQWxnb3JpdGhtPSJodHRwOi8vd3d3LnczLm9yZy9UUi8xOTk5L1JFQy14cGF0aC0xOTk5MTExNiI+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICA8ZHM6WFBhdGg+bm90KC8vYW5jZXN0b3Itb3Itc2VsZjo6Y2FjOlNpZ25hdHVyZSk8L2RzOlhQYXRoPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICA8L2RzOlRyYW5zZm9ybT4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgPGRzOlRyYW5zZm9ybSBBbGdvcml0aG09Imh0dHA6Ly93d3cudzMub3JnL1RSLzE5OTkvUkVDLXhwYXRoLTE5OTkxMTE2Ij4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDxkczpYUGF0aD5ub3QoLy9hbmNlc3Rvci1vci1zZWxmOjpjYWM6QWRkaXRpb25hbERvY3VtZW50UmVmZXJlbmNlW2NiYzpJRD0nUVInXSk8L2RzOlhQYXRoPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICA8L2RzOlRyYW5zZm9ybT4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgPGRzOlRyYW5zZm9ybSBBbGdvcml0aG09Imh0dHA6Ly93d3cudzMub3JnLzIwMDYvMTIveG1sLWMxNG4xMSIvPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDwvZHM6VHJhbnNmb3Jtcz4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICA8ZHM6RGlnZXN0TWV0aG9kIEFsZ29yaXRobT0iaHR0cDovL3d3dy53My5vcmcvMjAwMS8wNC94bWxlbmMjc2hhMjU2Ii8+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgPGRzOkRpZ2VzdFZhbHVlPjJyeVArWjJERVBEWGt1NmxxbW9KVWdVSmFvZUV0Z1l4a25MczluVnlkckU9PC9kczpEaWdlc3RWYWx1ZT4KICAgICAgICAgICAgICAgICAgICAgICAgICAgIDwvZHM6UmVmZXJlbmNlPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgPGRzOlJlZmVyZW5jZSBUeXBlPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwLzA5L3htbGRzaWcjU2lnbmF0dXJlUHJvcGVydGllcyIgVVJJPSIjeGFkZXNTaWduZWRQcm9wZXJ0aWVzIj4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICA8ZHM6RGlnZXN0TWV0aG9kIEFsZ29yaXRobT0iaHR0cDovL3d3dy53My5vcmcvMjAwMS8wNC94bWxlbmMjc2hhMjU2Ii8+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgPGRzOkRpZ2VzdFZhbHVlPk1tTXlPRGRoWXpWa05qWTBNelpsWm1KbE5ESTVZamhpT