API Reference
Invoices (Bulk)
This is a non-posting endpoint
This endpoint is designed to send invoices in large volumes. In order to preserve accounting reports performance, invoices you send through it are non-posting, meaning they are not automatically recorded in your books.
You can query or export the invoices created through this endpoint, then create a regular summary invoice or simplified invoice for the total daily, weekly or monthly revenue.
Endpoints
GET /v1/api-invoices/
GET /v1/api-invoices/:id
DELETE /v1/api-invoices/:id
POST /v1/api-invoices/bulk_send/
POST /v1/api-invoices/summary/?from_date=<from_date>&to_date=<to_date>
Invoice object
Attributes | Type | Required | Description |
---|---|---|---|
reference | string | False | Invoice reference code. |
invoice_number | string | True | Invoice number. |
invoice_date | string | True | Invoice date in YYYY-MM-DD e.g. 2021-01-01 . |
currency | string | True | Currency to be used in the invoice. |
paid_through_account | string | False | The Account where the invoice was paid through, for example a bank account. |
language | string | True | Language in which the invoice will be generated. en or ar . |
notes | string | False | Extra notes to be added at the end of the invoice. |
tax_amount_type | string | False | Whether LineItem prices are exclusive or inclusive of taxes. One of TAX_INCLUSIVE , TAX_EXCLUSIVE . |
contact | Contact | True | Contact details to be displayed on the Invoice. |
channels | array[ Channel ] | True | List of channels to be used to send the invoice. |
line_items | array[ LineItem ] | True | List of line items and their details. |
Create and send e-invoices in bulk
Endpoint
POST /v1/api-invoices/bulk_send/
Request body
The request body must be an array of invoice objects. You can include up to 50 invoice objects in one request.
Request
curl --location \
--request POST 'https://api.wafeq.com/v1/api-invoices/bulk_send/' \
--header 'Authorization: Api-Key <api_key>' \
--header 'Content-Type: application/json' \
--data-raw '[
{
"reference": "test",
"invoice_number": "TEST-INV-1234",
"invoice_date": "2021-01-01",
"currency": "SAR",
"paid_through_account": "<paid_through_account_id>",
"language": "en",
"tax_amount_type": "TAX_INCLUSIVE",
"contact": {
"name": "Ahmed A.",
"address": "Ahmed A. Building, first floor, Riyadh, Saudi Arabia",
"email": "ahmed@example.com"
},
"channels": [
{
"medium": "email",
"data": {
"subject": "Invoice X from the Company of Abdullah S. Trading",
"message": "<p>Please find attached your invoice.</p>",
"recipients": {
"to": [
"<to_email>"
],
"cc": [
],
"bcc": [
]
}
}
}
],
"line_items": [
{
"name": "Item 1",
"description": "Item description 1",
"account": "<account_id>",
"quantity": 2,
"price": 40,
"tax_rate": "<tax_rate_id>"
},
{
"name": "Item 2",
"description": "Item description 2",
"account": "<account_id>",
"quantity": 3,
"price": 20,
"tax_rate": "<tax_rate_id>"
}
]
}
]'
e-Invoices are not sent to ZATCA in Phase 1
ZATCA has currently implemented only Phase 1 of the e-invoicing law, which means invoices are not sent to ZATCA during this phase. Wafeq will be integrated with ZATCA in phase 2, which is expected to launch in waves in 2023. Reach out to our support if you're part of the early waves so we can assist.
Contact
Attributes | Type | Required | Description |
---|---|---|---|
name | string | True | Name. |
string | False | Email. | |
address | string | False | Address. |
city | string | False | City. |
country | string | False | Country. |
tax_registration_number | string | False | Tax Registration Number. |
Channel
Attributes | Type | Required | Description |
---|---|---|---|
medium | string | True | Type of the channel to be used i.e. email |
data | ChannelData | True | Info required by the channel |
Below is the table to find corresponding Data objects for each medium.
medium | data |
---|---|
email | EmailData |
Discount
Attributes | Type | Required | Description |
---|---|---|---|
type | string | True | Type of discount. One of percent , amount . |
value | decimal | True | Value of the discount. |
LineItem
Attributes | Type | Required | Description |
---|---|---|---|
name | string | True | Name of line item. |
description | string | True | Description of the line item. |
account | string | False | The Account to categorize this line item. |
quantity | int | False | Quanity. |
price | decimal | True | Price. |
tax_rate | [string ] | False | id of the tax rate of applicable on the item. |
discount | Discount | False | Discount details. |
EmailData
Attributes | Type | Required | Description |
---|---|---|---|
subject | string | True | Subject of the email. |
message | string | True | Mail body of the email. |
recipients | Recipients | True | Details about the recipients. |
Recipients
Attributes | Type | Required | Description |
---|---|---|---|
to | array[string] | True | Array of to emails. |
bcc | array[string] | False | Array of bcc emails. |
cc | array[string] | False | Array of cc emails. |
List invoices
Request
curl --location \
--request GET 'https://api.wafeq.com/v1/invoices/' \
--header 'Authorization: Api-Key <api_key>' \
--header 'Content-Type: application/json'
Summary Invoice
This API can be used to fetch a a list of summary invoices equivalent to all the Bulk Invoices sent grouped by month of invoice date, currency, paid through account, tax amount type and tax rate for the provided date range between from_date
and to to_date
.
Endpoints
GET /v1/api-invoices/summary/?from_date=<from_date>&to_date=<to_date>