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:

Ask the user to connect their Wafeq account using the flow described in the Authorization section. Store the access token in your database to make API calls on behalf of your user.
Get the list of accounts filtered on the EXPENSE classification for the organization
Ask the user to map these accounts to their expense categories in your software
Ask the user to choose a CURRENT_LIABILITY account in Wafeq that will be used 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.
Ask the user to choose a CURRENT_ASSET account in Wafeq that will be used 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.
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 Expenses endpoint 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 Bank Transaction 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