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.
email	`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>