Fawtara API integration for custom software — where your code stops

If your business already runs its own invoicing software — an in-house system, a product you built, an ERP you control — Fawtara does not replace it. It draws a boundary through it. Some work stays in your code, some moves to an accredited service provider, and one step is a portal task that no API can do for you.

This guide draws that boundary. It is written for the team that will write the integration, and for the person deciding how much of it to build.

Where your software sits

Oman uses a five-corner model. The OTA describes the service provider's job in one sentence: it validates format and rules, then forwards validated invoices to the tax authority and to the buyer. That sentence is the whole division of labour.

Corner	Who	What it means for your integration
C1	The supplier — you	Your software. It creates the invoice data.
C2	Your accredited service provider	Receives from you, validates, transmits. The only party your code talks to.
C3	The buyer's service provider	Not yours to think about.
C4	The buyer	Receives the invoice.
C5	The Oman Tax Authority	Receives tax data from providers. Your code never calls it.

Two flows bend that shape, and both are easy to miss when scoping:

• Exports run C1 → C2 → C5, because C3 and C4 sit outside the network.
• Imports are reported through self-billing: businesses report the bayan number, and self-billed invoices must be raised for imports of goods and services. Reverse-charge invoices are also self-billed, and the data dictionary carries a specific transaction type for them.

The sequence — including the step no API can do

Check your rollout period first. Everything here is keyed to VAT registration and to which rollout you fall in. The OTA publishes a checker that takes your VATIN, and it commits to reaching out at least six months before your onboarding. The first rollout is a defined set of selected taxpayers, not everyone. Find out where you stand before you plan any engineering.

Then:

1. Choose a provider from the official accredited list. The OTA publishes it on the Fawtara Portal. A vendor's own claim is not proof of accreditation. Our companion guide on choosing a provider covers what to ask; the accredited-list guide covers how to read the registry.
2. Negotiate and sign — before the portal step, not after. The portal makes you record your stage of engagement with the provider, and all stages must be complete before the connection can proceed. The sequence is deliberate: the connection cannot run ahead of the contract.
3. Raise the connection on the Fawtara Portal. This is the authoritative act, and it is manual. Taxpayers request connection with an accredited service provider through the portal. You can hold one provider at a time.
4. Integrate. This is where your code lives — and it is provider-specific by design. The OTA does not standardise the provider's side of the link; each provider defines its own integration process.
5. Be integrated on or before your go-live date. The OTA states this plainly.

Step 3 is the one teams do not plan for. It is not an API call, it is not something your provider can do for you, and the portal will not let it complete until the commercial stages are done.

Where your code stops

This is the table to argue about internally before you write anything.

Layer	Who owns it	Why it lands there
Invoice source data and its quality	You	Nothing downstream can invent a VATIN you never captured.
Mapping source data → PINT-OM XML	Negotiable	The real build-versus-buy decision. See below.
Schematron and business-rule validation	Provider	The OTA has service providers validate invoices against Oman Schematron rules.
Transmission to the buyer, reporting to the OTA	Provider	Corners 2 and 3 are the network.
SMP lookup and routing	Provider — using the OTA's	Oman runs a centralized SMP; providers must use it rather than operating their own. Your code never touches it.
The human-readable invoice	You	Your existing document generation keeps its job, with a new one attached.
Archive and retrieval	You	The OTA has stated it will not provide invoice information back to taxpayers or service providers.
Compliance responsibility	You	Ultimate responsibility for invoice compliance remains with the taxpayer. The provider validating does not move it.

The last row is the one that matters commercially. A provider can validate your invoice and still leave you responsible for it. Buying an integration does not buy an indemnity.

Your PDF does not die — it changes job

The mandatory structured invoice format is XML. A PDF is not an e-invoice. But your document generation does not become dead code, because the human-readable invoice still has a role, particularly in B2C.

The OTA describes the B2C path like this: the seller submits the invoice to its service provider, the provider submits the tax data to the OTA, and the seller exchanges the human-readable version with the buyer using its existing mechanism — physical, PDF, or otherwise — outside the Fawtara network. That human-readable version must meet the OTA's prescribed specifications and will require a QR code.

So plan for two outputs from one source model, not one output that changes shape.

The build-versus-buy line

Only one layer is genuinely yours to decide: who turns your invoice data into PINT-OM XML.

Thin. Send your provider invoice data in whatever format their API takes and let them build and validate the XML. Faster to ship. The mapping — the part that actually encodes Oman's rules — lives in their system, and you hold one provider at a time.

Thick. Build the PINT-OM XML yourself and hand it to the provider for validation, transport, and reporting. More work. The mapping stays an asset you own and can take with you.

Either way, the same discipline applies, and it is the one thing worth doing today: keep a source invoice model inside your application and map to PINT-OM at the boundary. Do not hard-code Fawtara into screen forms or document templates. Our PINT-OM guide for developers goes through the layers — semantic model, syntax binding, code lists, Schematron — and the Tax Data Document, which is a separate regulatory report to the OTA and not something you exchange with your buyer.

Why the mapper is not today's work

The specification is real: the Oman Peppol specifications are published, and PINT-OM has a released version. But three things are still moving, and all three sit inside the mapper:

• The data dictionary is a draft for consultation. The OTA says the shared version of the data dictionary and business rules is a draft circulated to rollout participants and prospective service providers, and that a final official version will follow after consultation feedback. Mandatory, optional, and conditional fields are defined there.
• Monetary precision may change. The Oman specifications currently limit document-level monetary amounts to two decimal places, with an update to support three planned. Do not hard-code precision.
• The QR content specification is not public, and QR scope is contested (below).

The useful work today is the work that survives all three: inventory your source data, decide where every required value comes from, and build fixtures from your real invoices — a simple B2B invoice, multiple VAT rates, a credit note against an original, an export, a self-billing case, Arabic customer and item text, and an intentionally invalid one for each validation layer. None of that is invalidated by a spec revision. A finished mapper might be.

The lock-in you are choosing

Three facts compound, and they are worth reading together before you sign:

• you can hold one accredited provider at a time;
• the provider's integration surface is not standardised by the OTA, so your work is specific to them;
• requesting a connection to a new provider is what disconnects you from your current one — switching does not begin with a tidy disconnection. Our guide on connecting and switching covers the timing traps.

None of that is a reason not to integrate. It is a reason to ask, in writing and before signing, what leaving looks like: whether you can retrieve your invoice XML and validation history, and in what format.

Could you be your own service provider?

Yes — and for a software company this is the real strategic question hiding behind the technical one. The OTA is explicit: any company that meets the service provider criteria and passes the prescribed tests can be accredited and subsequently also serve as its own service provider. There is no deadline to apply, and a white-labelled solution is permitted if the criteria and tests are still met.

The bar is a business line, not a shortcut:

Requirement	What the OTA states
Capital	Paid-up capital of at least OMR 6,000.
Security	ISO/IEC 27001 certification for the information security management system.
Continuity	ISO 22301 certification, or commercial registration as the alternative evidence.
Experience	Two years of operational experience — one year for Riyada card holders. A newly set-up applicant may count parent-company experience.
Registration	The commercial registration should include two IT-related activities.
Presence	Foreign and GCC providers may participate but need a local presence in Oman.
Testing	The eDelivery Test Suite and the PINT OM Test Suite for C2–C3, on the official Peppol Testbed.

And note what accreditation does not buy you: you still may not run your own SMP. Oman implements a centralized SMP and accredited providers must use the Tax Authority's rather than operating their own. Our SMP guide explains what that management API is and, importantly, what it is not — it is not the invoice submission API, and its production URL has not been issued yet.

For one company's own invoices, the security certification alone will usually outweigh the saving. This path makes sense if you intend to serve other businesses, not to serve yourself.

If you are part of a VAT group

All companies under the same tax group sharing one tax number must follow the e-invoicing procedures, and must have a single, same service provider. If your group runs different systems per entity, that constraint lands on your architecture, not just on your paperwork. The OTA has said more detail for VAT groups will follow.

What is not settled — and must not be designed around

Two points are actively contested between two current, official OTA documents. Both documents are live, both are the OTA's own, and neither overrides the other.

B2C submission timing. The Monthly FAQ (30 June 2026) states a 24-hour window for B2C. The Service Provider FAQ says B2C timing is still under discussion, with no stipulated timeframe yet and guidance to follow. Sources disagree. Plan for the stricter case if you sell to consumers, treat it as provisional, and confirm with your provider before you rely on it.

QR scope. The Monthly FAQ states that QR applies to B2C transactions whether full or simplified. The Service Provider FAQ says QR is only expected to be mandatory for simplified B2C invoices, and that the details have not been released. Sources disagree.

On top of that, the QR content specification itself is not published. The Monthly FAQ points at an appendix of the Peppol Oman Architecture for what goes inside the code, and that appendix is not public. If you sell to consumers, this is a piece of work you cannot specify yet — scope it as unknown rather than guessing at it.

If you are B2B only, none of the three touches you.

Questions worth asking a provider — developer edition

The buyer-side questions are in our provider-selection guide. These are the ones a team writing code should add:

• Can we see your Oman test environment before we sign, and test with our own invoice examples?
• Do we send you PINT-OM XML, or your own format? If we want to send XML, will you accept it?
• How do you surface a Schematron failure — do we get the raw rule and a mapped message?
• What is the cutover path from test to production?
• If we leave, what do we get back: the source data, the XML, the validation history, in what format, and for how long can we still reach it?
• Which legal entity signs our contract, and is it the entity on the OTA's accredited list?

What is not safe to claim yet

Do not rely on the following without current primary evidence:

• a settled B2C submission window, or a settled QR scope;
• the contents, structure, or limits of the QR code;
• a final mandatory-field list or validation-rule count;
• that any provider or product fully supports PINT-OM;
• that the draft data dictionary is the final enacted specification;
• that using a provider transfers your compliance or archiving responsibility.

Next step

Check your rollout period. If you have time, spend it on the source-data inventory and the fixture set rather than the mapper — those hold their value through a spec revision. Then take the developer questions above to the providers on the OTA list, and make the build-versus-buy call once you know whose interface you would actually be building against.