How to Connect ERPNext to a UAE Peppol ASP: Step-by-Step Setup

Quick Answer

Connecting ERPNext to a UAE Peppol ASP takes two technical minutes and one data-cleanup pass. Generate a Frappe API key and secret in ERPNext (User > API Access > Generate Keys), enter your site URL and credentials in InvoiceUAE, let it sync your Sales Invoices and Customers, then enrich each customer once with TRN/Emirate/Supply Type before testing in Mock Mode and going live. No ERPNext customisation, no custom app, no code.

Key Takeaways

You need a Frappe API Key + API Secret, generated from your ERPNext User record — the same process for self-hosted ERPNext and Frappe Cloud.
InvoiceUAE authenticates with the standard Authorization: token api_key:api_secret header — no custom app or code required.
Only submitted Sales Invoices (docstatus=1) sync — draft invoices are skipped automatically.
Customer enrichment (TRN, Emirate, Supply Type) is a one-time step per customer, not per invoice.
Always test in Mock Mode first, including at least one return invoice, before switching to live ASP submissions.

Before You Start

This guide assumes your ERPNext instance already has UAE VAT configured — Tax ID (TRN) set on your Company record, and VAT tax templates in place. If you haven't done that yet, complete ERPNext's own United Arab Emirates regional setup first; connecting InvoiceUAE before your VAT data is clean just means re-doing the enrichment step later. You'll also need an FTA-approved ASP already selected — see our ASP selection guide if you haven't chosen one yet.

Step 1: Generate a Frappe API Key in ERPNext

Log in to ERPNext (self-hosted or Frappe Cloud) with the user account you want InvoiceUAE to connect as.
Open that User's record (usually your own, or a dedicated integration user — see the FAQ below on permissions).
Scroll to the API Access section.
Click Generate Keys.
Copy both the API Key and the API Secret immediately — the secret is shown only once. If you lose it, you'll need to regenerate a new pair.

Step 2: Create Your InvoiceUAE Account and Select ERPNext

Register for a free InvoiceUAE account, then choose ERPNext as your accounting software. Select the Frappe REST API connection method (CSV export is available as a fallback if API access isn't an option for your setup).

Step 3: Enter Your ERPNext Site URL and API Credentials

In InvoiceUAE's connection screen, provide:

Your ERPNext site URL (e.g. https://yourcompany.erpnext.com or your self-hosted domain)
The API Key from Step 1
The API Secret from Step 1

InvoiceUAE authenticates every request using the standard Frappe header format: Authorization: token api_key:api_secret. Your ERPNext password is never requested or stored.

Step 4: Confirm the Initial Sync

Once connected, InvoiceUAE pulls:

All submitted Sales Invoices (docstatus=1) — draft invoices are skipped
All return invoices (is_return=1), ERPNext's credit note equivalent, linked to their original via return_against
All Customer records referenced by those invoices

Review the sync summary in InvoiceUAE to confirm invoice and customer counts look right before moving on.

Step 5: Enrich Customers with UAE PINT-AE Fields

This is the step most teams underestimate the time for. For each synced ERPNext customer, open their record in InvoiceUAE and confirm:

TRN — read automatically from ERPNext's native Tax ID field; confirm it's a valid 15-digit number
Emirate — Dubai, Abu Dhabi, Sharjah, etc., for place-of-supply reporting
Supply Type — Goods or Services

This is a one-time step per customer — once set, it applies automatically to every future invoice from that customer, with no re-entry required.

Haven't picked an ASP yet? See our complete ASP explainer and selection guide, both linking to the Ministry of Finance's official pre-approved provider list.

Read the ASP Guide →

Step 6: Connect Your ASP and Test in Mock Mode

Enter your FTA-approved ASP's credentials in InvoiceUAE Settings. Before any live submission, run the full workflow in Mock Mode:

Pick a handful of real (already-submitted) ERPNext invoices, including at least one return invoice.
Let InvoiceUAE's AI validator check TRN format, VAT calculations, and mandatory PINT-AE fields.
Generate the PINT-AE XML (UBL 2.1 + SBDH) for each and review the output.
Submit in Mock Mode and confirm the simulated accept/reject flow behaves as expected.

Step 7: Go Live Before Your Deadline

Once Mock Mode testing is clean, switch off Mock Mode and begin live submissions. There is no grace period once your deadline passes — Phase 1 (revenue ≥ AED 50 million) requires go-live by 1 January 2027; Phase 2 by 1 July 2027. See the full mandate guide for the complete timeline.

Troubleshooting

Common Issues

API Secret lost — regenerate a new key/secret pair in ERPNext, it cannot be retrieved after the fact.
No invoices syncing — check that invoices are submitted (docstatus=1), not left as drafts.
TRN validation failing — confirm the Tax ID field on the ERPNext Customer record is a 15-digit number with no extra characters.

Getting Help

Check the InvoiceUAE sync log for the specific ERPNext API error returned.
Confirm the API user has read access to Sales Invoice and Customer doctypes.
Contact Infotree support for a hands-on connection check.

Want someone to set this up for you? Contact Infotree for hands-on ERPNext e-invoicing implementation — from API connection to go-live testing, our team handles the full setup.

Frequently Asked Questions

How do I generate an API key in ERPNext?

Open your User record in ERPNext, scroll to the API Access section, and click Generate Keys. This creates an API Key and an API Secret — the secret is only shown once, so copy it immediately. The same process works for both self-hosted ERPNext and Frappe Cloud.

What permissions does the ERPNext API user need?

The user whose API key you generate needs read access to the Sales Invoice and Customer doctypes at minimum. For a dedicated integration, many teams create a separate ERPNext user specifically for InvoiceUAE with read-only permissions scoped to accounting doctypes, rather than reusing an administrator's personal key.

Does connecting ERPNext to InvoiceUAE require any ERPNext customisation?

No. The standard Frappe REST API connection requires no custom app, no code changes, and no ERPNext customisation. InvoiceUAE reads existing Sales Invoice and Customer data through the API that ships with every ERPNext installation.

How long does the ERPNext to InvoiceUAE setup take?

For a business with UAE VAT already configured in ERPNext, the technical connection (API key generation plus entering credentials in InvoiceUAE) takes a few minutes. Customer enrichment (TRN confirmation, Emirate, Supply Type) takes longer depending on customer count, since it's a one-time per-customer step.

Ready to connect ERPNext to UAE Peppol e-invoicing?

Start Your Free 15-Day Trial →

Sources: Frappe/ERPNext Documentation — United Arab Emirates Regional Features, UAE Ministry of Finance — Cabinet Decision No. 106 of 2025, Ministry of Finance — Pre-Approved Service Providers.