### Example Webhook Request Source: https://zatca.wafeq.com/reference/webhook An example of a POST request for a ZATCA Wafeq webhook. It demonstrates the necessary headers, including `X-Wafeq-Webhook-Secret`, and the full JSON payload for a reported simplified invoice event. ```http POST HTTP/1.1 Content-Length: 703 Content-Type: application/json Host: app.example.com Accept: application/json X-Wafeq-Webhook-Secret: 4cbf513c-d96a-4f3d-83ff-de637283d7aa { "payload": { "document": { "id": "61d7226e-c04a-4e55-a459-ad442812dbf0", "document_number": "INV-2023-001", "issue_datetime": "2023-09-04T13:05:38.113425Z", "supply_date": "2023-01-01" }, "status": "reported", "response": { "detail": { "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" }, "reportingStatus": "REPORTED" }, "status": 200 } }, "event_id": "68158622-72be-4e53-8a2d-5e813c959abf", "event_type": "zatca.simplified_invoice.reported", "timestamp": "2023-09-04T13:05:44.887378Z" } ``` -------------------------------- ### Register Device API Call (Production) Source: https://zatca.wafeq.com/index This code snippet demonstrates how to register a device to the ZATCA production environment using the Register Device API. It's similar to the simulation registration but uses `X-ZATCA-Environment=production`. This is used when ready to go live and requires a valid API Key and OTP. ```shell curl --request POST \ --url https://api.wafeq.com/v1/zatca/devices/register/ \ --header 'Authorization: Api-Key ' \ --header 'Accept: application/json; version=v1' \ --header 'Content-Type: application/json' \ --header 'X-ZATCA-Environment: production' \ --data '\ { "common_name": "Real Device 1", "otp": "583844" } ' ``` -------------------------------- ### GET /zatca/debit-notes/{id}/ Source: https://zatca.wafeq.com/reference/debit_notes_retrieve Retrieves a single debit note by its ID. This endpoint requires specifying the ZATCA environment and can optionally include branch and connected account IDs for multi-account setups. ```APIDOC ## GET /zatca/debit-notes/{id}/ ### Description Retrieves a single debit note by its unique identifier. ### Method GET ### Endpoint `/zatca/debit-notes/{id}/ ### Parameters #### Path Parameters - **id** (string) - Required - The unique identifier of the document. #### Header Parameters - **Authorization** (string) - Required - An API key that will be supplied in `Authorization` header. Example: `Api-Key vVLOU1BB.aKz8GWaAGz0w1fO997aCMskNfS0ZpwjS` - **X-ZATCA-Branch** (string) - Optional - If the account is under a Group VAT, then it is required to be the TIN of the instance under the Group VAT. Otherwise it is optional and can be used as a branch name. - **X-ZATCA-Connected-Account-Id** (string) - Optional - The unique identifier of the connected account you're operating on behalf of. - **X-ZATCA-Environment** (string) - Required - The ZATCA environment to use, available options are ['production', 'simulation']. ### Response #### Success Response (200) - **created_ts** (string) - The datetime in UTC when the document was created. - **document** (object) - The document data. Contains fields like `document_number`, `id`, `issue_datetime`, and `supply_date`. - **metadata** (object) - The metadata of the document. - **qr_code_data** (string) - Base64 encoded QR code data. - **reference** (string) - The reference of the document. - **reported_ts** (string) - The datetime in UTC when the document was reported/cleared. - **response** (object) - The response from the ZATCA API. - **sent_ts** (string) - The datetime in UTC when the document was sent. #### Response Example ```json { "created_ts": "2023-10-27T10:00:00Z", "document": { "document_number": "INV-001", "id": "doc-12345", "issue_datetime": "2023-10-27T09:00:00Z", "supply_date": "2023-10-27" }, "metadata": { "key1": "value1" }, "qr_code_data": "/9j/4AAQSkZJRgABAgEASABIAAD/2wBD...", "reference": "REF-XYZ", "reported_ts": "2023-10-27T11:00:00Z", "response": {}, "sent_ts": "2023-10-27T10:30:00Z" } ``` ``` -------------------------------- ### Register Device API Call (Production) Source: https://zatca.wafeq.com/docs Registers a device with the ZATCA production environment. Requires an API Key for authorization and an OTP received after onboarding. The `X-ZATCA-Environment` header must be set to 'production'. The response includes the device's common name, ID, and status. ```shell curl --request POST \ --url https://api.wafeq.com/v1/zatca/devices/register/ \ --header 'Authorization: Api-Key ' \ --header 'Accept: application/json; version=v1' \ --header 'Content-Type: application/json' \ --header 'X-ZATCA-Environment: production' \ --data \ '{ "common_name": "Real Device 1", "otp": "583844" }' ``` -------------------------------- ### Register Device API Call (Simulation) Source: https://zatca.wafeq.com/docs Registers a device with the ZATCA simulation environment. Requires an API Key for authorization and an OTP received after onboarding. The response includes the device's common name, ID, and status. ```shell curl --request POST \ --url https://api.wafeq.com/v1/zatca/devices/register/ \ --header 'Authorization: Api-Key ' \ --header 'Accept: application/json; version=v1' \ --header 'Content-Type: application/json' \ --header 'X-ZATCA-Environment: simulation' \ --data \ '{ "common_name": "Test Device 1", "otp": "454230" }' ``` -------------------------------- ### Report Debit Note - POST Request Example (JSON) Source: https://zatca.wafeq.com/reference/debit_notes_report_create Example of a POST request to report a single debit note using the ZATCA API. Includes supplier, customer, document, and line item details. ```json { "components": { "securitySchemes": { "APIKeyAuth": { "description": "__An API key that will be supplied in `Authorization` header.__\n\nExample:\n`Api-Key vVLOU1BB.aKz8GWaAGz0w1fO997aCMskNfS0ZpwjS`", "in": "header", "name": "Authorization", "type": "apiKey", "x-default": "Api-Key replace_with_your_api_key" } } }, "info": { "title": "Wafeq ZATCA API", "version": "v1-zatca" }, "openapi": "3.1.1", "paths": { "/zatca/debit-notes/report/": { "post": { "description": "Reports a single debit note. Optionally, send the debit note using specified `channels`.\n", "operationId": "debit_notes_report_create", "parameters": [ { "description": "If the account is under a Group VAT, then it is required to be the TIN of the instance under the Group VAT. Otherwise it is optional and can be used as a branch name", "in": "header", "name": "X-ZATCA-Branch", "schema": { "type": "string" } }, { "description": "The unique identifier of the connected account you're operating on behalf of", "in": "header", "name": "X-ZATCA-Connected-Account-Id", "schema": { "type": "string" } }, { "description": "The zatca environment to use, available options are ['production', 'simulation']", "in": "header", "name": "X-ZATCA-Environment", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "Reporting": { "value": { "document": { "currency": "SAR", "customer": { "address": { "building": "6789", "city": "Riyadh", "country": "SA", "district": "Al Olaya", "postal_code": "12211", "street": "King Fahd Road" }, "identification": { "type": "TIN", "value": "311111111111113" }, "name": "John Doe", "tax_registration_number": "311111111111113" }, "document_number": "DN-0001", "line_items": [ { "description": "iPhone 15 Pro 512 GB", "item": "iPhone 15 Pro", "quantity": 1, "tax": { "percent": 15, "type": "S" }, "unit_of_measure": "unit", "unit_price": 4699 } ], "payment_means": { "code": "10", "issue_reason": "Fees correction" }, "reference_document_number": "INV-0001", "supplier": { "address": { "building": "3141", "city": "Riyadh", "country": "SA", "district": "Al Malqa", "postal_code": "13521", "street": "Anas Bin Malik" }, "identification": { "type": "CRN", "value": "1234567890" }, "name": "ABCD Global Company for Information Technology", "tax_registration_number": "300000000000003" }, "supply_date": "2024-05-30", "tax_total": 123 } } }, "Reporting+Sending": { "summary": "Reporting + Sending", "value": { "channels": [ { "data": { "message": "Please find attached the debit note.", "recipients": { "bcc": [], "cc": [], "to": [ "john.doe@example.com" ] }, "subject": "Debit Note DN-0001" }, "type": "email" } ] } } } } } } } } } } ``` -------------------------------- ### Device Registration API Source: https://zatca.wafeq.com/index Register a new device for ZATCA invoice reporting. This endpoint is used for both simulation and production environments. OTPs are required and are valid for 1 hour. ```APIDOC ## POST /v1/zatca/devices/register/ ### Description Registers a new device with ZATCA for invoice reporting. Requires an OTP obtained from the ZATCA portal. Supports both simulation and production environments. ### Method POST ### Endpoint https://api.wafeq.com/v1/zatca/devices/register/ ### Parameters #### Headers - **Authorization** (string) - Required - Api-Key - **Accept** (string) - Required - application/json; version=v1 - **Content-Type** (string) - Required - application/json - **X-ZATCA-Environment** (string) - Required - 'simulation' or 'production' #### Request Body - **common_name** (string) - Required - A unique name for the device. - **otp** (string) - Required - The One-Time Password obtained from the ZATCA portal. ### Request Example ```json { "common_name": "Test Device 1", "otp": "454230" } ``` ### Response #### Success Response (200) - **common_name** (string) - The name of the registered device. - **id** (string) - The unique identifier for the registered device. - **status** (string) - The status of the device registration (e.g., 'active'). #### Response Example ```json { "common_name": "Test Device 1", "id": "zdev_1234567890", "status": "active" } ``` ``` -------------------------------- ### Credit Note Reporting Example (JSON) Source: https://zatca.wafeq.com/reference/credit_notes_report_create This JSON structure represents a credit note report to be submitted to the ZATCA API. It includes details about the supplier, customer, line items, and payment information. This is a foundational example for reporting. ```json { "document": { "currency": "SAR", "customer": { "address": { "building": "6789", "city": "Riyadh", "country": "SA", "district": "Al Olaya", "postal_code": "12211", "street": "King Fahd Road" }, "identification": { "type": "TIN", "value": "311111111111113" }, "name": "John Doe", "tax_registration_number": "311111111111113" }, "document_number": "CN-0001", "line_items": [ { "description": "iPhone 15 Pro 512 GB", "item": "iPhone 15 Pro", "quantity": 1, "tax": { "percent": 15, "type": "S" }, "unit_of_measure": "unit", "unit_price": 4699 } ], "payment_means": { "code": "10", "issue_reason": "Refund" }, "reference_document_number": "INV-0001", "supplier": { "address": { "building": "3141", "city": "Riyadh", "country": "SA", "district": "Al Malqa", "postal_code": "13521", "street": "Anas Bin Malik" }, "identification": { "type": "CRN", "value": "1234567890" }, "name": "ABCD Global Company for Information Technology", "tax_registration_number": "300000000000003" }, "supply_date": "2024-05-30", "tax_total": 123 } } ``` -------------------------------- ### Report Simplified Invoice API Call (Simulation) Source: https://zatca.wafeq.com/docs Reports a simplified invoice to the ZATCA simulation environment. Requires an API Key for authorization and the `X-Zatca-Environment` header set to 'simulation'. The request body should contain the simplified invoice payload. ```shell curl --request POST \ --url https://api.wafeq.com/v1/zatca/simplified-invoices/report/ \ --header 'Authorization: Api-Key ' \ --header 'Accept: application/json; version=v1' \ --header 'Content-Type: application/json' \ --header 'X-ZATCA-Environment: simulation' --data \ '{ ... }' ``` -------------------------------- ### List ZATCA Devices using HTTP GET Source: https://zatca.wafeq.com/reference/device This snippet shows the HTTP GET request structure for listing ZATCA devices. It includes the necessary headers for authorization and content type. The request is made to the specified ZATCA API endpoint. ```http GET https://api.wafeq.com/v1/zatca/devices/ Authorization: Api-Key replace_with_your_api_key accept: application/json ``` -------------------------------- ### Register Device API Source: https://zatca.wafeq.com/docs API endpoint to register a new device for ZATCA invoice reporting. Supports both simulation and production environments. ```APIDOC ## POST /v1/zatca/devices/register/ ### Description Registers a new device with ZATCA for invoice reporting. OTPs are required and have a limited validity period. ### Method POST ### Endpoint /v1/zatca/devices/register/ ### Parameters #### Headers - **Authorization** (string) - Required - Api-Key - **Accept** (string) - Required - application/json; version=v1 - **Content-Type** (string) - Required - application/json - **X-ZATCA-Environment** (string) - Required - 'simulation' or 'production' #### Request Body - **common_name** (string) - Required - A unique name for the device. - **otp** (string) - Required - The One-Time Password received from ZATCA. ### Request Example ```json { "common_name": "Test Device 1", "otp": "454230" } ``` ### Response #### Success Response (200) - **common_name** (string) - The name of the registered device. - **id** (string) - The unique identifier assigned to the device by ZATCA. - **status** (string) - The current status of the device (e.g., 'active'). #### Response Example ```json { "common_name": "Test Device 1", "id": "zdev_1234567890", "status": "active" } ``` ``` -------------------------------- ### GET /websites/zatca_wafeq Source: https://zatca.wafeq.com/reference/prepayment_simplified_invoices_retrieve Retrieve an invoice with its associated details. ```APIDOC ## GET /v1/invoices/{id} ### Description Retrieve a specific invoice by its ID. ### Method GET ### Endpoint /v1/invoices/{id} ### Parameters #### Path Parameters - **id** (string) - Required - The unique identifier of the invoice. ### Response #### Success Response (200) - **id** (string) - The unique identifier of the invoice. - **created_ts** (string) - The datetime in UTC when the document was created. - **document** (object) - Contains details about the invoice document. - **metadata** (object) - Contains metadata related to the invoice. - **qr_code_data** (string) - The QR code data for the invoice. - **reference** (string) - A reference number for the invoice. - **reported_ts** (string) - The datetime in UTC when the document was reported. - **response** (object) - Contains the response from the reporting service. - **sent_ts** (string) - The datetime in UTC when the document was sent. - **status** (string) - The status of the document. #### Response Example ```json { "id": "inv_123", "created_ts": "2023-10-27T10:00:00Z", "document": {}, "metadata": {}, "qr_code_data": "", "reference": "REF456", "reported_ts": "2023-10-27T10:05:00Z", "response": {}, "sent_ts": "2023-10-27T10:02:00Z", "status": "Submitted" } ``` ``` -------------------------------- ### Configuration for Charges and Discounts Source: https://zatca.wafeq.com/reference/prepayment_invoices_bulk_validate_create This section details the configuration options for charges and discounts within the ZATCA Wafeq system. It includes setting labels and reasons for both. ```APIDOC ## PUT /websites/zatca_wafeq/config ### Description Updates the configuration for charges and discounts for ZATCA documents. ### Method PUT ### Endpoint /websites/zatca_wafeq/config ### Parameters #### Request Body - **config** (object) - Required - The configuration object for the custom template. - **charges** (array) - Optional - Configuration for charges provided. - **labels** (object) - Required - Labels for the charge. - **ar** (string) - Required - Arabic label for the charge (max length 50). - **en** (string) - Required - English label for the charge (max length 50). - **reasons** (array) - Optional - Reasons for the charge. - Items (string) - Description for each reason. - **discounts** (array) - Optional - Configuration for discounts provided. - **labels** (object) - Required - Labels for the discount. - **ar** (string) - Required - Arabic label for the discount (max length 50). - **en** (string) - Required - English label for the discount (max length 50). - **reasons** (array) - Optional - Reasons for the discount. - Items (string) - Description for each reason. ### Request Example ```json { "config": { "charges": [ { "labels": { "ar": "رسوم إضافية", "en": "Additional Charges" }, "reasons": [ "Service Fee", "Handling Charge" ] } ], "discounts": [ { "labels": { "ar": "خصم خاص", "en": "Special Discount" }, "reasons": [ "Promotional Offer", "Bulk Purchase" ] } ] } } ``` ### Response #### Success Response (200) - **message** (string) - Indicates that the configuration was updated successfully. #### Response Example ```json { "message": "Configuration updated successfully." } ``` ``` -------------------------------- ### ZATCA Simplified Credit Note Reporting and Sending Example Source: https://zatca.wafeq.com/reference/simplified_credit_notes_report_create This snippet illustrates the combined reporting and sending functionality for a simplified credit note. It includes the document details along with email channel information for sending the credit note. This is a read-only example. ```json { "channels": [ { "data": { "message": "Please find attached the credit note.", "recipients": { "bcc": [], "cc": [], "to": [ "john.doe@example.com" ] }, "subject": "Credit Note CN-0001" }, "medium": "email" } ], "document": { "currency": "SAR", "customer": { "address": { "building": "6789", "city": "Riyadh", "country": "SA", "district": "Al Olaya", "postal_code": "12211", "street": "King Fahd Road" }, "identification": { "type": "TIN", "value": "311111111111113" }, "name": "John Doe", "tax_registration_number": "311111111111113" }, "document_number": "CN-0001", "line_items": [ { "description": "iPhone 15 Pro 512 GB", "item": "iPhone 15 Pro", "quantity": 1, "tax": { "percent": 15, "type": "S" }, "unit_of_measure": "unit", "unit_price": 4699 } ] } } ``` -------------------------------- ### Simplified Invoice Report API Source: https://zatca.wafeq.com/docs API endpoint to report a simplified invoice to ZATCA. Supports reporting to the simulation environment. ```APIDOC ## POST /v1/zatca/simplified-invoices/report/ ### Description Reports a simplified invoice to the ZATCA Fatoora system. Use the `X-Zatca-Environment` header to specify the target environment. ### Method POST ### Endpoint /v1/zatca/simplified-invoices/report/ ### Parameters #### Headers - **Authorization** (string) - Required - Api-Key - **Accept** (string) - Required - application/json; version=v1 - **Content-Type** (string) - Required - application/json - **X-ZATCA-Environment** (string) - Required - 'simulation' or 'production' #### Request Body - **** (object) - Required - The complete payload for the simplified invoice, adhering to ZATCA's specifications. ### Request Example ```json { ... } ``` ### Response #### Success Response (200) Details of the successful invoice submission (specific fields depend on ZATCA's response). #### Response Example (Example response not provided in source text, but would typically include submission confirmation details.) ``` -------------------------------- ### ZATCA Simplified Invoice Reporting Example (JSON) Source: https://zatca.wafeq.com/reference/prepayment_simplified_invoices_report_create An example JSON payload for reporting a simplified invoice through the ZATCA API. This includes details of the supplier, customer, line items, currency, and tax information. It serves as a template for generating compliant invoices. ```json { "document": { "currency": "SAR", "customer": { "address": { "building": "6789", "city": "Riyadh", "country": "SA", "district": "Al Olaya", "postal_code": "12211", "street": "King Fahd Road" }, "identification": { "type": "TIN", "value": "311111111111113" }, "name": "John Doe", "tax_registration_number": "311111111111113" }, "document_number": "INV-0001", "line_items": [ { "description": "iPhone 15 Pro 512 GB", "item": "iPhone 15 Pro", "quantity": 1, "tax": { "percent": 15, "type": "S" }, "unit_of_measure": "unit", "unit_price": 4699 } ], "supplier": { "address": { "building": "3141", "city": "Riyadh", "country": "SA", "district": "Al Malqa", "postal_code": "13521", "street": "Anas Bin Malik" }, "identification": { "type": "CRN", "value": "1234567890" }, "name": "ABCD Global Company for Information Technology", "tax_registration_number": "300000000000003" }, "supply_date": "2024-05-30", "tax_total": 123 } } ``` -------------------------------- ### Credit Note Reporting and Sending Example (JSON) Source: https://zatca.wafeq.com/reference/credit_notes_report_create This JSON object extends the credit note reporting example by adding channels for sending the document, specifically via email. It includes recipient details and subject for the email notification. This is useful for automated communication. ```json { "channels": [ { "data": { "message": "Please find attached the credit note.", "recipients": { "bcc": [], "cc": [], "to": [ "john.doe@example.com" ] }, "subject": "Credit Note CN-0001" }, "medium": "email" } ], "document": { "currency": "SAR", "customer": { "address": { "building": "6789", "city": "Riyadh", "country": "SA", "district": "Al Olaya", "postal_code": "12211", "street": "King Fahd Road" }, "identification": { "type": "TIN", "value": "311111111111113" }, "name": "John Doe", "tax_registration_number": "311111111111113" }, "document_number": "CN-0001", "line_items": [ { "description": "iPhone 15 Pro 512 GB", "item": "iPhone 15 Pro", "quantity": 1, "tax": { "percent": 15, "type": "S" }, "unit_of_measure": "unit", "unit_price": 4699 } ], "payment_means": { "code": "10", "issue_reason": "Refund" }, "reference_document_number": "INV-0001", "supplier": { "address": { "building": "3141", "city": "Riyadh", "country": "SA", "district": "Al Malqa", "postal_code": "13521", "street": "Anas Bin Malik" }, "identification": { "type": "CRN", "value": "1234567890" }, "name": "ABCD Global Company for Information Technology", "tax_registration_number": "300000000000003" }, "supply_date": "2024-05-30", "tax_total": 123 } } ``` -------------------------------- ### Simplified Invoice Report API Source: https://zatca.wafeq.com/index Report a simplified invoice to ZATCA. This endpoint is used for submitting invoice data and requires the `X-Zatca-Environment` header to specify the target environment. ```APIDOC ## POST /v1/zatca/simplified-invoices/report/ ### Description Reports a simplified invoice to ZATCA. This endpoint is used for submitting invoice data and can target either the simulation or production environment. ### Method POST ### Endpoint https://api.wafeq.com/v1/zatca/simplified-invoices/report/ ### Parameters #### Headers - **Authorization** (string) - Required - Api-Key - **Accept** (string) - Required - application/json; version=v1 - **Content-Type** (string) - Required - application/json - **X-ZATCA-Environment** (string) - Required - 'simulation' or 'production' #### Request Body - **Simplified Invoice Payload** (object) - Required - The complete data structure for a simplified invoice as defined by ZATCA. ### Request Example ```json { ... } ``` ### Response #### Success Response (200) Details of the successful invoice submission. The exact structure may vary based on ZATCA's response. #### Response Example (Example response structure not provided in the source text, but would typically include invoice status, UUID, etc.) ``` -------------------------------- ### Register Device API Call (Simulation) Source: https://zatca.wafeq.com/index This code snippet demonstrates how to register a device to the ZATCA simulation environment using the Register Device API. It requires an API Key, a common name for the device, and a One-Time Password (OTP) obtained from the ZATCA portal. The response includes the device's common name, ID, and status. ```shell curl --request POST \ --url https://api.wafeq.com/v1/zatca/devices/register/ \ --header 'Authorization: Api-Key ' \ --header 'Accept: application/json; version=v1' \ --header 'Content-Type: application/json' \ --header 'X-ZATCA-Environment: simulation' \ --data '\ { "common_name": "Test Device 1", "otp": "454230" } ' ``` -------------------------------- ### Example Document Structure (JSON) Source: https://zatca.wafeq.com/reference/credit_notes_report_create An example JSON structure representing a document, likely an invoice or credit note, for use with ZATCA. It includes supplier, customer, line items, payment details, and tax information. This structure is used for generating electronic invoices. ```json { "currency": "SAR", "customer": { "address": { "building": "6789", "city": "Riyadh", "country": "SA", "district": "Al Olaya", "postal_code": "12211", "street": "King Fahd Road" }, "identification": { "type": "TIN", "value": "311111111111113" }, "name": "John Doe", "tax_registration_number": "311111111111113" }, "document_number": "CN-0001", "line_items": [ { "description": "iPhone 15 Pro 512 GB", "item": "iPhone 15 Pro", "quantity": 1, "tax": { "percent": 15, "type": "S" }, "unit_of_measure": "unit", "unit_price": 4699 } ], "payment_means": { "code": "10", "issue_reason": "Refund" }, "reference_document_number": "INV-0001", "supplier": { "address": { "building": "3141", "city": "Riyadh", "country": "SA", "district": "Al Malqa", "postal_code": "13521", "street": "Anas Bin Malik" }, "identification": { "type": "CRN", "value": "1234567890" }, "name": "ABCD Global Company for Information Technology", "tax_registration_number": "300000000000003" }, "supply_date": "2024-05-30", "tax_total": 123 } ``` -------------------------------- ### POST /websites/zatca_wafeq/create Source: https://zatca.wafeq.com/reference/connected_accounts_create Endpoint for creating a connected account. ```APIDOC ## POST /websites/zatca_wafeq/create ### Description Endpoint for creating a connected account. ### Method POST ### Endpoint /websites/zatca_wafeq/create ### Parameters #### Query Parameters #### Request Body (No specific request body details provided in the input) ### Request Example ```json { "message": "Request body structure not specified" } ``` ### Response #### Success Response (200) (No specific success response details provided in the input) #### Response Example ```json { "message": "Response body structure not specified" } ``` ``` -------------------------------- ### ZATCA Debit Note Reporting and Sending Example (JSON) Source: https://zatca.wafeq.com/reference/simplified_debit_notes_report_create This example demonstrates how to report and send a simplified debit note, including email channel details. It extends the reporting structure by adding a 'channels' array to specify how the document should be communicated. This is useful for automated notifications. ```json { "channels": [ { "data": { "message": "Please find attached the debit note.", "recipients": { "bcc": [], "cc": [], "to": [ "john.doe@example.com" ] }, "subject": "Debit Note DN-0001" }, "medium": "email" } ], "document": { "currency": "SAR", "customer": { "address": { "building": "6789", "city": "Riyadh", "country": "SA", "district": "Al Olaya", "postal_code": "12211", "street": "King Fahd Road" }, "identification": { "type": "TIN", "value": "311111111111113" }, "name": "John Doe", "tax_registration_number": "311111111111113" }, "document_number": "DN-0001", "line_items": [ { "description": "iPhone 15 Pro 512 GB", "item": "iPhone 15 Pro", "quantity": 1, "tax": { "percent": 15, "type": "S" }, "unit_of_measure": "unit", "unit_price": 4699 } ], "payment_means": { "code": "10", "issue_reason": "Fees correction" }, "reference_document_number": "INV-0001", "supplier": { "address": { "building": "3141", "city": "Riyadh", "country": "SA", "district": "Al Malqa", "postal_code": "13521", "street": "Anas Bin Malik" }, "identification": { "type": "CRN", "value": "1234567890" }, "name": "ABCD Global Company for Information Technology", "tax_registration_number": "300000000000003" }, "supply_date": "2024-05-30", "tax_total": 123 } } ``` -------------------------------- ### Report Simplified Invoice API Call (Simulation) Source: https://zatca.wafeq.com/index This code snippet shows how to report a simplified invoice to the ZATCA simulation environment using the Simplified Invoice Report API. It requires an API Key and the `X-Zatca-Environment` header set to `simulation`. The data payload should contain the simplified invoice details. ```shell curl --request POST \ --url https://api.wafeq.com/v1/zatca/simplified-invoices/report/ \ --header 'Authorization: Api-Key ' \ --header 'Accept: application/json; version=v1' \ --header 'Content-Type: application/json' \ --header 'X-ZATCA-Environment: simulation' --data '\ { ... } ' ``` -------------------------------- ### ZATCA Simplified Credit Note Reporting Example Source: https://zatca.wafeq.com/reference/simplified_credit_notes_report_create Example JSON payload for reporting a single credit note to ZATCA. This includes details for the customer, supplier, line items, payment means, and tax information. It can optionally include channel information for sending the credit note. ```json { "components": { "securitySchemes": { "APIKeyAuth": { "description": "__An API key that will be supplied in `Authorization` header.__\n\nExample:\n`Api-Key vVLOU1BB.aKz8GWaAGz0w1fO997aCMskNfS0ZpwjS`", "in": "header", "name": "Authorization", "type": "apiKey", "x-default": "Api-Key replace_with_your_api_key" } } }, "info": { "title": "Wafeq ZATCA API", "version": "v1-zatca" }, "openapi": "3.1.1", "paths": { "/zatca/simplified-credit-notes/report/": { "post": { "description": "Reports a single credit note. Optionally, send the credit note using specified `channels`.\n", "operationId": "simplified_credit_notes_report_create", "parameters": [ { "description": "If the account is under a Group VAT, then it is required to be the TIN of the instance under the Group VAT. Otherwise it is optional and can be used as a branch name", "in": "header", "name": "X-ZATCA-Branch", "schema": { "type": "string" } }, { "description": "The unique identifier of the connected account you're operating on behalf of", "in": "header", "name": "X-ZATCA-Connected-Account-Id", "schema": { "type": "string" } }, { "description": "The zatca environment to use, available options are ['production', 'simulation']", "in": "header", "name": "X-ZATCA-Environment", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "Reporting": { "value": { "document": { "currency": "SAR", "customer": { "address": { "building": "6789", "city": "Riyadh", "country": "SA", "district": "Al Olaya", "postal_code": "12211", "street": "King Fahd Road" }, "identification": { "type": "TIN", "value": "311111111111113" }, "name": "John Doe", "tax_registration_number": "311111111111113" }, "document_number": "CN-0001", "line_items": [ { "description": "iPhone 15 Pro 512 GB", "item": "iPhone 15 Pro", "quantity": 1, "tax": { "percent": 15, "type": "S" }, "unit_of_measure": "unit", "unit_price": 4699 } ], "payment_means": { "code": "10", "issue_reason": "Refund" }, "reference_document_number": "INV-0001", "supplier": { "address": { "building": "3141", "city": "Riyadh", "country": "SA", "district": "Al Malqa", "postal_code": "13521", "street": "Anas Bin Malik" }, "identification": { "type": "CRN", "value": "1234567890" }, "name": "ABCD Global Company for Information Technology", "tax_registration_number": "300000000000003" }, "supply_date": "2024-05-30", "tax_total": 123 } } }, "Reporting+Sending": { "summary": "Reporting + Sending", "value": { "channels": [ { "data": { "message": "Please find attached the credit note.", "recipients": { "bcc": [], "cc": [], "to": [ "john.doe@example.com" ] }, "subject": "Credit Note CN-0001" }, "type": "email" } ], "document": { "currency": "SAR", "customer": { "address": { "building": "6789", "city": "Riyadh", "country": "SA", "district": "Al Olaya", "postal_code": "12211", "street": "King Fahd Road" }, "identification": { "type": "TIN", "value": "311111111111113" }, "name": "John Doe", "tax_registration_number": "311111111111113" }, "document_number": "CN-0001", "line_items": [ { "description": "iPhone 15 Pro 512 GB", "item": "iPhone 15 Pro", "quantity": 1, "tax": { "percent": 15, "type": "S" }, "unit_of_measure": "unit", "unit_price": 4699 } ], "payment_means": { "code": "10", "issue_reason": "Refund" }, "reference_document_number": "INV-0001", "supplier": { "address": { "building": "3141", "city": "Riyadh", "country": "SA", "district": "Al Malqa", "postal_code": "13521", "street": "Anas Bin Malik" }, "identification": { "type": "CRN", "value": "1234567890" }, "name": "ABCD Global Company for Information Technology", "tax_registration_number": "300000000000003" }, "supply_date": "2024-05-30", "tax_total": 123 } } } } } } } } } } } ```