Invoices (Bulk)

Endpoints

GET /v1/api-invoices/
GET /v1/api-invoices/:id
DELETE /v1/api-invoices/:id
POST /v1/api-invoices/bulk_send/

Invoice object

AttributesTypeRequiredDescription
referencestringFalseInvoice reference code.
invoice_numberstringTrueInvoice number.
invoice_datestringTrueInvoice date in YYYY-MM-DD e.g. 2021-01-01.
currencystringTrueCurrency to be used in the invoice.
paid_through_accountstringFalseThe Account where the invoice was paid through, for example a bank account.
languagestringTrueLanguage in which the invoice will be generated. en or ar.
notesstringFalseExtra notes to be added at the end of the invoice.
tax_amount_typestringFalseWhether LineItem prices are exclusive or inclusive of taxes. One of TAX_INCLUSIVE, TAX_EXCLUSIVE.
contactContactTrueContact details to be displayed on the Invoice.
channelsarray[Channel]TrueList of channels to be used to send the invoice.
line_itemsarray[LineItem]TrueList 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

AttributesTypeRequiredDescription
namestringTrueName.
emailstringFalseEmail.
addressstringFalseAddress.
citystringFalseCity.
countrystringFalseCountry.
tax_registration_numberstringFalseTax Registration Number.

Channel

AttributesTypeRequiredDescription
mediumstringTrueType of the channel to be used i.e. email
dataChannelDataTrueInfo required by the channel

Below is the table to find corresponding Data objects for each medium.

mediumdata
emailEmailData

Discount

AttributesTypeRequiredDescription
typestringTrueType of discount. One of percent, amount.
valuedecimalTrueValue of the discount.

LineItem

AttributesTypeRequiredDescription
namestringTrueName of line item.
descriptionstringTrueDescription of the line item.
accountstringFalseThe Account to categorize this line item.
quantityintFalseQuanity.
pricedecimalTruePrice.
tax_rate[string]Falseid of the tax rate of applicable on the item.
discountDiscountFalseDiscount details.

EmailData

AttributesTypeRequiredDescription
subjectstringTrueSubject of the email.
messagestringTrueMail body of the email.
recipientsRecipientsTrueDetails about the recipients.

Recipients

AttributesTypeRequiredDescription
toarray[string]TrueArray of to emails.
bccarray[string]FalseArray of bcc emails.
ccarray[string]FalseArray 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'