Wafeq ZATCA Public API

https://zatca.wafeq.com/
Admin
Wafeq ZATCA Public API provides a platform and API for businesses to onboard devices and report...
Tokens:613,221
Snippets:1,077
Trust Score:9.1
Update:1 year ago
Show doc for...
Tokens:
Raw
### 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 <Your 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 <Your 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 <Your 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 <Your 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 <Your API Key>' \
     --header 'Accept: application/json; version=v1' \
     --header 'Content-Type: application/json' \
     --header 'X-ZATCA-Environment: simulation' 
     --data \
'{
	...
  <Simplified Invoice Payload>
}'
```

--------------------------------

### 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 <Your 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 <Your 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 payload for the simplified invoice, adhering to ZATCA's specifications.

### Request Example
```json
{
	... 
  <Simplified Invoice Payload>
}
```

### 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 <Your 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
{
	... 
  <Simplified Invoice Payload>
}
```

### 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 <Your 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 <Your API Key>' \
     --header 'Accept: application/json; version=v1' \
     --header 'Content-Type: application/json' \
     --header 'X-ZATCA-Environment: simulation' 
     --data '\
{
	...
  <Simplified Invoice Payload>
}
'
```

--------------------------------

### 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
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```
Tokens:
Raw