Connect Your Own Software to Oman's Fawtara: What Your Code Must Produce

The short answer

If you wrote your own billing, point-of-sale or ERP software, you do not have to build a Peppol access point, a Schematron engine, a signing pipeline or a QR encoder. You have to produce clean invoice data with six Oman-specific things in it, and post it. Everything downstream of that — validation against Oman's own rules, the digital signature, the Fawtara QR code, delivery to the buyer over the network, and the separate report to the Oman Tax Authority — is what an accredited service provider is for.

That division is the whole decision, and it is usually made backwards. Teams look at the Oman specification, see 120 country-specific validation rules, an XAdES-BES signature and a tag-length-value QR payload, and scope a six-month project. Almost none of that is theirs to write.

This page draws the line precisely: what your code produces, what ours adds, and the order to build it in. It is written for the implementer. If you are still choosing a provider, how to choose an e-invoicing service provider in Oman is the page for that, and the Oman page is the commercial overview.

Do you have to build UBL XML yourself?

No — and you can if you want to. There are two ways in, and they are equally valid.

Post JSON. You send invoice data in a plain JSON object — parties, addresses, VAT identification numbers, Peppol addresses, lines with quantity, unit, unit price, VAT rate and VAT category — and the UBL 2.1 XML in the PINT Oman profile is produced from it. For a team whose product has never emitted XML, this is the shorter road by a wide margin.

Post UBL. If your software already produces UBL 2.1 — and plenty of ERP products do, because Europe has required it for years — you post the XML as it stands and it is validated and transmitted. The Oman compliance elements are still added for you.

The choice is about your codebase, not about what Oman accepts. Both routes end in the same document, the same validation and the same delivery. The complete request and response shapes are in the developer documentation, and the API and services page covers the interface as a whole.

What must your own code produce?

Ordinary invoice data, plus six things Oman asks for that no other market does. This is the part that is genuinely yours, and it is worth being exact about it.

Four of those deserve their own paragraph, because they are where in-house builds lose time.

Scheme 0248, and the OM prefix stays. An Omani participant is addressed as 0248:OM1100012345. Not scheme 9959, and not the bare number with the letters stripped. This is worth checking first because getting it wrong produces no validation message at all: the network address lookup finds nothing, and the send fails as a transport error. A developer reading that error will look at their AS4 layer, which is not the problem.

Three decimals, everywhere. The Omani rial carries 1,000 baisa, so three decimal places is the precision of the currency rather than a formatting preference. Every monetary field — line amounts, tax amounts, totals — is written to three. A codebase that has always stored money at two decimals will produce documents that look correct to every human who reads them and fail on arithmetic, because line VAT is checked against rate times net amount within a tolerance measured in baisa.

The transaction-type bitmap. Every Oman document carries a 20-character string of 1s and 0s, with at least one bit set, saying what kind of supply this is — an ordinary supply, a self-billed document, an import of services under reverse charge, and so on. It travels in the name attribute of the document type code element rather than as a field of its own, which is why it is easy to miss when reading the specification quickly. Fifteen of the twenty positions are defined and the rest are reserved. Rule IBR-001-OM enforces the shape, and several further rules key off individual positions, so a structurally valid bitmap with the wrong bit set still fails.

Reason codes on 0% lines. A Z or E tax category is not sufficient on its own. Oman requires the reason, coded: sixteen zero-rating codes VATZR-OM-01 to VATZR-OM-16, and twelve exemption codes VATEX-OM-01 to VATEX-OM-12. Your software cannot derive which applies — it is a VAT-treatment decision about your own products, made once, by someone who knows the answer. Two that come up constantly for anyone trading across the border: VATZR-OM-09 for export of a service and VATZR-OM-12 for re-export of goods.

What does GoRoute add, so your team does not build it?

Six things, each of which is a project on its own if you take it in-house.

• The Fawtara QR code. Oman requires a QR on the invoice, encoded as tag-length-value rather than as text: seller name, VAT number, timestamp, total with VAT, VAT amount and a hash, each as a tag byte, a length byte and the value, then base64-encoded and embedded in the document. It is added for you.
• The invoice hash. A SHA-256 digest of the invoice's business content, embedded alongside the QR.
• The digital signature. Oman requires an XAdES-BES enveloped signature — RSA with SHA-256, exclusive canonicalisation, the certificate held in a keystore, the signature sitting inside the UBL extensions block as the first child of the document. Getting canonicalisation wrong is a classic multi-week detour, and it is not your detour.
• Validation, in five layers. XSD structure, business rules, code lists, and then the official OpenPeppol Oman Schematron packs. A PINT Oman document is detected from its specification identifier and runs the Oman rules, which already contain the European and Peppol rules rather than layering on top of them.
• Delivery. Looking your buyer up in the network directory, constructing the AS4 message, transmitting it, and handling the receipt.
• The tax report. The Tax Data Document, derived from the invoice and filed with the Oman Tax Authority, validated against its own rules before submission.

The practical consequence: you send a standard invoice and the Oman compliance elements are added before transmission. If your team has been sizing a signing pipeline, that estimate can come out of the plan.

Which rules break first, and why

Five, in the order they tend to appear. Each one is checked before anything is sent, so these are messages you will read during development rather than incidents you will read about later.

IBR-032-OM is the one that catches almost everyone. A credit note, debit note or self-billed credit note must carry the preceding invoice's reference, issue date and UUID — all three. The UUID is the one people omit, because the ordinary Peppol billing profile does not ask for it, and it must be the original invoice's UUID rather than a fresh one. That means your software has to store the UUID it issued against every invoice it issued. Retrofitting that into a schema after the fact is unpleasant; adding a column now costs nothing.

IBR-002-OM says that UUID must be a version 5 UUID — derived from a name rather than generated at random — so re-deriving the same invoice produces the same identifier. That is what makes the preceding-invoice reference verifiable, and it is also what makes a retry recognisable as a retry rather than as a second invoice.

IBR-177-OM restricts self-billing to a short list of cases: self-billed supply, import of services under reverse charge, profit-margin self-billing, import of goods. Self-billing outside those cases is refused. This is a policy rule rather than a formatting one, so no amount of correct XML makes it pass.

IBR-034-OM covers invoices not in rial: if the document currency is not OMR, the VAT accounting currency must be present.

And the document type codes decide which rules apply at all — 380 commercial invoice, 381 credit note, 383 debit note, 386 prepayment invoice, 389 self-billed invoice, 261 self-billed credit note. The exact specification identifiers and profile strings for each are set out in the PINT OM CustomizationID and ProfileID reference; a billing invoice or credit note carries urn:peppol:pint:billing-1@om-1.

Two pages go deeper than this one on purpose: what format an Oman e-invoice must be in sets out the layers and what each refuses, and why Oman e-invoices get rejected reads a real validation result identifier by identifier.

What is the right order to build this in?

Sandbox first, and validation before sending. The sequence below is not a suggested methodology; it is how the platform is structured, and following it means the fourth stage requires no code change.

1. Get a sandbox key. Apply with a business email on the developer page. Approved developers receive a test API key and a registered test participant identifier within 24 hours on business days. There is no card and no commitment at this stage.

2. Validate before you send anything. Post a document to the deep validation endpoint and read what comes back: every rule that fired, named by its own identifier — IBR-032-OM, not "invalid document". That is a ticket a developer can act on. This runs long before you are ready to transmit, which means your data-mapping work and your commercial conversation can proceed in parallel. How to test an Oman e-invoice before you send it covers this stage on its own.

3. Exercise every path, not just the happy one. The sandbox provides four deterministic test receivers that simulate success, timeout, validation failure and recipient-not-found, with the full webhook lifecycle behind each. Handling the success case is a demo; handling the timeout is an integration. Build your retry and reconciliation logic against these before you have live invoices to lose.

4. Go live. You upgrade, a Peppol certificate is issued, your participant identifier is registered in the production network directory, and real sending and receiving are unlocked — against the same endpoints, with the same payloads. The sandbox runs the same compliance gate and the same AS4 stack as production, which is why nothing has to change.

What if you sell your software to several Omani businesses?

Then the multi-tenant question is the real one, and it has a specific answer. Each of your customers needs its own Peppol identity, because the identifier is its VAT identification number and the Tax Authority reports against that number, not against yours.

Three things follow. Each API key maps to an isolated organisation — data, invoices, configuration and audit trail kept separate per tenant. Participants and their document types can be registered through the API rather than configured by hand, which matters the moment you have more than a handful. And if you want the whole thing to appear under your own brand rather than ours, that is the white-label platform rather than a different integration; the integrator programme covers the commercial side of embedding e-invoicing in a product you sell.

For a point-of-sale product there is one more thing worth reading early: simplified tax invoices and point-of-sale in Oman covers the retail case, which does not behave like the B2B one.

Where does the tax reporting happen?

Separately from the invoice, and not by you. Oman runs a continuous-controls model: your buyer receives the invoice, and a Tax Data Document — derived from that invoice and carrying it — goes to the Oman Tax Authority, which is itself a participant on the network. It has its own document structure and its own validation, which is why a document that validates cleanly as an invoice can still leave reporting work to do.

This is the part that surprises teams who have integrated e-invoicing in Europe, where there is no equivalent step. The model is walked through in Oman's Fawtara five-corner model explained, and the document itself, field by field, in inside the Oman Tax Data Document.

Does the language you write in matter?

No. The interface is a REST API described by an OpenAPI 3.0 specification, so you can generate a client for C#, Java, Python, PHP, Go or anything else that speaks HTTP, and import the same specification into Postman or Insomnia to explore it by hand first. Nothing is installed inside your product, and there is no SDK you are obliged to adopt — which also means no dependency of ours ends up in your release cycle.

Webhooks carry the events back: delivery confirmations, validation results, tax authority responses and status changes, so you are not polling for outcomes.

Where do the invoices live?

For Oman, in Oman. GoRoute operates in-country data residency for Omani clients — invoices, keys, tax data documents and audit logs. The detail is on data residency and compliance in Oman.

Raise this in week one. It is a cheap question early and an expensive one when a security review asks it a fortnight before go-live.

Which date applies to your customers?

The dates depend on annual supplies, not on which software raises the invoice. Decision 189/2026 makes electronic tax invoices mandatory from 1 April 2027 for taxable persons whose annual supplies exceed OMR 5,000,000, and from 1 October 2027 for those at or below that figure. The page that owns that question is the Oman 2027 mandate, and which wave am I in works through the threshold. This page states no further dates deliberately.

If you sell to Omani businesses, note that the earlier of those dates is the one that matters to your roadmap rather than to your own turnover: your largest customers are the ones with the earlier obligation.

What to build this week

1. Add a UUID column to your invoice table, if you do not already store one, and start populating it. Every credit note you ever issue will need the original's.
2. Check your money precision end to end — storage, calculation, rounding, output. Three decimals, not two.
3. List every 0% product or service line you sell and decide, for each, zero-rated or exempt and which Oman code. This is a business decision and it is the long pole.
4. Count how many customer records hold a usable VAT identification number in the OM plus ten digits form. That number is the size of your data work.
5. Request a sandbox key on the developer page and validate one real invoice. One rule identifier coming back tells you more than a week of reading.
6. Decide JSON or UBL — whichever your codebase already produces.

Where GoRoute stands

GoRoute is an e-invoicing service provider accredited in Oman by the Oman Tax Authority, on 29 July 2026, through Union Digital Technologies SPC. It operates a Peppol-certified Access Point (Service Provider ID POP000991, ClayDesk LLC).

Those are checkable facts rather than adjectives, and checking them is reasonable. How to check an Oman provider's claim sets out the questions worth asking of us and of anyone else.

If it is easier to walk this through against your own schema, book a working session, or apply for a sandbox key and start with a real document.

Sources

• PINT OM Billing Process v1.0.1 — the Oman specification the validation rules come from
• Oman Tax Authority — Fawtara — the national e-invoicing programme
• OASIS UBL 2.1 — the underlying document syntax
• OpenPeppol — the network the exchange runs on
• GoRoute developer documentation — the API reference, the Oman country guide, and the sandbox quickstart

Every capability described here is what GoRoute publishes on its own developer and API pages and in its developer documentation, read on 24 August 2026. Every rule identifier and field constraint was read on the same day in the Oman PINT OM material GoRoute ships and publishes. No pricing is stated on this page and none should be inferred.