PINT-OM for developers

PINT-OM is the Oman localization of the Peppol International model for e-invoicing. For developers, it is the technical shape of Fawtara: the document models, identifiers, syntax bindings, validation artefacts, and tax-reporting document that software must handle.

This guide is a draft for developers and integrators. It explains the package boundaries and the implementation questions to answer before writing code.

The short answer

The current OpenPeppol Oman package has three main parts:

Package	What it covers
PINT OM Billing	Standard electronic invoices and credit notes issued in Oman.
PINT OM Self-Billing	Self-billing invoice and credit-note transactions where the buyer issues on behalf of the supplier.
Oman Tax Data Document	A separate tax-reporting document used to report invoice information to the tax authority.

Do not treat the invoice XML and the Tax Data Document as the same artifact. They are related, but they serve different jobs.

What PINT-OM is

PINT-OM uses the Peppol PINT methodology for Oman-specific invoice and credit-note transactions. It is a national customization, not a generic PDF format and not a free-form API payload.

The current OpenPeppol documentation says the Oman specifications define electronic invoicing and tax-reporting structures, validation rules, and exchange processes. The PINT OM Billing page defines standard electronic invoices issued in Oman, while the TDD pages define a separate tax data document process.

For software teams, that means the implementation has at least four layers:

• source-system invoice data;
• PINT-OM invoice or credit-note XML;
• validation against syntax, code lists, and rules;
• Tax Data Document generation/reporting where required.

Document package map

Use this working map when planning architecture.

Flow	Document	Developer concern
Billing	Invoice	Map source invoice data into the PINT OM invoice model and validate it.
Billing	Credit note	Keep correction references and amounts consistent with the original invoice.
Self-billing	Self-billing invoice	Support buyer-issued invoice scenarios separately from normal supplier-issued invoices.
Self-billing	Self-billing credit note	Support corrections in self-billing flows.
Tax reporting	Tax Data Document	Generate and validate the tax-reporting document separately from the buyer-facing invoice exchange.

The Tax Data Document is not exchanged between the invoice issuer and receiver. The OpenPeppol Oman landing page describes it as a regulatory report submitted to the tax authority for tax reporting and compliance purposes.

Validation is not one check

PINT-OM validation is layered. A developer should not build a single "valid XML" check and call the invoice compliant.

At minimum, plan for:

• XML well-formedness;
• schema and syntax binding conformance;
• required and conditional business terms;
• allowed code values from normative code lists;
• calculation and rounding rules;
• Oman-specific business rules;
• Schematron validation artefacts;
• TDD validation where tax reporting is in scope.

The TDD release notes say implementers should understand the semantic model and syntax binding, comply with normative code lists, and validate against published artefacts including XSD and Schematron rules. That same discipline should shape the invoice-side implementation.

Keep the source data model separate

Do not hard-code Fawtara directly into screen forms or PDF templates. Keep a source invoice model inside the application and map it into PINT-OM at the boundary.

A useful internal model should preserve:

• seller and buyer identities;
• VATIN and electronic-address identifiers;
• invoice header fields;
• document type;
• invoice line items;
• tax categories and VAT rates;
• taxable amounts, VAT amounts, totals, discounts, and charges;
• credit/debit note references;
• export, import, self-billing, and B2C flags where relevant;
• archive metadata and validation status.

The mapping layer should be testable and deterministic. If two developers run the same source invoice through the mapper, they should get the same PINT-OM output.

TDD is a separate implementation concern

The Tax Data Document has its own process page, semantic model, syntax binding, code lists, rules, and Schematrons. Treat it as its own module.

Practical implications:

• Do not embed tax-reporting logic only inside the buyer-facing invoice transmitter.
• Keep TDD generation testable from a stored source invoice.
• Preserve links between source invoice, PINT-OM invoice XML, TDD instance, validation result, and archive record.
• Track submit, update, withdraw, and failure/status scenarios if they apply to the final process.
• Do not assume every TDD is identical to the invoice XML; the TDD has metadata, extracts, and source-document handling rules.

This separation is important for debugging. A buyer-facing invoice can fail for one reason, while a tax-reporting document can fail for another.

Implementation checklist

Use this before writing production code.

Area	Checklist
Source data	Confirm where every required invoice value comes from.
Identifiers	Decide how VATIN, electronic-address, document, branch, and customer identifiers are stored.
Mapping	Build a deterministic mapper from source invoice data to PINT-OM XML.
Code lists	Centralize allowed codes and update them from the official artefacts.
Calculations	Unit-test totals, VAT amounts, allowances, charges, rounding, and negative/correction cases.
Validation	Run schema, code-list, business-rule, and Schematron checks before submission.
TDD	Treat TDD generation and validation as a separate module.
Errors	Translate validation failures into finance-friendly messages without hiding the raw error.
Archive	Store source data, generated XML, TDD records, validation status, timestamps, and correction links.
Change control	Version the mapper and keep test fixtures for every spec update.

Test fixtures to create early

Do not wait for provider testing to create fixtures. Build a local fixture set from your real business cases.

Recommended fixtures:

• simple B2B invoice;
• simple B2C invoice;
• invoice with discount;
• invoice with multiple VAT rates;
• credit note linked to an original invoice;
• debit note or correction case;
• export invoice;
• import or self-billing case if relevant;
• Arabic customer and item text;
• edge-case rounding amounts;
• intentionally invalid invoice for each validation layer.

Each fixture should include expected source data, expected XML output, expected validation result, and the reason it exists.

Current watch points

Several details should be re-verified before this guide becomes public:

• final PINT-OM status and release location;
• final data dictionary and mandatory field list;
• exact validation artefact versions;
• whether document-level monetary precision changes from two to three decimal places;
• final QR/TLV rules from Peppol Oman Architecture v1.0.2 Appendix D;
• final legislation and penalty provisions.

The current OpenPeppol Oman landing page notes that document-level monetary amounts are currently limited to two decimal places and that an update to support three decimal places is planned. Do not hard-code precision assumptions without versioning.

What is not safe to claim yet

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

• exact final field names for every business term;
• exact validation-rule counts;
• exact QR/TLV tag order or limits;
• final penalty amounts;
• that a provider or software product fully supports PINT-OM;
• that the current review-stage documentation is the final enacted spec.

The safe claim is that developers should build around the official OpenPeppol/OTA artefacts, separate invoice XML from the TDD, centralize validation, and version every mapping decision.

Next step

Start with a source-data inventory. Pick 10 real invoices and mark where each field lives in your system. Then build a mapper test around one simple B2B invoice and one correction case. Add TDD generation only after the invoice mapping and validation path is visible.