Oman's SMP and the Peppol access point layer — a developer's orientation

If you are integrating with Fawtara, you will meet three acronyms fast: SMP, SML, and access point. This guide orients you before you open the specification — in particular, it draws the line between the part of the stack you manage and the part that carries invoices, because conflating them is the most expensive early mistake.

This is orientation, not a reference. The Oman Tax Authority's own specification is the authority for every endpoint and payload.

Where the SMP sits in the five-corner model

Oman's e-invoicing uses a five-corner Peppol model: you and your customer each work through accredited service providers, and the tax authority receives the data at the same time. Direct system-to-OTA invoice submission is not allowed.

In that picture:

• an access point is the corner that actually sends and receives documents on a participant's behalf;
• the SMP (Service Metadata Publisher) is the address book: it publishes which endpoint serves a given participant, and which document types that participant can receive;
• the SML (Service Metadata Locator) is the layer that lets a sender find the right SMP entry at all.

So the SMP answers "where do I deliver, and what will they accept?" — a routing and capability question. It never carries the invoice itself. That distinction is why the API below looks nothing like an invoicing API.

What the Oman SMP API actually covers

Per the OTA's specification, the Oman SMP REST API provides secure, standards-based access to SMP resources for participant SML registration, participant service metadata, and participant Peppol Directory entries.

In practice that means operations of this shape:

• register or remove a participant (removing one also issues a deletion command to the SML);
• manage the document types a participant is registered to receive;
• manage the participant's Peppol Directory presence.

Participant identifiers follow the usual Peppol scheme — the specification's own example is of the form iso6523-actorid-upis::0088:123456.

What it does not do: submit invoices, validate invoice content, return compliance verdicts, or carry anything about the human-readable invoice. If you are looking for the invoice path, you are in the wrong document.

Authentication: mTLS, not an API key

Write operations against the Oman SMP API are mutual-TLS secured and require a valid X.509 client certificate. There is no API-key shortcut.

Plan for this early, because it is a procurement and infrastructure task, not a coding one:

• you need a certificate your platform trusts and can present from your deployment environment;
• your HTTP client, load balancer, and any egress proxy must all preserve the client certificate — this is where most teams lose a week;
• certificate lifecycle (renewal, rotation, revocation) needs an owner before go-live, not after.

Note also that your digital certificate for Peppol participation comes from OpenPeppol — that is a separate artifact from any TLS client certificate your infrastructure presents. Do not assume one covers the other.

The production endpoint does not exist yet

The specification publishes a test SMP host and records the production SMP URL as "to be provided upon go live."

Two consequences worth designing for:

1. Make the base URL configuration, not a constant. You will receive the production host later than you would like.
2. Do not infer the production hostname from the test one. A guessed host that happens to resolve is worse than one that fails loudly.

We are not going to print a production URL that the OTA has not published — including a "probable" one. Check the specification and the portal at go-live.

What this means for your architecture

• You will not be your own SMP. Oman's SMP is centralized at the OTA and providers may not run their own, so SMP interaction is integration work, not infrastructure you own.
• Most businesses never touch this API. It is the accredited provider's layer. If you are a taxpayer choosing a provider, this is background — your provider handles participant registration.
• A company can be accredited to act as its own provider if it meets the OTA's criteria and passes the prescribed tests. That is the route to touching this API directly, and it means meeting the same accreditation bar as any vendor.
• Compliance responsibility does not move. Whoever transmits, the obligation for the invoices stays with the taxpayer's business.

Where to go next

• Read the OTA's SMP API specification for the endpoint-level truth — this page deliberately does not mirror it, because a stale copy of an API reference is worse than no copy.
• Read the OpenPeppol Oman specifications for PINT-OM and the TDD.
• For invoice content — the semantic model and mandatory fields — use the PINT-OM field helper and the TDD guide rather than this page.

What is not safe to claim yet

Do not publish or rely on the following without current primary evidence:

• a production SMP URL — the OTA has not published one;
• QR code or TLV specifics — do not publish tag names, tag order, character limits, or byte counts. They remain unreleased, and this document contains no QR/TLV mapping;
• exact validation rule counts;
• that the SMP API submits, validates, or clears invoices — it does not;
• provider-specific claims about access point performance, uptime, or certification status.