---
title: Getting started
pageTitle: Wafeq e-invoicing API
description: Send ZATCA-compliant e-invoices at scale.
---

Issue ZATCA-compliant e-invoices at scale. Send your first invoice for free in a couple of minutes.{% .lead %}

{% quick-links %}

{% quick-link title="Get your API Key" icon="installation" href="/docs/introduction/setup" description="Sign up to Wafeq and get your API key." /%}

{% quick-link title="Send your first invoice" icon="presets" href="/docs/introduction/send-your-first-e-invoice" description="Send an e-invoice by email." /%}

{% quick-link title="API reference" icon="theming" href="/docs/api-reference/api-invoices" description="All the details you need to know." /%}
{% quick-link title="Read our FAQ" icon="presets" href="/docs/support/faq" description="Some common questions and answers." /%}

{% /quick-links %}

---

## Quick start

1. {% relative-link href="/docs/introduction/setup" %}Get your API key{% /relative-link %} from your [Wafeq Developer Console](https://app.wafeq.com/c/api-keys).
2. Send an invoice by pasting the below code in your terminal. Make sure to replace `<api_key>` with your API key and `<to_email>` with your email.

{% partial file="send-your-first-e-invoice.md" /%}


---
title: إبدأ مع وافِق
pageTitle: Wafeq e-invoicing API
description: Send ZATCA-compliant e-invoices at scale.
---

إبدأ بكل سهولة.{% .lead %}

{% quick-links %}

{% quick-link title="Get your API Key" icon="installation" href="/docs/introduction/setup" description="Sign up to Wafeq and get your API key." /%}

{% quick-link title="Send your first invoice" icon="presets" href="/docs/introduction/send-your-first-e-invoice" description="Send an e-invoice by email." /%}

{% quick-link title="API reference" icon="theming" href="/docs/api-reference/api-invoices" description="All the details you need to know." /%}
{% quick-link title="Read our FAQ" icon="presets" href="/docs/support/faq" description="Some common questions and answers." /%}

{% /quick-links %}

---

## Quick start

1. {% relative-link href="/docs/introduction/setup" %}Get your API key{% /relative-link %} from your [Wafeq Developer Console](https://app.wafeq.com/c/api-keys).
2. Send an invoice by pasting the below code in your terminal. Make sure to replace `<api_key>` with your API key and `<to_email>` with your email.

{% partial file="send-your-first-e-invoice.md" /%}


---
title: Accounts
section: api-reference
---

Represents an account from your Chart of Accounts.

## Endpoints

{% endpoint %}
GET {% $endpoints.accounts.base %}
GET {% $endpoints.accounts.base %}:id/
POST {% $endpoints.accounts.base %}
PATCH {% $endpoints.accounts.base %}:id/
DELETE {% $endpoints.accounts.base %}:id/
{% /endpoint %}


## The account object
Attributes | Type | Description
--------- | ---- | ----------- 
id | `string` | id of the object.
account_code | `string` | The account code.
name_en | `string` | The name of the account in English.
name_ar | `string` | The name of the account in Arabic.
classification | `string` | One of `REVENUE`, `EXPENSE`, `ASSET`, `LIABILITY`, `EQUITY`.
sub_classification | `string` | One of `INCOME`, `OTHER_INCOME`, `COGS`, `OPERATING_EXPENSE`, `NON_OPERATING_EXPENSE`, `CASH_EQUIVALENTS`, `CURRENT_ASSET`, `NON_CURRENT_ASSET`, `FIXED_ASSET`, `CURRENT_LIABILITY`, `NON_CURRENT_LIABILITY`, `PAID_IN_CAPITAL`, `RETAINED_EARNINGS`, `ACCUMULATED_OTHER_COMPREHENSIVE_INCOME`, `TREASURY_STOCK`, `OPENING_BALANCE_EQUITY`, `OWNERS_EQUITY`.
is_payment_enabled | `true`, `false` | `true` if the account is allowed to be set on a `paid_through_account` field, `false` otherwise.
is_system | `true`, `false` | `true` if the account is a system account.


#### Example
```json
{
    "id": "acc_x908asdlmn298123lnm",
    "account_code": "200",
    "name_en": "Sales",
    "name_ar": "مبيعات",
    "is_system": false,
    "classification": "REVENUE",
    "sub_classification": "INCOME",
    "is_payment_enabled": false
}
```


## List accounts
{% endpoint %}
GET {% $endpoints.accounts.base %}
{% /endpoint %}

{% triablerequest sample="ACCOUNTS" /%}

### Filters
Query param | Possible values | Description
--------- | ---- | -------- 
classification | One of `REVENUE`, `EXPENSE`, `ASSET`, `LIABILITY`, `EQUITY` | The classification of the account.
include_system | `true`, `false` | `true` if you want to include system accounts in the response, `false` otherwise. Defaults to `false`.
is_payment_enabled | `true`, `false` | `true` if the account is allowed to be set on a `paid_through_account` field, `false` otherwise.

{% triablerequest sample="ACCOUNTS_PAID_THROUGH" /%}


## Create account
{% endpoint %}
POST {% $endpoints.accounts.base %}
{% /endpoint %}

### Request body
Attributes | Type | Description
--------- | ---- | ----------- 
name_en | `string` | The name of the account in English.
name_ar | `string` | The name of the account in Arabic.
sub_classification | `string` | One of `INCOME`, `OTHER_INCOME`, `COGS`, `OPERATING_EXPENSE`, `NON_OPERATING_EXPENSE`, `CASH_EQUIVALENTS`, `CURRENT_ASSET`, `NON_CURRENT_ASSET`, `FIXED_ASSET`, `CURRENT_LIABILITY`, `NON_CURRENT_LIABILITY`, `PAID_IN_CAPITAL`, `RETAINED_EARNINGS`, `ACCUMULATED_OTHER_COMPREHENSIVE_INCOME`, `TREASURY_STOCK`, `OPENING_BALANCE_EQUITY`, `OWNERS_EQUITY`.
account_code | `string` | (Optional) The account code.

{% triablerequest sample="ACCOUNTS_CREATE" /%}

## Update account
{% endpoint %}
PATCH {% $endpoints.accounts.base %}:id/
{% /endpoint %}

If the account is already tied to a journal, you can only modify `is_payment_enabled` and `account_code`.

### Request body
Attributes | Type | Description
--------- | ---- | ----------- 
name_en | `string` | The name of the account in English.
name_ar | `string` | The name of the account in Arabic.
sub_classification | `string` | One of `INCOME`, `OTHER_INCOME`, `COGS`, `OPERATING_EXPENSE`, `NON_OPERATING_EXPENSE`, `CASH_EQUIVALENTS`, `CURRENT_ASSET`, `NON_CURRENT_ASSET`, `FIXED_ASSET`, `CURRENT_LIABILITY`, `NON_CURRENT_LIABILITY`, `PAID_IN_CAPITAL`, `RETAINED_EARNINGS`, `ACCUMULATED_OTHER_COMPREHENSIVE_INCOME`, `TREASURY_STOCK`, `OPENING_BALANCE_EQUITY`, `OWNERS_EQUITY`.
account_code | `string` | The account code.
is_payment_enabled | `true`, `false` | `true` if the account is allowed to be set on a `paid_through_account` field, `false` otherwise.

## Delete account

Delete an account for your organization. However you cannot delete an account that has been used to book an invoice or an expense.

{% endpoint %}
DELETE {% $endpoints.accounts.base %}:id/
{% /endpoint %}


---
title: Invoices (Bulk)
section: api-reference
---

## Endpoints

{% endpoint %}
GET {% $endpoints.invoices_bulk.base %}
GET {% $endpoints.invoices_bulk.base %}:id
DELETE {% $endpoints.invoices_bulk.base %}:id
POST {% $endpoints.invoices_bulk.base %}bulk_send/
{% /endpoint %}


## 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`](/docs/api-reference/accounts) 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`](#line-item) prices are exclusive or inclusive of taxes. One of `TAX_INCLUSIVE`, `TAX_EXCLUSIVE`.
contact | [`Contact`](#contact) | `True` | Contact details to be displayed on the Invoice.
channels | `array[`[`Channel`](#channel)`]` | `True` | List of channels to be used to send the invoice.
line_items | `array[`[`LineItem`](#line-item)`]` | `True` | List of line items and their details.

## Create and send e-invoices in bulk

#### Endpoint
{% endpoint %}
POST {% $endpoints.invoices_bulk.base %}bulk_send/
{% /endpoint %}

#### Request body
The request body must be an array of [invoice objects](#invoice-object). You can include up to 50 invoice objects in one request.

{% triablerequest sample="INVOICES_BULK_SEND" /%}

{% partial file="e-invoices-not-sent.md" /%}


## 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 {% #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`](#email-data)

## Discount

Attributes | Type | Required | Description
--------- | ---- | -------- | -----------
type | `string` | `True` | Type of discount. One of `percent`, `amount`.
value | `decimal` | `True` | Value of the discount.


## LineItem {% #line-item %}
Attributes | Type | Required | Description
--------- | ---- | -------- | ----------- 
name | `string` | `True` | Name of line item.
description | `string` | `True` | Description of the line item.
account | `string` | `False` | The [`Account`](/docs/api-reference/accounts) 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`](#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`](#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
{% triablerequest sample="INVOICES_LIST" /%}



---
title: Bank Accounts
section: api-reference
---

Represents a bank account and the account that is linked to it.

## Endpoints

{% endpoint %}
GET {% $endpoints.bank_accounts.base %}
GET {% $endpoints.bank_accounts.base %}:id/
POST {% $endpoints.bank_accounts.base %}
PATCH {% $endpoints.bank_accounts.base %}:id/
DELETE {% $endpoints.bank_accounts.base %}:id/
{% /endpoint %}


## The bank account object
Attributes | Type | Description
--------- | ---- | ----------- 
id | `string` | id of the object.
name | `string` | The name of the bank account.
currency | `string` | The currency of the bank account.
classification | `string` | One of `ASSET` or `LIABILITY`.
sub_classification | `string` | One of `BANK`, `PETTY_CASH` or `CREDIT_CARD`.
account | `string` | The id of the account underlying this bank account.


#### Example
```json
{
    "id": "ba_iDp8ZyYzHc2HJDckmeGtV2",
    "name": "My bank account",
    "currency": "SAR",
    "classification": "ASSET",
    "sub_classification": "PETTY_CASH",
    "account": "acc_2nqzog3ZRXegUgvLWEVJ84"
}
```


## List bank accounts
{% endpoint %}
GET {% $endpoints.bank_accounts.base %}
{% /endpoint %}

{% triablerequest sample="BANK_ACCOUNTS" /%}

### Filters
Query param | Possible values | Description
--------- | ---- | -------- 
sub_classification | One of `BANK`, `PETTY_CASH` or `CREDIT_CARD` | The sub classification of the bank account.
currency | A valid currency | The currency of the bank account

{% triablerequest sample="BANK_ACCOUNTS_BANK" /%}


## Create bank account
{% endpoint %}
POST {% $endpoints.bank_accounts.base %}
{% /endpoint %}

### Request body
Attributes | Type | Description
--------- | ---- | ----------- 
name | `string` | The name of the bank account.
sub_classification | `string` | One of `BANK`, `PETTY_CASH` or `CREDIT_CARD`.
currency | `string` | The bank account currency.

{% triablerequest sample="BANK_ACCOUNTS_CREATE" /%}

## Update bank account
{% endpoint %}
PATCH {% $endpoints.bank_accounts.base %}:id/
{% /endpoint %}

Any change to the `sub_classification` field will result in changes to the `classification` and `sub_classification` of the linked account.

### Request body
Attributes | Type | Description
--------- | ---- | ----------- 
name | `string` | The name of the bank account.
sub_classification | `string` | One of `BANK`, `PETTY_CASH` or `CREDIT_CARD`.
currency | `string` | The bank account currency.

## Delete bank account

Delete a bank account for your organization. However you cannot delete a bank account that has been used to book an invoice or an expense.

{% endpoint %}
DELETE {% $endpoints.bank_accounts.base %}:id/
{% /endpoint %}


---
title: Ledger bank transactions
section: api-reference
---

## Endpoints

All the endpoints related to bank transactions in the bank account ledgers need a specific `bank_account` in the path.
 
{% endpoint %}
GET {% $endpoints.bank_ledgers.base %}
GET {% $endpoints.bank_ledgers.base %}:id/
POST {% $endpoints.bank_ledgers.base %}
PATCH {% $endpoints.bank_ledgers.base %}:id/
DELETE {% $endpoints.bank_ledgers.base %}:id/
{% /endpoint %}


## Ledger bank transaction object

Ledger bank transactions are accounting transactions using the bank account. They can be `manual`, in the sense
that they were created by a user (for instance to start from a specific balance). They are not `manual` when the
system generated them, because an invoice / expense / bill used the bank account as the paid through account.

Attribute | Type  | Description
---------- | ----- | -----------
id | `string` | id of the ledger bank transaction
bank_account | `string` | (Readonly) id of the bank account
account | `string` | id of the account
date | `string` | The date of the transaction
amount | `number` | The transaction amount
description | `string` | A description attached to the transaction
reference | `string` | A reference attached to the transaction
is_manual | `boolean` | (Readonly) True when the transaction was created by a user

#### Example
```json
{
    "id": "bt_KabEvYZwpUQCevDJycmVWu",
    "bank_account": "ba_9t79bCG2Q6SxPxQBqva8z9",
    "account": "acc_x908asdlmn298123lnm",
    "date": "2019-12-29",
    "amount": 1000.0,
    "description": "Set bank account initial balance",
    "reference": "",
    "is_manual": true
}
```


## List ledger bank transactions
{% endpoint %}
GET {% $endpoints.bank_ledgers.base %}
{% /endpoint %}

{% triablerequest sample="BANK_LEDGERS" /%}

### Filters
Query param | Possible values | Description
--------- | ---- | -------- 
account | `string` | The identifier of the account.
date_after | `string` | Transactions that are booked on or after the date.
date_before | `string` | Transactions that are booked before the date.
amount_min | `number` | Transactions with this minimum amount.
amount_max | `number` | Transactions with this maximum amount.

{% triablerequest sample="BANK_LEDGERS_AMOUNT" /%}


## Create ledger bank transactions
{% endpoint %}
POST {% $endpoints.bank_ledgers.base %}
{% /endpoint %}

### Request body
Attribute | Type  | Description
---------- | ----- | -----------
date | `string` | The date of the transaction
account | `string` | The id of the account
amount | `number` | The transaction amount
description | `string` | A description attached to the transaction
reference | `string` | A reference attached to the transaction

## Update ledger bank transaction
{% endpoint %}
PATCH {% $endpoints.bank_ledgers.base %}:id/
{% /endpoint %}

You can only update ledger bank transactions that have `is_manual` set to `true`.


### Request body
Attributes | Type | Description
--------- | ---- | ----------- 
date | `string` | The date of the transaction
account | `string` | The id of the account
amount | `number` | The transaction amount
description | `string` | A description attached to the transaction
reference | `string` | A reference attached to the transaction

## Delete ledger bank transactions

{% endpoint %}
DELETE {% $endpoints.bank_ledgers.base %}:id/
{% /endpoint %}


---
title: Statement bank transactions
section: api-reference
---

## Endpoints

All the endpoints related to bank transactions in the bank account statements need a specific `bank_account` in the path.
 
{% endpoint %}
GET {% $endpoints.bank_statements.base %}
GET {% $endpoints.bank_statements.base %}:id/
POST {% $endpoints.bank_statements.base %}
PATCH {% $endpoints.bank_statements.base %}:id/
DELETE {% $endpoints.bank_statements.base %}:id/
{% /endpoint %}


## Statement bank transaction object

Statement bank transactions are the transactions usually found in bank statements. They are useful to track
and compare the balance as reported by the bank (`statement_balance`) with the balance
computed by all the transactions (`calculated_balance`).

Attribute | Type  | Description
---------- | ----- | -----------
id | `string` | id of the statement bank transaction
bank_account | `string` | (Readonly) id of the bank account
date | `string` | The date of the statement
amount | `number` | The statement amount
statement_balance | `number` | The balance as reported by the bank
calculated_balance | `number` | (Readonly) The balace computed from all statements
description | `string` | A description attached to the statement
reference | `string` | A reference attached to the statement
is_posted | `boolean` | (Readonly) Whether the bank statement is reconciled

#### Example
```json
{
    "id": "bt_KabEvYZwpUQCevDJycmVWu",
    "bank_account": "ba_9t79bCG2Q6SxPxQBqva8z9",
    "date": "2019-12-29",
    "amount": -1000.0,
    "statement_balance": -1000.0,
    "calculated_balance": -1000.0,
    "description": "Payment",
    "reference": "121",
    "is_posted": false
}
```


## List statement bank transactions
{% endpoint %}
GET {% $endpoints.bank_statements.base %}
{% /endpoint %}

{% triablerequest sample="BANK_STATEMENTS" /%}

### Filters
Query param | Possible values | Description
--------- | ---- | -------- 
date_after | `string` | Statements that are booked on or after the date.
date_before | `string` | Statements that are booked before the date.
amount_min | `number` | Statements with this minimum amount.
amount_max | `number` | Statements with this maximum amount.

{% triablerequest sample="BANK_STATEMENTS_AMOUNT" /%}


## Create statement bank transactions
{% endpoint %}
POST {% $endpoints.bank_statements.base %}
{% /endpoint %}

### Request body
Attribute | Type  | Description
---------- | ----- | -----------
date | `string` | The date of the statement
amount | `number` | The statement amount
statement_balance | `number` | The balance as reported by the bank
description | `string` | A description attached to the statement
reference | `string` | A reference attached to the statement

## Update bank statement
{% endpoint %}
PATCH {% $endpoints.bank_statements.base %}:id/
{% /endpoint %}


### Request body
Attributes | Type | Description
--------- | ---- | ----------- 
date | `string` | The date of the statement
amount | `number` | The statement amount
statement_balance | `number` | The balance as reported by the bank
description | `string` | A description attached to the statement
reference | `string` | A reference attached to the statement

## Delete statement bank transactions

{% endpoint %}
DELETE {% $endpoints.bank_statements.base %}:id/
{% /endpoint %}


---
title: Contacts
section: api-reference
---

## Endpoints

{% endpoint %}
GET {% $endpoints.contacts.base %}
GET {% $endpoints.contacts.base %}:id/
POST {% $endpoints.contacts.base %}
PATCH {% $endpoints.contacts.base %}:id/
DELETE {% $endpoints.contacts.base %}:id/
{% /endpoint %}


## Contact object
Attributes | Type  | Description
---------- | ----- | -----------
id | `string` | id of the contact
name | `string` |  Name
email | `string` | Email
address | `string` | Address
city | `string` | City
country | `string` | ISO 3166 two-letter country code
tax_registration_number | `string` | Tax Registration Number
relationship | `string[]` | A list of tags, can be `Customer`,  `Supplier`, `Investor`, `Partner`, `Other`

#### Example
```json
{
    "id": "co_hTNcixkrGGnhWnCiAxnCjP",
    "name": "Honest Veggies",
    "relationship": ["Supplier"],
    "email": "info@honestveggies.com",
    "address": "Malek street, 1st floor, office 1000",
    "city": "Riyadh",
    "country": "SA",
    "tax_registration_number": "100092309810991",
}
```


## List contacts
{% endpoint %}
GET {% $endpoints.contacts.base %}
{% /endpoint %}

{% triablerequest sample="CONTACTS" /%}

### Filters
Query param | Possible values | Description
--------- | ---- | -------- 
relationship | Comma separated list of a subset of `Customer`,  `Supplier`, `Investor`, `Partner`, `Other` | The relationship to the contact.
country | `string` | The country code of the contact.

{% triablerequest sample="CONTACTS_SUPPLIER_OR_PARTNER" /%}


## Create contact
{% endpoint %}
POST {% $endpoints.contacts.base %}
{% /endpoint %}

### Request body
Attributes | Type  | Description
---------- | ----- | -----------
name | `string` |  Name (required)
email | `string` | Email
address | `string` | Address
city | `string` | City
country | `string` | ISO 3166 two-letter country code
tax_registration_number | `string` | Tax Registration Number
relationship | `string[]` | A list of tags, can be `Customer`,  `Supplier`, `Investor`, `Partner`, `Other`

{% triablerequest sample="CONTACTS_CREATE" /%}

## Update contact
{% endpoint %}
PATCH {% $endpoints.contacts.base %}:id/
{% /endpoint %}


### Request body
Attributes | Type | Description
--------- | ---- | ----------- 
name | `string` |  Name
email | `string` | Email
address | `string` | Address
city | `string` | City
country | `string` | ISO 3166 two-letter country code
tax_registration_number | `string` | Tax Registration Number
relationship | `string[]` | A list of tags, can be `Customer`,  `Supplier`, `Investor`, `Partner`, `Other`

## Delete contact

{% endpoint %}
DELETE {% $endpoints.contacts.base %}:id/
{% /endpoint %}


---
title: Credit Notes
section: api-reference
---

## Endpoints

{% endpoint %}
GET {% $endpoints.credit_notes.base %}
GET {% $endpoints.credit_notes.base %}:id/
POST {% $endpoints.credit_notes.base %}
PATCH {% $endpoints.credit_notes.base %}:id/
DELETE {% $endpoints.credit_notes.base %}:id/
GET {% $endpoints.credit_notes.base %}:id/download/
GET {% $endpoints.credit_notes.base %}:id/line-items/
POST {% $endpoints.credit_notes.base %}:id/line-items/:line_item_id/
PATCH {% $endpoints.credit_notes.base %}:id/line-items/:line_item_id/
DELETE {% $endpoints.credit_notes.base %}:id/line-items/:line_item_id/
{% /endpoint %}


## Credit Note object

Attributes | Type | Description
---------- | ---- | -----------
id | `string` | The id of the object.
amount | `number` | The credit note amount.
contact | `string` | The id of the contact.
currency | `string` | The currency used in the credit note.
credit_note_number | `string` | The credit note number.
credit_note_date | `string` | The date of the credit note.
language | `string` | The language used in the credit note.
line_items | `array` | The line items of the credit note.
reference | `string` | The reference of the credit note.
status | `string` | The status of the credit note.
tax_amount | `number` | The tax amount.
tax_amount_type | `string` | Either `TAX_INCLUSIVE` or `TAX_EXCLUSIVE`.

#### Example
```json
{
    "amount": 115.0,
    "contact": "co_HS9cspuVZJUHdqVsS9CFfY",
    "currency": "AED",
    "id": "cn_YEdmVKecVi45RYWcrt2rJe",
    "credit_note_date": "2022-10-05",
    "credit_note_number": "CN-000100",
    "language": "en",
    "line_items": [
        {
            "account": "acc_7jpGSFEGGF9cK39vwoDPBt",
            "description": "Line item",
            "id": "cnli_Zhf8cUxzjiRRs8Ga7MCgWE",
            "line_amount": 115.0,
            "quantity": 1.0,
            "tax_amount": 15.0,
            "tax_rate": "tax_c8TkJLeXZYJmWuSjqGzGzj",
            "unit_amount": 100.0
        }
    ],
    "reference": "",
    "status": "DRAFT",
    "tax_amount": 15.0,
    "tax_amount_type": "TAX_EXCLUSIVE"
}
```

## Get credit note

### Endpoint
{% endpoint %}
GET {% $endpoints.credit_notes.base %}:id/
{% /endpoint %}

#### Response sample
```json
{
    "amount": 115.0,
    "contact": "co_HS9cspuVZJUHdqVsS9CFfY",
    "currency": "AED",
    "id": "cn_YEdmVKecVi45RYWcrt2rJe",
    "credit_note_date": "2022-10-05",
    "credit_note_number": "CN-000100",
    "language": "en",
    "line_items": [
        {
            "account": "acc_7jpGSFEGGF9cK39vwoDPBt",
            "description": "Line item",
            "id": "cnli_Zhf8cUxzjiRRs8Ga7MCgWE",
            "line_amount": 115.0,
            "quantity": 1.0,
            "tax_amount": 15.0,
            "tax_rate": "tax_c8TkJLeXZYJmWuSjqGzGzj",
            "unit_amount": 100.0
        }
    ],
    "reference": "",
    "status": "DRAFT",
    "tax_amount": 15.0,
    "tax_amount_type": "TAX_EXCLUSIVE"
}
```


## List credit notes

### Endpoint
{% endpoint %}
GET {% $endpoints.credit_notes.base %}
{% /endpoint %}

### Filters
Query param | Type | Description
----------- | ---- | -----------
contact | `string` | The id of the contact.
credit_note_date | `string` | The credit note date in `YYYY-MM-DD` e.g. `2021-01-01`.

{% triablerequest sample="CREDIT_NOTES" /%}


## Create credit note

### Endpoint
{% endpoint %}
POST {% $endpoints.credit_notes.base %}
{% /endpoint %}

### Request body
Attributes | Type | Description
---------- | ---- | -----------
amount | `number` | The credit note amount.
contact | `string` | The id of the contact.
currency | `string` | The currency used in the credit note.
credit_note_number | `string` | The credit note number.
credit_note_date | `string` | The date of the credit note.
language | `string` | The language used in the credit note.
line_items | `array` | The line items of the credit note.
reference | `string` | The reference of the credit note.
tax_amount | `number` | The tax amount.
tax_amount_type | `string` | Either `TAX_INCLUSIVE` or `TAX_EXCLUSIVE`.

{% triablerequest sample="CREDIT_NOTES_CREATE" /%}

## Update credit note
{% endpoint %}
PATCH {% $endpoints.credit_notes.base %}:id/
{% /endpoint %}

### Request body
Attributes | Type | Description
---------- | ---- | -----------
id | `string` | The id of the object.
amount | `number` | The credit note amount.
contact | `string` | The id of the contact.
currency | `string` | The currency used in the credit note.
credit_note_number | `string` | The credit note number.
credit_note_date | `string` | The date of the credit note.
language | `string` | The language used in the credit note.
reference | `string` | The reference of the credit note.
tax_amount_type | `string` | Either `TAX_INCLUSIVE` or `TAX_EXCLUSIVE`.

To update the line items, you need to use the credit notes line items endpoints.

## Delete credit note
{% endpoint %}
DELETE {% $endpoints.credit_notes.base %}:id/
{% /endpoint %}

## Download credit note
{% endpoint %}
GET {% $endpoints.credit_notes.base %}:id/download/
{% /endpoint %}


## Credit Note line item object

Attribute | Type | Description
--------- | ---- | -----------
account | `string` | The id of the account.
description | `string` | The description of the line item.
id | `string` | The id of the object.
line_amount | `number` | The line amount.
quantity | `number` | The quantity.
tax_amount | `number` | The tax amount.
tax_rate | `string` | The id of the tax rate.
unit_amount | `number` | The unit amount.

#### Example
```json
{
    "account": "acc_7jpGSFEGGF9cK39vwoDPBt",
    "description": "Line item",
    "id": "cnli_Zhf8cUxzjiRRs8Ga7MCgWE",
    "line_amount": 115.0,
    "quantity": 1.0,
    "tax_amount": 15.0,
    "tax_rate": "tax_c8TkJLeXZYJmWuSjqGzGzj",
    "unit_amount": 100.0
}
```

## Get credit note line item

### Endpoint
{% endpoint %}
POST {% $endpoints.credit_notes.base %}:id/line-item/
{% /endpoint %}

#### Response sample
```json
{
    "account": "acc_7jpGSFEGGF9cK39vwoDPBt",
    "description": "Line item",
    "id": "cnli_Zhf8cUxzjiRRs8Ga7MCgWE",
    "line_amount": 115.0,
    "quantity": 1.0,
    "tax_amount": 15.0,
    "tax_rate": "tax_c8TkJLeXZYJmWuSjqGzGzj",
    "unit_amount": 100.0
}
```

## List credit note line items

### Endpoint
{% endpoint %}
GET {% $endpoints.credit_notes.base %}:id/line-items/
{% /endpoint %}

### Filters
Query param | Type | Description
----------- | ---- | -----------
account | `string` | The id of the account.

## Create credit note line item

### Endpoint
{% endpoint %}
POST {% $endpoints.credit_notes.base %}:id/line-items/
{% /endpoint %}

### Request body
Attributes | Type | Description
---------- | ---- | -----------
account | `string` | The id of the account.
description | `string` | The description of the line item.
quantity | `number` | The quantity.
tax_rate | `string` | The id of the tax rate.
unit_amount | `number` | The unit amount.

## Update credit note line item
{% endpoint %}
PATCH {% $endpoints.credit_notes.base %}:id/line-items/:line_item_id/
{% /endpoint %}

### Request body
Attributes | Type | Description
---------- | ---- | -----------
account | `string` | The id of the account.
description | `string` | The description of the line item.
quantity | `number` | The quantity.
tax_rate | `string` | The id of the tax rate.
unit_amount | `number` | The unit amount.

## Delete credit note line item
{% endpoint %}
DELETE {% $endpoints.credit_notes.base %}:id/line-items/:line_item_id/
{% /endpoint %}


---
title: Debit Notes
section: api-reference
---

## Endpoints

{% endpoint %}
GET {% $endpoints.debit_notes.base %}
GET {% $endpoints.debit_notes.base %}:id/
POST {% $endpoints.debit_notes.base %}
PATCH {% $endpoints.debit_notes.base %}:id/
DELETE {% $endpoints.debit_notes.base %}:id/
GET {% $endpoints.debit_notes.base %}:id/download/
GET {% $endpoints.debit_notes.base %}:id/line-items/
POST {% $endpoints.debit_notes.base %}:id/line-items/:line_item_id/
PATCH {% $endpoints.debit_notes.base %}:id/line-items/:line_item_id/
DELETE {% $endpoints.debit_notes.base %}:id/line-items/:line_item_id/
{% /endpoint %}


## Debit Note object

Attributes | Type | Description
---------- | ---- | -----------
id | `string` | The id of the object.
amount | `number` | The debit note amount.
contact | `string` | The id of the contact.
currency | `string` | The currency used in the debit note.
debit_note_number | `string` | The debit note number.
debit_note_date | `string` | The date of the debit note.
language | `string` | The language used in the debit note.
line_items | `array` | The line items of the debit note.
reference | `string` | The reference of the debit note.
status | `string` | The status of the debit note.
tax_amount | `number` | The tax amount.
tax_amount_type | `string` | Either `TAX_INCLUSIVE` or `TAX_EXCLUSIVE`.

#### Example
```json
{
    "amount": 115.0,
    "contact": "co_HS9cspuVZJUHdqVsS9CFfY",
    "currency": "AED",
    "id": "cn_YEdmVKecVi45RYWcrt2rJe",
    "debit_note_date": "2022-10-05",
    "debit_note_number": "DN-000100",
    "language": "en",
    "line_items": [
        {
            "account": "acc_7jpGSFEGGF9cK39vwoDPBt",
            "description": "Line item",
            "id": "cnli_Zhf8cUxzjiRRs8Ga7MCgWE",
            "line_amount": 115.0,
            "quantity": 1.0,
            "tax_amount": 15.0,
            "tax_rate": "tax_c8TkJLeXZYJmWuSjqGzGzj",
            "unit_amount": 100.0
        }
    ],
    "reference": "",
    "status": "DRAFT",
    "tax_amount": 15.0,
    "tax_amount_type": "TAX_EXCLUSIVE"
}
```

## Get debit note

### Endpoint
{% endpoint %}
GET {% $endpoints.debit_notes.base %}:id/
{% /endpoint %}

#### Response sample
```json
{
    "amount": 115.0,
    "currency": "AED",
    "id": "dn_YEdmVKecVi45RYWcrt2rJe",
    "debit_note_date": "2022-10-05",
    "debit_note_number": "DN-000100",
    "language": "en",
    "line_items": [
        {
            "account": "acc_7jpGSFEGGF9cK39vwoDPBt",
            "description": "Line item",
            "id": "dnli_Zhf8cUxzjiRRs8Ga7MCgWE",
            "line_amount": 115.0,
            "quantity": 1.0,
            "tax_amount": 15.0,
            "tax_rate": "tax_c8TkJLeXZYJmWuSjqGzGzj",
            "unit_amount": 100.0
        }
    ],
    "reference": "",
    "status": "DRAFT",
    "tax_amount": 15.0,
    "tax_amount_type": "TAX_EXCLUSIVE"
}
```


## List debit notes

### Endpoint
{% endpoint %}
GET {% $endpoints.debit_notes.base %}
{% /endpoint %}

### Filters
Query param | Type | Description
----------- | ---- | -----------
contact | `string` | The id of the contact.
debit_note_date | `string` | The debit note date in `YYYY-MM-DD` e.g. `2021-01-01`.

{% triablerequest sample="CREDIT_NOTES" /%}


## Create debit note

### Endpoint
{% endpoint %}
POST {% $endpoints.debit_notes.base %}
{% /endpoint %}

### Request body
Attributes | Type | Description
---------- | ---- | -----------
amount | `number` | The debit note amount.
contact | `string` | The id of the contact.
currency | `string` | The currency used in the debit note.
debit_note_number | `string` | The debit note number.
debit_note_date | `string` | The date of the debit note.
language | `string` | The language used in the debit note.
line_items | `array` | The line items of the debit note.
reference | `string` | The reference of the debit note.
tax_amount | `number` | The tax amount.
tax_amount_type | `string` | Either `TAX_INCLUSIVE` or `TAX_EXCLUSIVE`.

{% triablerequest sample="CREDIT_NOTES_CREATE" /%}

## Update debit note
{% endpoint %}
PATCH {% $endpoints.debit_notes.base %}:id/
{% /endpoint %}

### Request body
Attributes | Type | Description
---------- | ---- | -----------
id | `string` | The id of the object.
amount | `number` | The debit note amount.
contact | `string` | The id of the contact.
currency | `string` | The currency used in the debit note.
debit_note_number | `string` | The debit note number.
debit_note_date | `string` | The date of the debit note.
language | `string` | The language used in the debit note.
reference | `string` | The reference of the debit note.
tax_amount_type | `string` | Either `TAX_INCLUSIVE` or `TAX_EXCLUSIVE`.

To update the line items, you need to use the debit notes line items endpoints.

## Delete debit note
{% endpoint %}
DELETE {% $endpoints.debit_notes.base %}:id/
{% /endpoint %}

## Download debit note
{% endpoint %}
GET {% $endpoints.debit_notes.base %}:id/download/
{% /endpoint %}


## Debit Note line item object

Attribute | Type | Description
--------- | ---- | -----------
account | `string` | The id of the account.
description | `string` | The description of the line item.
id | `string` | The id of the object.
line_amount | `number` | The line amount.
quantity | `number` | The quantity.
tax_amount | `number` | The tax amount.
tax_rate | `string` | The id of the tax rate.
unit_amount | `number` | The unit amount.

#### Example
```json
{
    "account": "acc_7jpGSFEGGF9cK39vwoDPBt",
    "description": "Line item",
    "id": "dnli_Zhf8cUxzjiRRs8Ga7MCgWE",
    "line_amount": 115.0,
    "quantity": 1.0,
    "tax_amount": 15.0,
    "tax_rate": "tax_c8TkJLeXZYJmWuSjqGzGzj",
    "unit_amount": 100.0
}
```

## Get debit note line item

### Endpoint
{% endpoint %}
POST {% $endpoints.debit_notes.base %}:id/line-item/
{% /endpoint %}

#### Response sample
```json
{
    "account": "acc_7jpGSFEGGF9cK39vwoDPBt",
    "description": "Line item",
    "id": "dnli_Zhf8cUxzjiRRs8Ga7MCgWE",
    "line_amount": 115.0,
    "quantity": 1.0,
    "tax_amount": 15.0,
    "tax_rate": "tax_c8TkJLeXZYJmWuSjqGzGzj",
    "unit_amount": 100.0
}
```

## List debit note line items

### Endpoint
{% endpoint %}
GET {% $endpoints.debit_notes.base %}:id/line-items/
{% /endpoint %}

### Filters
Query param | Type | Description
----------- | ---- | -----------
account | `string` | The id of the account.

## Create debit note line item

### Endpoint
{% endpoint %}
POST {% $endpoints.debit_notes.base %}:id/line-items/
{% /endpoint %}

### Request body
Attributes | Type | Description
---------- | ---- | -----------
account | `string` | The id of the account.
description | `string` | The description of the line item.
quantity | `number` | The quantity.
tax_rate | `string` | The id of the tax rate.
unit_amount | `number` | The unit amount.

## Update debit note line item
{% endpoint %}
PATCH {% $endpoints.debit_notes.base %}:id/line-items/:line_item_id/
{% /endpoint %}

### Request body
Attributes | Type | Description
---------- | ---- | -----------
account | `string` | The id of the account.
description | `string` | The description of the line item.
quantity | `number` | The quantity.
tax_rate | `string` | The id of the tax rate.
unit_amount | `number` | The unit amount.

## Delete debit note line item
{% endpoint %}
DELETE {% $endpoints.debit_notes.base %}:id/line-items/:line_item_id/
{% /endpoint %}


---
title: Errors
section: api-reference
---

## Response codes
Wafeq uses standard HTTP response codes:

Code | Description
--------- | ----
`200` | Success
`400` | Bad request
`401` | Unauthorized
`402` | Request failed
`403` | Forbidden
`404` | Not found
`429` | Too many requests
`5xx` | Server error




---
title: Expenses
section: api-reference
---

## Endpoints

{% endpoint %}
GET {% $endpoints.expenses.base %}
GET {% $endpoints.expenses.base %}:id/
POST {% $endpoints.expenses.base %}
PATCH {% $endpoints.expenses.base %}:id/
DELETE {% $endpoints.expenses.base %}:id/
{% /endpoint %}


## Expense object

Attributes | Type | Description
---------- | ---- | -----------
id | `string` | The id of the object.
account | `string` | The id of the account.
paid_through_account | `string` | The id of the account used for the payment.
contact | `string` | The id of the contact.
amount | `number` | The expense amount.
currency | `string` | The currency used in the expense.
tax_rate | `string` | The id of the tax rate.
amount_tax_type | `string` | Either `TAX_INCLUSIVE` or `TAX_EXCLUSIVE`.
description | `string` | The description attached to it.
date | `string` | The date of the expense.
reference | `string` | A reference attached to the expense.

#### Example
```json
{
	"account": "acc_ecKYVzRBqRqWhguoWqWqYT",
	"amount_tax_type": "TAX_INCLUSIVE",
	"amount": 12.0,
	"contact": null,
	"currency": "SAR",
	"date": "2022-07-19",
	"description": "A long description",
	"id": "exp_6E8yfeBkLUM2yi3m7F4aie",
	"paid_through_account": "acc_Xjwoy4VSKtVm6gEYcC9ZKR",
	"reference": "A reference to be reused",
	"tax_rate": "tax_BbdyVvf3kv6uj78nK5772t"
}
```

## Get expense

### Endpoint
{% endpoint %}
GET {% $endpoints.expenses.base %}:id/
{% /endpoint %}

#### Response sample
```json
{
	"account": "acc_ecKYVzRBqRqWhguoWqWqYT",
	"amount_tax_type": "TAX_INCLUSIVE",
	"amount": 12.0,
	"contact": null,
	"currency": "SAR",
	"date": "2022-07-19",
	"description": "A long description",
	"id": "exp_6E8yfeBkLUM2yi3m7F4aie",
	"paid_through_account": "acc_Xjwoy4VSKtVm6gEYcC9ZKR",
	"reference": "A reference to be reused",
	"tax_rate": "tax_BbdyVvf3kv6uj78nK5772t"
}
```


## List expenses

### Endpoint
{% endpoint %}
GET {% $endpoints.expenses.base %}
{% /endpoint %}

### Filters
Query param | Type | Description
----------- | ---- | -----------
account | `string` | The identifier of a account |
paid_through_account | `string` | The identifier of a paid_through_account |
contact | `string` | The identifier of a contact |

{% triablerequest sample="EXPENSES_PAID_THROUGH" /%}


## Create expense

### Endpoint
{% endpoint %}
POST {% $endpoints.expenses.base %}
{% /endpoint %}

### Request body
Attributes | Type | Description
---------- | ---- | -----------
date | `string` | The date of the expense.
account | `string` | The id of the expense account to categorize the expense.
paid_through_account | `string` | The id of the account used to pay for the expense.
currency | `string` | The currency used in the expense.
amount | `number` | The expense amount.
contact | `string` | (Optional) The id of the contact (vendor).
tax_rate | `string` | (Optional) The id of the tax rate.
amount_tax_type | `string` | (Optional) Either `TAX_INCLUSIVE` or `TAX_EXCLUSIVE`. Required if `tax_rate` is provided.
description | `string` | (Optional) The description attached to it.
reference | `string` | (Optional) A reference attached to the expense.

{% triablerequest sample="EXPENSES_CREATE" /%}

## Update expense
{% endpoint %}
PATCH {% $endpoints.expenses.base %}:id/
{% /endpoint %}

### Request body
Attributes | Type | Description
---------- | ---- | -----------
date | `string` | The date of the expense.
account | `string` | The id of the expense account to categorize the expense.
paid_through_account | `string` | The id of the account used to pay for the expense.
currency | `string` | The currency used in the expense.
amount | `number` | The expense amount.
contact | `string` | (Optional) The id of the contact (vendor).
tax_rate | `string` | (Optional) The id of the tax rate.
amount_tax_type | `string` | (Optional) Either `TAX_INCLUSIVE` or `TAX_EXCLUSIVE`. Required if `tax_rate` is provided.
description | `string` | (Optional) The description attached to it.
reference | `string` | (Optional) A reference attached to the expense.


## Delete expense
{% endpoint %}
DELETE {% $endpoints.expenses.base %}:id/
{% /endpoint %}


---
title: Invoices
section: api-reference
---

{% callout title="Sending invoices in large volumes?" %}
If you plan to create or send more than 500 invoices per month, it's recommended to use the {% relink text="Invoices (Bulk)" href="docs/api-reference/api-invoices" /%} API.
{% /callout %}

## Endpoints

{% endpoint %}
GET {% $endpoints.invoices.base %}
GET {% $endpoints.invoices.base %}:id/
POST {% $endpoints.invoices.base %}
PATCH {% $endpoints.invoices.base %}:id/
DELETE {% $endpoints.invoices.base %}:id/
GET {% $endpoints.invoices.base %}:id/download/
GET {% $endpoints.invoices.base %}:id/line-items/
POST {% $endpoints.invoices.base %}:id/line-items/:line_item_id/
PATCH {% $endpoints.invoices.base %}:id/line-items/:line_item_id/
DELETE {% $endpoints.invoices.base %}:id/line-items/:line_item_id/
{% /endpoint %}


## Invoice object

Attributes | Type | Description
---------- | ---- | -----------
id | `string` | The id of the object.
amount | `number` | The invoice amount.
contact | `string` | The id of the contact.
currency | `string` | The currency used in the invoice.
invoice_number | `string` | The invoice number.
invoice_date | `string` | The date of the invoice.
language | `string` | The language used in the invoice.
line_items | `array` | The line items of the invoice.
reference | `string` | The reference of the invoice.
status | `string` | The status of the invoice.
tax_amount | `number` | The tax amount.
tax_amount_type | `string` | Either `TAX_INCLUSIVE` or `TAX_EXCLUSIVE`.

#### Example
```json
{
    "amount": 115.0,
    "contact": "co_HS9cspuVZJUHdqVsS9CFfY",
    "currency": "AED",
    "id": "inv_YEdmVKecVi45RYWcrt2rJe",
    "invoice_date": "2022-10-05",
    "invoice_number": "INV-000100",
    "language": "en",
    "line_items": [
        {
            "account": "acc_7jpGSFEGGF9cK39vwoDPBt",
            "description": "Line item",
            "id": "invli_Zhf8cUxzjiRRs8Ga7MCgWE",
            "line_amount": 115.0,
            "quantity": 1.0,
            "tax_amount": 15.0,
            "tax_rate": "tax_c8TkJLeXZYJmWuSjqGzGzj",
            "unit_amount": 100.0
        }
    ],
    "reference": "",
    "status": "DRAFT",
    "tax_amount": 15.0,
    "tax_amount_type": "TAX_EXCLUSIVE"
}
```

## Get invoice

### Endpoint
{% endpoint %}
GET {% $endpoints.invoices.base %}:id/
{% /endpoint %}

#### Response sample
```json
{
    "amount": 115.0,
    "contact": "co_HS9cspuVZJUHdqVsS9CFfY",
    "currency": "AED",
    "id": "inv_YEdmVKecVi45RYWcrt2rJe",
    "invoice_date": "2022-10-05",
    "invoice_number": "INV-000100",
    "language": "en",
    "line_items": [
        {
            "account": "acc_7jpGSFEGGF9cK39vwoDPBt",
            "description": "Line item",
            "id": "invli_Zhf8cUxzjiRRs8Ga7MCgWE",
            "line_amount": 115.0,
            "quantity": 1.0,
            "tax_amount": 15.0,
            "tax_rate": "tax_c8TkJLeXZYJmWuSjqGzGzj",
            "unit_amount": 100.0
        }
    ],
    "reference": "",
    "status": "DRAFT",
    "tax_amount": 15.0,
    "tax_amount_type": "TAX_EXCLUSIVE"
}
```


## List invoices

### Endpoint
{% endpoint %}
GET {% $endpoints.invoices.base %}
{% /endpoint %}

### Filters
Query param | Type | Description
----------- | ---- | -----------
contact | `string` | The id of the contact.
invoice_date | `string` | The invoice date in `YYYY-MM-DD` e.g. `2021-01-01`.

{% triablerequest sample="INVOICES" /%}


## Create invoice

### Endpoint
{% endpoint %}
POST {% $endpoints.invoices.base %}
{% /endpoint %}

### Request body
Attributes | Type | Description
---------- | ---- | -----------
amount | `number` | The invoice amount.
contact | `string` | The id of the contact.
currency | `string` | The currency used in the invoice.
invoice_number | `string` | The invoice number.
invoice_date | `string` | The date of the invoice.
language | `string` | The language used in the invoice.
line_items | `array` | The line items of the invoice.
reference | `string` | The reference of the invoice.
tax_amount | `number` | The tax amount.
tax_amount_type | `string` | Either `TAX_INCLUSIVE` or `TAX_EXCLUSIVE`.

{% triablerequest sample="INVOICES_CREATE" /%}

## Update invoice
{% endpoint %}
PATCH {% $endpoints.invoices.base %}:id/
{% /endpoint %}

### Request body
Attributes | Type | Description
---------- | ---- | -----------
id | `string` | The id of the object.
amount | `number` | The invoice amount.
contact | `string` | The id of the contact.
currency | `string` | The currency used in the invoice.
invoice_number | `string` | The invoice number.
invoice_date | `string` | The date of the invoice.
language | `string` | The language used in the invoice.
reference | `string` | The reference of the invoice.
tax_amount_type | `string` | Either `TAX_INCLUSIVE` or `TAX_EXCLUSIVE`.

To update the line items, you need to use the invoices line items endpoints.

## Delete invoice
{% endpoint %}
DELETE {% $endpoints.invoices.base %}:id/
{% /endpoint %}

## Download invoice
{% endpoint %}
GET {% $endpoints.invoices.base %}:id/download/
{% /endpoint %}


## Invoice line item object

Attribute | Type | Description
--------- | ---- | -----------
account | `string` | The id of the account.
description | `string` | The description of the line item.
id | `string` | The id of the object.
line_amount | `number` | The line amount.
quantity | `number` | The quantity.
tax_amount | `number` | The tax amount.
tax_rate | `string` | The id of the tax rate.
unit_amount | `number` | The unit amount.

#### Example
```json
{
    "account": "acc_7jpGSFEGGF9cK39vwoDPBt",
    "description": "Line item",
    "id": "invli_Zhf8cUxzjiRRs8Ga7MCgWE",
    "line_amount": 115.0,
    "quantity": 1.0,
    "tax_amount": 15.0,
    "tax_rate": "tax_c8TkJLeXZYJmWuSjqGzGzj",
    "unit_amount": 100.0
}
```

## Get invoice line item

### Endpoint
{% endpoint %}
POST {% $endpoints.invoices.base %}:id/line-item/
{% /endpoint %}

#### Response sample
```json
{
    "account": "acc_7jpGSFEGGF9cK39vwoDPBt",
    "description": "Line item",
    "id": "invli_Zhf8cUxzjiRRs8Ga7MCgWE",
    "line_amount": 115.0,
    "quantity": 1.0,
    "tax_amount": 15.0,
    "tax_rate": "tax_c8TkJLeXZYJmWuSjqGzGzj",
    "unit_amount": 100.0
}
```

## List invoice line items

### Endpoint
{% endpoint %}
GET {% $endpoints.invoices.base %}:id/line-items/
{% /endpoint %}

### Filters
Query param | Type | Description
----------- | ---- | -----------
account | `string` | The id of the account.

## Create invoice line item

### Endpoint
{% endpoint %}
POST {% $endpoints.invoices.base %}:id/line-items/
{% /endpoint %}

### Request body
Attributes | Type | Description
---------- | ---- | -----------
account | `string` | The id of the account.
description | `string` | The description of the line item.
quantity | `number` | The quantity.
tax_rate | `string` | The id of the tax rate.
unit_amount | `number` | The unit amount.

## Update invoice line item
{% endpoint %}
PATCH {% $endpoints.invoices.base %}:id/line-items/:line_item_id/
{% /endpoint %}

### Request body
Attributes | Type | Description
---------- | ---- | -----------
account | `string` | The id of the account.
description | `string` | The description of the line item.
quantity | `number` | The quantity.
tax_rate | `string` | The id of the tax rate.
unit_amount | `number` | The unit amount.

## Delete invoice line item
{% endpoint %}
DELETE {% $endpoints.invoices.base %}:id/line-items/:line_item_id/
{% /endpoint %}


---
title: Organization
section: api-reference
---

## Endpoints

{% endpoint %}
GET {% $endpoints.organization.base %}
{% /endpoint %}


## The Organization object
Attributes | Type | Description
--------- | ---- | ----------- 
id | `string` | id of the object.
name | `object` | Object containing the name of the organization in English and Arabic.
users | `array` | List of organization users.

#### Example
```json
{
  "id": "org_By5sp4qfjM6LdnDDyvYL8B",
  "name": {
    "en": "Abdullah's Trading Est.",
    "ar": "مؤسسة عبدالله للتجارة"
  },
  "users": [
    {
      "id": "usr_FBmxyogdgTDufYvGiTjXs2",
      "email": "some@example.com"
    }
  ]
}
```

## Retrieve organization
Retrieves the organization associated with the API key.

{% triablerequest sample="ORGANIZATION" /%}


---
title: Simplified Invoices
section: api-reference
---

## Endpoints

{% endpoint %}
GET {% $endpoints.simplified_invoices.base %}
GET {% $endpoints.simplified_invoices.base %}:id/
POST {% $endpoints.simplified_invoices.base %}
PATCH {% $endpoints.simplified_invoices.base %}:id/
DELETE {% $endpoints.simplified_invoices.base %}:id/
GET {% $endpoints.simplified_invoices.base %}:id/download/
GET {% $endpoints.simplified_invoices.base %}:id/line-items/
POST {% $endpoints.simplified_invoices.base %}:id/line-items/:line_item_id/
PATCH {% $endpoints.simplified_invoices.base %}:id/line-items/:line_item_id/
DELETE {% $endpoints.simplified_invoices.base %}:id/line-items/:line_item_id/
{% /endpoint %}


## Invoice object

Attributes | Type | Description
---------- | ---- | -----------
id | `string` | The id of the object.
amount | `number` | The invoice amount.
contact | `string` | The id of the contact.
currency | `string` | The currency used in the invoice.
invoice_number | `string` | The invoice number.
invoice_date | `string` | The date of the invoice.
language | `string` | The language used in the invoice.
line_items | `array` | The line items of the invoice.
reference | `string` | The reference of the invoice.
status | `string` | The status of the invoice.
tax_amount | `number` | The tax amount.
tax_amount_type | `string` | Either `TAX_INCLUSIVE` or `TAX_EXCLUSIVE`.

#### Example
```json
{
    "amount": 115.0,
    "contact": "co_HS9cspuVZJUHdqVsS9CFfY",
    "currency": "AED",
    "id": "sinv_YEdmVKecVi45RYWcrt2rJe",
    "invoice_date": "2022-10-05",
    "invoice_number": "SINV-000100",
    "language": "en",
    "line_items": [
        {
            "account": "acc_7jpGSFEGGF9cK39vwoDPBt",
            "description": "Line item",
            "id": "sinvli_Zhf8cUxzjiRRs8Ga7MCgWE",
            "line_amount": 115.0,
            "quantity": 1.0,
            "tax_amount": 15.0,
            "tax_rate": "tax_c8TkJLeXZYJmWuSjqGzGzj",
            "unit_amount": 100.0
        }
    ],
    "reference": "",
    "status": "DRAFT",
    "tax_amount": 15.0,
    "tax_amount_type": "TAX_EXCLUSIVE"
}
```

## Get invoice

### Endpoint
{% endpoint %}
GET {% $endpoints.simplified_invoices.base %}:id/
{% /endpoint %}

#### Response sample
```json
{
    "amount": 115.0,
    "contact": "co_HS9cspuVZJUHdqVsS9CFfY",
    "currency": "AED",
    "id": "sinv_YEdmVKecVi45RYWcrt2rJe",
    "invoice_date": "2022-10-05",
    "invoice_number": "SINV-000100",
    "language": "en",
    "line_items": [
        {
            "account": "acc_7jpGSFEGGF9cK39vwoDPBt",
            "description": "Line item",
            "id": "sinvli_Zhf8cUxzjiRRs8Ga7MCgWE",
            "line_amount": 115.0,
            "quantity": 1.0,
            "tax_amount": 15.0,
            "tax_rate": "tax_c8TkJLeXZYJmWuSjqGzGzj",
            "unit_amount": 100.0
        }
    ],
    "reference": "",
    "status": "DRAFT",
    "tax_amount": 15.0,
    "tax_amount_type": "TAX_EXCLUSIVE"
}
```


## List simplified invoices

### Endpoint
{% endpoint %}
GET {% $endpoints.simplified_invoices.base %}
{% /endpoint %}

### Filters
Query param | Type | Description
----------- | ---- | -----------
contact | `string` | The id of the contact.
invoice_date | `string` | The invoice date in `YYYY-MM-DD` e.g. `2021-01-01`.

{% triablerequest sample="SIMPLIFIED_INVOICES" /%}


## Create invoice

### Endpoint
{% endpoint %}
POST {% $endpoints.simplified_invoices.base %}
{% /endpoint %}

### Request body
Attributes | Type | Description
---------- | ---- | -----------
amount | `number` | The invoice amount.
contact | `string` | The id of the contact.
currency | `string` | The currency used in the invoice.
invoice_number | `string` | The invoice number.
invoice_date | `string` | The date of the invoice.
language | `string` | The language used in the invoice.
line_items | `array` | The line items of the invoice.
reference | `string` | The reference of the invoice.
tax_amount | `number` | The tax amount.
tax_amount_type | `string` | Either `TAX_INCLUSIVE` or `TAX_EXCLUSIVE`.

{% triablerequest sample="SIMPLIFIED_INVOICES_CREATE" /%}

## Update invoice
{% endpoint %}
PATCH {% $endpoints.simplified_invoices.base %}:id/
{% /endpoint %}

### Request body
Attributes | Type | Description
---------- | ---- | -----------
id | `string` | The id of the object.
amount | `number` | The invoice amount.
contact | `string` | The id of the contact.
currency | `string` | The currency used in the invoice.
invoice_number | `string` | The invoice number.
invoice_date | `string` | The date of the invoice.
language | `string` | The language used in the invoice.
reference | `string` | The reference of the invoice.
tax_amount_type | `string` | Either `TAX_INCLUSIVE` or `TAX_EXCLUSIVE`.

To update the line items, you need to use the simplified invoices line items endpoints.

## Delete invoice
{% endpoint %}
DELETE {% $endpoints.simplified_invoices.base %}:id/
{% /endpoint %}

## Download invoice
{% endpoint %}
GET {% $endpoints.simplified_invoices.base %}:id/download/
{% /endpoint %}


## Invoice line item object

Attribute | Type | Description
--------- | ---- | -----------
account | `string` | The id of the account.
description | `string` | The description of the line item.
id | `string` | The id of the object.
line_amount | `number` | The line amount.
quantity | `number` | The quantity.
tax_amount | `number` | The tax amount.
tax_rate | `string` | The id of the tax rate.
unit_amount | `number` | The unit amount.

#### Example
```json
{
    "account": "acc_7jpGSFEGGF9cK39vwoDPBt",
    "description": "Line item",
    "id": "sinvli_Zhf8cUxzjiRRs8Ga7MCgWE",
    "line_amount": 115.0,
    "quantity": 1.0,
    "tax_amount": 15.0,
    "tax_rate": "tax_c8TkJLeXZYJmWuSjqGzGzj",
    "unit_amount": 100.0
}
```

## Get invoice line item

### Endpoint
{% endpoint %}
POST {% $endpoints.simplified_invoices.base %}:id/line-item/
{% /endpoint %}

#### Response sample
```json
{
    "account": "acc_7jpGSFEGGF9cK39vwoDPBt",
    "description": "Line item",
    "id": "sinvli_Zhf8cUxzjiRRs8Ga7MCgWE",
    "line_amount": 115.0,
    "quantity": 1.0,
    "tax_amount": 15.0,
    "tax_rate": "tax_c8TkJLeXZYJmWuSjqGzGzj",
    "unit_amount": 100.0
}
```

## List invoice line items

### Endpoint
{% endpoint %}
GET {% $endpoints.simplified_invoices.base %}:id/line-items/
{% /endpoint %}

### Filters
Query param | Type | Description
----------- | ---- | -----------
account | `string` | The id of the account.

## Create invoice line item

### Endpoint
{% endpoint %}
POST {% $endpoints.simplified_invoices.base %}:id/line-items/
{% /endpoint %}

### Request body
Attributes | Type | Description
---------- | ---- | -----------
account | `string` | The id of the account.
description | `string` | The description of the line item.
quantity | `number` | The quantity.
tax_rate | `string` | The id of the tax rate.
unit_amount | `number` | The unit amount.

## Update invoice line item
{% endpoint %}
PATCH {% $endpoints.simplified_invoices.base %}:id/line-items/:line_item_id/
{% /endpoint %}

### Request body
Attributes | Type | Description
---------- | ---- | -----------
account | `string` | The id of the account.
description | `string` | The description of the line item.
quantity | `number` | The quantity.
tax_rate | `string` | The id of the tax rate.
unit_amount | `number` | The unit amount.

## Delete invoice line item
{% endpoint %}
DELETE {% $endpoints.simplified_invoices.base %}:id/line-items/:line_item_id/
{% /endpoint %}


---
title: Tax rates
section: api-reference
---

## Endpoints

{% endpoint %}
GET {% $endpoints.taxRates.base %}
{% /endpoint %}


## The tax rate object
Attributes | Type | Required | Description
--------- | ---- | -------- | ----------- 
id | `string` | `True` | id of the object.
name | `string` | `False` | Name.
friendly_name | `string` | `False` | Friendly name.
description | `string` | `False` | Description.
rate | `string` | `False` | rate in decimals.
tax_type | `string` | `False` | One of `SALES`, `PURCHASES`, `REVERSE_CHARGE`.

#### Example
```json
{
    "id": "tax_x908asdlmn298123lnm",
    "name": "Standard-Rated VAT",
    "description": "KSA Standard-Rated VAT",
    "rate": "0.15",
    "tax_type": "SALES"
}
```


## List tax rates

List the tax rates of your organization.

{% triablerequest sample="TAX_RATES" /%}


---
title: Authentication
section: introduction
---

Wafeq supports authentication via two methods,

* Private Key (recommended for accessing your own organization by your application)
* OAuth Flow (recommended for building third party integrations with Wafeq)


---

## Authenticating API calls via API Key (Private Key)

To use private key authentication you will need to {% relink text="create an API key" href="/docs/introduction/setup" /%} from your [Wafeq Developer console](https://app.wafeq.com/c/api-keys).

When making an API call to a Wafeq endpoint, you must use an `Authorization` header with `Api-Key` prefix followed by your API key.

Example,
```
curl --location\
--request GET 'https://api.wafeq.com/v1/organization/' \
--header 'Authorization: Api-Key <api_key>' \
...
```

## Authenticating API calls via Access Token (OAuth Flow)

To use oauth flow authentication you will need to create an App from your Wafeq Developer console.

When making an API call to a Wafeq endpoint, you must use an `Authorization` header with `Bearer` prefix followed by the access token obtained by the oauth flow.

Example,
```
curl --location\
--request GET 'https://api.wafeq.com/v1/organization/' \
--header 'Authorization: Bearer <access_token>' \
...
```

or you can visit [oauth2-client-examples](https://gitlab.com/wafeq-com/oauth2-client-examples) repository for demo apps implementing oauth flow with Wafeq.


---
title: Authorization
section: introduction
---

Wafeq implements the OAuth 2.0 authorization framework.

---

## Endpoints

{% endpoint %}
GET {% $endpoints.oauthAuthorize.base %}
POST {% $endpoints.oauthTokenGenerate.base %}
POST {% $endpoints.oauthTokenRevoke.base %}
{% /endpoint %}


## Authorization Code Flow

### Prerequisites

This guide assumes that you already have created an app.

### Examples

You can find example apps implementing the authorization code flow in the [oauth2-client-examples](https://gitlab.com/wafeq-com/oauth2-client-examples) repository.


### List of scopes

Scope | Description
------|------------
basic | Basic access to organization info
users | Access to organization list of users
bulk_invoices | Bulk sending invoices api
chart_of_accounts.read | Read-only access to chart of accounts data
chart_of_accounts.write | Read and Write access to chart of accounts data
bank_accounts.read | Read-only access to bank_accounts data
bank_accounts.write | Read and Write access to bank accounts data
contacts.read | Read-only access to contacts data
contacts.write | Read and Write access to contacts data
tax_rates.read | Read-only access to tax_rates data
tax_rates.write | Read and Write access to tax_rates data
invoices.read | Read-only access to invoices data
invoices.write | Read and Write access to invoices data
expenses.read | Read-only access to expenses data
expenses.write | Read and Write access to expenses data
bills.read | Read-only access to bills data
bills.write | Read and Write access to bills data
reports | Read-only access to reports
payroll.read | Read-only access to payroll data
payroll.write | Read and Write access to payroll data

### Request User Authorization

The first step is to request authorization from the user, so your app can access the Wafeq resources in behalf that user.
To do so, your application must build and send a GET request to the `/oauth/authorize/` endpoint with the following parameters:

Query Param | Value
--- | ---
client_id | _Required_: The Client ID generated after registering your application.
response_type | _Required_: Set to `code`.
redirect_uri | _Required_: The URI to redirect to after the user grants or denies permission. This URI needs to have been entered in the Redirect URI allowlist that you specified when you registered your application. The value of redirect_uri here must exactly match one of the values you entered when you registered your application, including upper or lowercase, terminating slashes, and such.
scope | _Required_: A space-separated list of [scopes](#list-of-scopes).
state | _Optional, but strong recommended_: This provides protection against attacks such as cross-site request forgery. See RFC-6749.

If you're implementing the PKCE extension, you must include these additional parameters.

Query Param | Value
--- | ---
code_challenge_method | _Required_: Set to `S256`
code_challenge | _Required_: Set to the code challenge that your app calculated.

In order to generate the code_challenge, your app should hash the code verifier using the SHA256 algorithm. 
The code verifier is a random string between 43 and 128 characters in length. It can contain letters, digits, 
underscores, periods, hyphens, or tildes.

#### Response

**User accepts**

Query Params | Value
--- | ---
code | An authorization code that can be exchanged for an Access Token.
state | The value of the `state` parameter supplied in the request.

Example,
```
https://your-domain.com/callback?code=NApCCg..BkWtQ&state=34fFs29kd09
```

**User denies**

Query Params | Value
--- | ---
error | The reason authorization failed, for example: `access_denied`.
state | The value of the state parameter supplied in the request.

Example,
```
https://your-domain.com/callback?error=access_denied&state=34fFs29kd09
```

### Request Access Token

If the user accepted your request, then your app is ready to exchange the authorization code for an Access Token.
It can do this by making a `POST` request to the `/token/` endpoint.

The body of this POST request must contain the following parameters encoded in `application/x-www-form-urlencoded`:

Request Body Parameter | Value
--- | ---
grant_type | _Required_: This field must contain the value `authorization_code`.
code | _Required_: The authorization code returned from the previous request.

If you're implementing the PKCE extension, you must include these additional parameters.

Request Body Parameter | Value
--- | ---
client_id | _Required_: The Client ID generated after registering your application.
code_verifier | _Required_: The value of this parameter must match the value of the code_verifier that your app generated in the previous step.

The request must also include the following HTTP headers:

Header Parameters | Value
--- | ---
Authorization | _Required_: Base 64 encoded string that contains the Client ID and Client Secret Key. The field must have the format: `Authorization: Basic <base64 encoded client_id:client_secret>`
Content-Type | _Required_: Always set to `application/x-www-form-urlencoded`.

#### Response

Key | Value Type | Value Description
--- |--- | ---
access_token | string | An Access Token that can be provided in subsequent calls
refresh_token | string | An Refresh token which is used to fetch a new `access_token` to be then used in making authenticated API calls.
token_type | string | How the Access Token may be used: always `Bearer`.
expires_in | int | The time period (in seconds) for which the Access Token is valid.

Example:
```
curl --location \
    --request POST https://app.wafeq.com/oauth/token/ \
    --header 'Authorization: Basic NTMwO...3MWJi' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'redirect_uri=https://your-domain.com/callback' \
    --data-urlencode 'grant_type=authorization_code' \
    --data-urlencode 'code=83YqX...mlezV'
```
The response will be similar to this:
```
{
   "access_token": "NgA6ZcYI...ixn8bUQ",
   "refresh_token": "NgAagA...Um_SHo",
   "token_type": "Bearer",
   "expires_in": 3600
}
```

### Request a refreshed Access Token

Access tokens are deliberately set to expire after a short time, after which new tokens may be granted by supplying the refresh token originally obtained during the authorization code exchange.
In order to refresh the token, a POST request must be sent with the following body parameters encoded in `application/x-www-form-urlencoded`:

Request Body Parameter | Value
--- | ---
grant_type | _Required_: Set it to `refresh_token`.
refresh_token | _Required_: The refresh token returned from the authorization code exchange.

If you're implementing the PKCE extension, you must include these additional parameters.

Request Body Parameter | Value
--- | ---
client_id | _Required_: The Client ID generated after registering your application.

The request must also include the following HTTP headers:

Header Parameters | Value
--- | ---
Authorization | _Required_: Base 64 encoded string that contains the Client ID and Client Secret Key. The field must have the format: `Authorization: Basic <base64 encoded client_id:client_secret>`
Content-Type | _Required_: Always set to `application/x-www-form-urlencoded`.


Example:
```
curl --location \
    --request POST https://app.wafeq.com/oauth/token/ \
    --header 'Authorization: Basic NTMwO...3MWJi' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=refresh_token' \
    --data-urlencode 'refresh_token=0uOmz...GNu77'
```
The response will be similar to this:
```
{
   "access_token": "NgA6ZcYI...ixn8bUQ",
   "token_type": "Bearer",
   "expires_in": 3600
}
```


---
title: Calculations and rounding
section: introduction
---

While calculating tax total and the subtotal on an invoice, each individual line amount is rounded to 2 decimal places then summed to get the tax total.
The method used to round is to round half up.

| Name | Amount | Tax Rate | Tax (before rounding) | Tax (after rounding) | Totals |
|:---|---:|---:|---:|---:|---:|
| Line item 1 | 45.30 | 5% | 2.265 | 2.27 |  |
| Line item 2 | 33.45 | 10% | 3.345 | 3.35 |  |
| Total Tax Amounts |  |  |  | 5.62 |  |
| **Total** | 78.75 |  |  |  | 84.37 |


---
title: Effect on your books
section: introduction
---

{% partial file="effect-on-your-books.md" /%}


---
title: Expanding responses
section: introduction
---



---

## Expanding API response objects

Related objects that are referenced by their id can be expanded in the response using the `expand` query parameter. This 
parameter is a comma-separated list of objects to expand, and supports nesting using the `.` notation.

As an example, an unexpanded bank ledger:
```json
{
    "id": "bt_KabEvYZwpUQCevDJycmVWu",
    "bank_account": "ba_9t79bCG2Q6SxPxQBqva8z9",
    "account": "acc_x908asdlmn298123lnm",
    "date": "2019-12-29",
    "amount": 1000.0,
    "description": "Set bank account initial balance",
    "reference": "",
    "is_manual": true
}
```

Once you pass `?expand=account,bank_account,bank_account.account` as query parameter, the response
would look like this:
```json
{
    "id": "bt_KabEvYZwpUQCevDJycmVWu",
    "bank_account": {
        "id": "ba_9t79bCG2Q6SxPxQBqva8z9",
        "name": "My bank account",
        "currency": "SAR",
        "classification": "ASSET",
        "sub_classification": "PETTY_CASH",
        "account": {
            "id": "acc_2nqzog3ZRXegUgvLWEVJ84",
            "account_code": "200",
            "name_en": "My bank account",
            "name_ar": "My bank account",
            "is_system": false,
            "classification": "ASSET",
            "sub_classification": "CASH_EQUIVALENTS",
            "is_payment_enabled": true
        }
    },
    "account": {
        "id": "acc_x908asdlmn298123lnm",
        "account_code": "200",
        "name_en": "Sales",
        "name_ar": "مبيعات",
        "is_system": false,
        "classification": "REVENUE",
        "sub_classification": "INCOME",
        "is_payment_enabled": true
    },
    "date": "2019-12-29",
    "amount": 1000.0,
    "description": "Set bank account initial balance",
    "reference": "",
    "is_manual": true
}


---
title: Filter
section: introduction
---

`list` endpoints may allow filters.
Apply one or more filters using query parameters.

#### Example
The below request will exclude system accounts and include accounts where payments are enabled.
```shell
curl --location \
--request GET 'https://api.wafeq.com/v1/accounts/?is_system=false&is_payment_enabled=true' \
--header 'Authorization: Api-Key <api_key>'
```


---
title: Pagination
section: introduction
---



---

## Paginating API calls

All `list` endpoints responses will include the following keys:
```
{
    "count": 123,
    "next": "<next_url>",
    "previous": "<previous_url>",
    "results": [...]
}
```
The `results` array contains the first 50 results.
To retrieve the next page of results, simply call the `next` url:
```
curl --location\
--request GET '<next_url>'
--header 'Authorization: Api-Key <api_key>'
``` 









---
title: Send your first e-invoice
section: introduction
---

Make sure you've [created an API key](/docs/introduction/setup) from your [Wafeq Developer console](https://app.wafeq.com/c/api-keys).

---

## Sending an invoice by email

To send an invoice, paste the below code in your terminal. Make sure to replace `<api_key>` with your API key.

{% partial file="send-your-first-e-invoice.md" /%}



---
title: Get your API Key
section: introduction
---

If you haven't done so already, create a free account on [wafeq.com](https://app.wafeq.com/accounts/signup/).

---

## Create a new API key

1. Log into your Wafeq account on [wafeq.com](https://app.wafeq.com/accounts/signup/)
2. Head over to the **API Keys** page in the **Developer** section on the left-side menu
3. Click **Create new key** and save your key.
4. Click the **Enable API** button to enable the API. If you cannot enable the API, make sure you're on the **Starter plan** at least.

You can now use your API Key to make API calls.
{% callout title="You can use the API during free trials" %}
You need to be on the _Starter_ plan to be able to use the API. The API can be enabled and fully used during free trials.
{% /callout %}


---
title: Versioning
section: introduction
---

Wafeq uses a path prefix `https://api.wafeq.com/<version>` to determine which version of our API you are requesting.
The request will return an error if no version is specified.

The current API version is `v1`.

#### Example
The below request will use the `v1` version of the API.
```shell
curl --location \
--request POST 'https://api.wafeq.com/v1/api-invoices/bulk_send/' \
--header 'Authorization: Api-Key <api_key>' \
...
```


---
title: FAQ
description: Answers to some frequently asked questions.
section: support
---

Answers to some frequently asked questions.

---

#### Is Wafeq approved by ZATCA?

Yes, Wafeq is an approved e-invoicing (Fatoorah) solution provider by ZATCA.

#### Are e-invoices sent to ZATCA?

No. 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.

#### My country doesn't require e-invoicing. Can I send regular invoices through the API?

Yes. If your organization country implements e-invoicing (e.g. in Saudi Arabia), the invoice format will comply with e-invoicing requirements. Otherwise, the invoice will comply with regular VAT requirements in your country.

#### Why doesn't my Profit & Loss report show sales from invoices I've sent?

{% partial file="effect-on-your-books.md" /%}

#### Can I get an extension to my free trial?

If you need more time to test our API, contact us for an extension.


---
title: Getting support
description: Getting support on Wafeq.
section: support
---

If you need help, you can write to us on [help@wafeq.com](mailto:help@wafeq.com).


---
title: Use case for B2B
description: Use Wafeq's e-invoicing API to send your customers compliant B2B e-invoices.
section: use-cases
---

Use Wafeq's e-invoicing API to send your customers compliant B2B e-invoices.{% .lead %}

---

## Calling the API whenever you want to issue an invoice to your customer

In your app's code, simply call the e-invoicing API to send your customer an invoice.

You may want to include the `tax_registration_number` if your customer has one.  
See the [`Contact`](/docs/api-reference/api-invoices#contact) object for supported fields.


---
title: Use case for B2C
description: Use Wafeq's e-invoicing API to send your customers compliant B2C e-invoices.
section: use-cases
---

Use Wafeq's e-invoicing API to send your customers compliant B2C e-invoices.{% .lead %}

---

## Calling the API whenever you want to issue an invoice to your customer

In your app's code, simply call the e-invoicing API to send your customer an invoice.


---
title: Use case for e-commerce
description: If you're running an e-commerce store, you can use Wafeq's e-invoicing API to send your customers compliant e-invoices.
section: use-cases
---

If you're running an e-commerce store, you can use Wafeq's e-invoicing API to send your customers compliant e-invoices.

---

## Calling the API when an order is dispatched

In your e-commerce store code, call the e-invoicing API to send your customer an invoice.
You can do this whether you're using a ready-made platform such as:

- Salla
- Shopify
- Zid
- Woo Commerce
- Wordpress
- Other

or in your own custom platform.


---
title: Use case for expense management
description: Use Wafeq's API to push expenses from an expense management software into Wafeq.
section: use-cases
---

Use Wafeq's API to push expenses from an expense management software into Wafeq.{% .lead %}

---

## Use case overview
We'll implement an integration for a fictitious expense management app called __Expensico__.

__Expensico__ is a software that issues corporate cards to employees. It also allows employees to file expense claims they paid out of pocket to be reimbursed.

__Expensico__ developers want to build an integration with Wafeq to automate booking expenses for accounting purposes.
They want the integration to do the following:
- When an expense report is approved by a manager, automatically create the expenses in Wafeq.
- If an expense is to be reimbursed, book it under an `Expensico – Employee Claims` account.
- If an expense is paid through an employee card, book it against an `Expensico – Employees Balance` asset account. This is the account that keeps track of the total money available in employee cards.
- Any money movement in and out the bank account (such as top ups or reimbursements) that funds employee cards will be recorded in an `Expensico Bank Account` bank account in Wafeq.

## Suggested implementation
### Configuration
This step is performed by the user initially when setting up the integration. 
You will need to do the following:
1. Ask the user to connect their Wafeq account using the flow described in the {% relink text="Authorization section" href="/docs/introduction/authorization" /%}. Store the access token in your database to make API calls on behalf of your user.
2. {% relink text="Get the list of accounts" href="/docs/api-reference/accounts" /%} filtered on the `EXPENSE` classification for the organization
3. Ask the user to map these accounts to their expense categories in your software
4. Ask the user to choose the `CURRENT_LIABILITY` account in Wafeq to use to record employee claims, or offer to create one for him. Call it something easy to recognize as belonging to Expensico, such as `Expensico – Employee Claims` and make sure `is_payment_enabled` field set to `true`.
5. Ask the user to choose the `CURRENT_ASSET` account in Wafeq to use to record expenses paid through employee cards, or offer to create one for him. Call it something easy to recognize as belonging to Expensico, such as `Expensico – Employees Balance` and make sure `is_payment_enabled` field set to `true`.
6. Ask the user to choose the Bank Account that represents the bank account that funds employee cards, or offer to create one for him. Call it something easy to recognize such as `Expensico Bank Account`.

Save the above configuration in your database. You're now ready to sync.

### Syncing expenses
Once the configuration is done, you'll want to decide when you want create an expense in Wafeq. 
For example, when an expense report is approved:
- Use the {% relink text="Expenses endpoint" href="/docs/api-reference/expenses" /%} to create each expense in the expense report
    - Use the `reference` field as a unique identifier for expenses you create. You will use this field to look up an expense before you create it to avoid duplication
    - Set the `paid_through_account` based on whether the expense is a claim or paid using the `Expensico – Employees Balance` account.


### Syncing statement bank transactions
You'll want to create statement bank transactions to make it easy for the user to reconcile the statement, instead of asking them to import the statement manually.  

To do that, create a {% relink text="statement bank transaction" href="/docs/api-reference/bank-statements" /%} for each statement transaction for the bank account `Expensico Bank Account`.

### Syncing ledger bank transactions
For each transaction type below, create a ledger bank transaction in `Expensico Bank Account` with the `account` field set as follows:

Transaction type | Description | Account
---------------- | ------------ | ----------- 
**Reimbursements** | When an employee is reimbursed | `Expensico – Employee Claims` 
**Card funding** | When a card is funded | `Expensico – Employees Balance`


### Manual sync
After the configuration is completed, you'll want to allow the user to perform a sync of historical expenses into Wafeq. One possible implementation is as follows:
- Allow the user to select a date range to sync approved expense reports
- For each expense in each expense report, check if it already exists in Wafeq by looking it up by `reference`. If it does not exist, create it.
- Perform a full `Expensico Bank Account` statement sync
- Create ledger bank transactions for `Expensico Bank Account`


Attribute	Type	Description
id	`string`	id of the statement bank transaction
bank_account	`string`	(Readonly) id of the bank account
date	`string`	The date of the statement
amount	`number`	The statement amount
statement_balance	`number`	The balance as reported by the bank
calculated_balance	`number`	(Readonly) The balace computed from all statements
description	`string`	A description attached to the statement
reference	`string`	A reference attached to the statement
is_posted	`boolean`	(Readonly) Whether the bank statement is reconciled

Query param	Possible values	Description
date_after	`string`	Statements that are booked on or after the date.
date_before	`string`	Statements that are booked before the date.
amount_min	`number`	Statements with this minimum amount.
amount_max	`number`	Statements with this maximum amount.