Setting Up SimplifyVFD as Your VFD Provider in ERPNext

Tanzania VFD Compliance · ERPNext / VFD Providers App A step-by-step guide to configuring SimplifyVFD for fiscal receipt submission in ERPNext using the VFD Providers app.

---

Introduction

In Tanzania, businesses are required to use a Virtual Fiscal Device (VFD) to submit fiscal receipts to the Tanzania Revenue Authority (TRA). ERPNext supports multiple VFD providers through the VFD Providers app — an open-source app maintained by Aakvatech Limited that provides a pluggable VFD Provider DocType for managing provider configurations.

SimplifyVFD is a Tanzanian VFD middleware platform offering a partner API for fiscal receipt submission. Unlike some providers, SimplifyVFD uses JWT-based authentication — you log in to obtain a bearer token, then use that token on subsequent API calls. The token refresh flow is also handled automatically by the VFD Providers app.

Prerequisites - The VFD Providers app installed on your ERPNext instance - A SimplifyVFD partner account with valid credentials - System Manager access to your ERPNext site

---

About the VFD Providers App

The VFD Providers app is an open-source Frappe/ERPNext application developed and maintained by Aakvatech Limited. It provides the VFD Provider DocType which stores the base URL and API endpoint paths for each VFD middleware provider, allowing ERPNext to dynamically construct API requests without any code changes when switching providers.

→ https://github.com/Aakvatech-Limited/vfd_providers

Installation

cd /home/frappe/frappe-bench
bench get-app https://github.com/Aakvatech-Limited/vfd_providers
bench --site your-site.example.com install-app vfd_providers
bench migrate

---

SimplifyVFD API Endpoints

SimplifyVFD uses a partner API hosted at https://simplify.co.tz/partner/v1. It exposes three endpoints used by the VFD Providers app:

Key	Endpoint Path	Purpose
login	/auth/user/login	Authenticate and obtain a bearer token
refresh	/auth/user/token/refresh	Refresh an expired bearer token
createIssuedInvoice	/invoice/createIssuedInvoice	Submit a fiscal invoice to TRA

Authentication Flow

SimplifyVFD requires authentication before submitting invoices. The flow works as follows:

1. ERPNext calls /auth/user/login with your username and password
2. SimplifyVFD returns a bearer token and a refresh token with an expiry timestamp
3. All subsequent API calls include the bearer token in the Authorization header
4. When the token expires, ERPNext calls /auth/user/token/refresh automatically to obtain a new one

The bearer token and refresh token are stored securely in the Simplify VFD Settings document on your ERPNext site.

---

Step-by-Step Setup

Step 1 — Create the VFD Provider Record

In ERPNext, navigate to VFD Provider (search for it in the search bar). Create a new document with the following values:

Field	Value
VFD Provider (name)	SimplifyVFD
Base URL	https://simplify.co.tz/partner/v1
VFD Provider Settings	Simplify VFD Settings

Step 2 — Add the API Endpoint Attributes

In the Attributes child table, add each of the three endpoint rows below:

Key	Value
login	/auth/user/login
refresh	/auth/user/token/refresh
createIssuedInvoice	/invoice/createIssuedInvoice

Step 3 — Configure Simplify VFD Settings

Navigate to Simplify VFD Settings and enter your SimplifyVFD partner credentials:

Field	Description
Company	Your ERPNext company name
Username	Your SimplifyVFD account email (e.g. it@yourcompany.com)
Password	Your SimplifyVFD account password
Enable VFD Preview	Tick to preview receipts before submission (optional)

⚠️ Security Note Your password is stored encrypted in the ERPNext database. Never share your Simplify VFD Settings document export publicly — it contains sensitive credentials. The bearer_token and refresh_token fields are populated automatically at runtime and should also be treated as secrets.

Step 4 — Log In and Obtain a Token

Save the Simplify VFD Settings document, then click the Login button (or equivalent action in the app). ERPNext will call /auth/user/login with your credentials and store the returned bearer token and refresh token. You should see the Token Expires field update with a future timestamp confirming a successful login.

Step 5 — Set SimplifyVFD as the Active Provider

Go to VFD Settings and set the VFD Provider field to SimplifyVFD. Save the document.

Step 6 — Test with a Sales Invoice

Create or open a test Sales Invoice, enable VFD on it, and submit. The app will call /invoice/createIssuedInvoice with the fiscal payload and store the TRA receipt number and verification details on the invoice upon success.

---

Provider JSON Reference

If you are setting this up via a fixture file or data migration, here is the complete VFD Provider JSON record for SimplifyVFD:

{
  "doctype": "VFD Provider",
  "vfd_provider": "SimplifyVFD",
  "base_url": "https://simplify.co.tz/partner/v1",
  "vfd_provider_settings": "Simplify VFD Settings",
  "attributes": [
    {
      "key": "login",
      "value": "/auth/user/login"
    },
    {
      "key": "refresh",
      "value": "/auth/user/token/refresh"
    },
    {
      "key": "createIssuedInvoice",
      "value": "/invoice/createIssuedInvoice"
    }
  ]
}

Using as a Fixture Save this JSON as vfd_provider/SimplifyVFD.json inside your custom app's fixtures folder, then run bench migrate to automatically import it on new site deployments. Note that credentials in Simplify VFD Settings must still be configured manually per site.

---

API Endpoints Explained

POST /auth/user/login

Authenticates using your SimplifyVFD username and password. Returns a short-lived bearer token, a refresh token, and an expiry timestamp. Called automatically when tokens are absent or on manual login from settings.

POST /auth/user/token/refresh

Exchanges a valid refresh token for a new bearer token without requiring the user's password again. The VFD Providers app handles this automatically before token expiry so fiscal receipt submissions are not interrupted.

POST /invoice/createIssuedInvoice

Submits a fiscal invoice payload to TRA via the SimplifyVFD partner API. Requires a valid bearer token in the Authorization header. Called automatically on Sales Invoice submission when VFD is enabled and SimplifyVFD is the active provider.

---

Key Differences from Other Providers

SimplifyVFD differs from providers like VFDPlus in one important way — it requires authentication before use:

Feature	VFDPlus	SimplifyVFD
Authentication	API key / token (static)	JWT login + refresh flow
Endpoints	4 (receipt CRUD + account info)	3 (auth + invoice submission)
Token management	Not required	Automatic via refresh endpoint
Base URL	https://app.vfdplus.co.tz	https://simplify.co.tz/partner/v1

---

Troubleshooting

Login fails with invalid credentials

Double-check the username and password in Simplify VFD Settings. Ensure you are using your SimplifyVFD partner portal credentials, not your TRA or ERPNext login. Contact SimplifyVFD support if your account is locked.

Token expired errors during invoice submission

The app should refresh the token automatically. If this is not happening, try clicking Login again manually in Simplify VFD Settings to force a fresh token. Check that the Token Expires field shows a future timestamp after doing so.

Invoice submission rejected by TRA

Verify that your TIN, VRN, and serial number are correctly registered with SimplifyVFD. These are embedded in the JWT token returned at login — you can decode your bearer token at jwt.io to confirm the values match your TRA registration.

Connection errors / timeout

Confirm your ERPNext server has outbound internet access to simplify.co.tz on port 443:

curl -I https://simplify.co.tz/partner/v1/auth/user/login

⚠️ Test in Sandbox First Confirm with SimplifyVFD whether a sandbox/test environment is available. Always validate your integration in a non-production environment before submitting live receipts to TRA.

---

Contributing

The VFD Providers app is open source and contributions are welcome. If you add support for a new VFD provider or improve existing functionality, please submit a pull request:

→ https://github.com/Aakvatech-Limited/vfd_providers

---

About

This guide was produced by Aakvatech Limited, an ERPNext implementation partner specialising in Tanzania statutory compliance, East African ERP deployments, and Frappe/ERPNext customisations.

• 🌐 Website: aakvatech.com
• 📧 Email: info@aakvatech.com
• 🐙 GitHub: github.com/Aakvatech-Limited

SimplifyVFD is a product of its respective owners. This guide is provided for informational purposes.