Oman E-Invoicing and Fiscalization Mandates

The Sultanate of Oman has introduced e-invoicing mandates as part of its digital transformation strategy. This section outlines the key mandate affecting businesses operating in Oman.

OTA eInvoicing with Peppol

The Ministry of Commerce, Industry and Investment Promotion has implemented a mandatory e-invoicing system based on the international Peppol network, adapted for local requirements through the PINT OM (Peppol International Oman) specifications.

What is Peppol?

Peppol (Pan-European Public Procurement Online) is an international network that enables businesses to exchange electronic documents, including invoices, in a standardized format. Oman has adopted this proven framework and customized it to meet local tax and business requirements.

Regulatory Framework

Who Must Comply?

How It Works

The Oman e-invoicing system operates through a five-corner model:

This decentralized approach means businesses must work with Accredited Service Providers (ASPs) to exchange invoices and report tax information automatically to the OTA.

Document Types

The mandate covers several types of electronic documents:

Key Requirements

To comply with the OTA eInvoicing mandate, businesses must:

Benefits

The e-invoicing system provides the following benefits:

Implementation

The e-invoicing mandate is being rolled out in phases. Businesses should take the following steps:

For detailed specifications and official timelines, refer to the Ministry of Commerce, Industry and Investment Promotion e-invoicing portal.

OTA E-Invoicing with Peppol

The Tax Authority of Oman (OTA) e-invoicing system is built on the PINT OM (Peppol International Oman) specifications, establishing a comprehensive framework for electronic invoice exchange and tax reporting.

What is Oman E-Invoicing?

The Oman e-invoicing program requires businesses to exchange electronic invoices in a standardized format through the Peppol network. This system enables real-time invoice validation, automated tax reporting, and seamless business-to-business document exchange while ensuring compliance with Oman tax regulations.

The framework is based on the international Peppol BIS Billing 3.0 standard, customized for Oman requirements through the PINT OM (Peppol International Oman) specifications.

The Five-Corner Model

Oman has adopted a Decentralized Continuous Transaction Control and Exchange (DCTCE) model, which operates through five key participants:

How It Works

The invoice flow follows these steps:

1. Supplier creates invoice and submits it to their Accredited Service Provider (C2)
2. C2 validates the invoice data and converts it to Oman standard XML format
3. C2 transmits the invoice to the Buyer's Service Provider (C3) via Peppol network
4. C2 reports the Tax Data Document (TDD) to the OTA (C5)
5. C3 validates the received invoice and sends status message to C2
6. C3 delivers the invoice to the Buyer (C4)
7. C3 reports the Tax Data Document (TDD) to the OTA (C5)
8. OTA confirms receipt of TDD to both C2 and C3
9. Status messages flow back through the chain to inform both parties

Key Components

PINT OM Data Dictionary

The Data Dictionary defines all required and optional fields for invoices, including:

• Invoice identification and dates
• Party information (supplier, buyer, payee)
• Line items with pricing and quantities
• Tax breakdowns by category
• Payment terms and methods
• Allowances and charges

Tax Data Document (TDD)

A subset of the invoice data that is automatically reported to the OTA by both Service Providers, containing:

• Essential tax-related fields
• Party identifiers
• Tax calculations
• Transaction amounts

Message Level Status (MLS)

Real-time status messages that confirm each stage of the process:

• Validation success or failure
• Transmission confirmation
• Receipt acknowledgment
• TDD reporting confirmation

Business Use Cases

The Oman e-invoicing framework defines 16 business use cases (matching the 20-bit transaction type identifier) that cover common invoice, credit note, and debit note scenarios. These use cases ensure standardized handling of various transaction types while maintaining compliance with Oman VAT regulations.

The 5 Mandatory Use Cases

These use cases establish the fundamental requirements for any e-invoicing implementation in Oman. All businesses must support these scenarios:

The 11 Additional (Conditional) Use Cases

These use cases handle specific business scenarios with additional data requirements beyond standard invoice fields:

Field Complexity by Scenario

The data requirements vary significantly based on the use case:

• Mandatory use cases: 49-50 mandatory data fields
• Conditional use cases: Up to 120 data fields per invoice (mandatory, conditional, and optional)
• Total coverage: Over 135 business terms across all scenarios in the PINT OM Data Dictionary

Implementation Requirements

Businesses must:

1. Identify applicable use cases for their business operations
2. Support all 5 mandatory use cases at minimum
3. Implement conditional use cases relevant to their transaction types
4. Ensure data completeness for all required fields per use case
5. Validate against PINT OM specifications before transmission
6. Test scenarios with their Accredited Service Provider

Standards & Format

For detailed technical specifications and field definitions, refer to the Ministry of Commerce, Industry and Investment Promotion e-invoicing portal.

PINT OM Invoice Datapoints

These are the datapoints included in PINT OM in an e-invoice.

Customization ID: urn:peppol:pint:billing-1@om-1

Base-Level Invoice Datapoints

document_identifier

UBL Tag: cbc:ID
Requirement: Mandatory
Type: String

Unique identifier for the invoice.

{
  "document_identifier": "INV-001/2025"
}

{
  "document_identifier": "INV-001/2025"
}

Rules:

• [ibr-001]: Invoice MUST contain invoice number (IBT-001)
• Must be unique within the supplier's system
• No specific format required, but should be sequential and traceable

uuid

UBL Tag: cbc:UUID
Requirement: Mandatory
Type: String (UUID v4)
PINT Reference: BTOM-002

Universally unique identifier for the invoice. Must be a standard UUID v4 format.

{
  "uuid": "6f47cc9a-3b2e-4d5f-a1c8-7e9d3b4f6a2c"
}

{
  "uuid": "6f47cc9a-3b2e-4d5f-a1c8-7e9d3b4f6a2c"
}

Rules:

• [BTOM-002]: Invoice MUST contain a UUID
• Must be a valid UUID v4 format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
• Must be unique per invoice
• Required for all invoice types

issue_date

UBL Tag: cbc:IssueDate
Requirement: Mandatory
Type: Date (YYYY-MM-DD)

The date when the invoice was issued.

{
  "issue_date": "2025-06-15"
}

{
  "issue_date": "2025-06-15"
}

Rules:

• [ibr-002]: Invoice MUST contain invoice issue date (IBT-002)
• Must be in ISO 8601 format: YYYY-MM-DD
• Cannot be a future date

issue_time

UBL Tag: cbc:IssueTime
Requirement: Mandatory
Type: Time (HH:MM:SS)
PINT Reference: IBT-168

The time when the invoice was issued. PINT OM requires the issue time on all invoices.

{
  "issue_time": "14:30:00"
}

{
  "issue_time": "14:30:00"
}

Rules:

• [IBT-168]: Invoice issue time is mandatory for all PINT OM invoices
• Must be in ISO 8601 format: HH:MM:SS
• Represents the local time of invoice issuance

due_date

UBL Tag: cbc:DueDate
Requirement: Conditional
Type: Date (YYYY-MM-DD)

The date by which payment is due.

Rules:

• [IBT-009]: Payment due date
• [ibr-127-om]: Payment due date MUST be present when the amount due for payment (IBT-115) is greater than 0, except when invoice type code (IBT-003) is Credit Note (381) or Self-Billing Credit Note (261), or when the transaction type code (BTOM-001) indicates Deemed supply
• Must be in ISO 8601 format: YYYY-MM-DD
• Should be equal to or after issue_date

document_type

UBL Tag: cbc:InvoiceTypeCode
Requirement: Mandatory
Type: Code

Specifies the type of invoice document.

{
  "document_type": "380"
}

{
  "document_type": "380"
}

Allowed Values:

Rules:

• [ibr-003]: Invoice MUST contain invoice type code (IBT-003)
• [ibr-cl-01]: Invoice type code MUST be from UNCL1001 subset
• Must be one of the five approved codes for Oman

transaction_type_code

UBL Tag: cbc:ProfileExecutionID
Requirement: Mandatory
Type: String (20-bit binary)
PINT Reference: BTOM-001

A 20-character binary string indicating the nature of the invoice transaction. Each bit position corresponds to a specific transaction characteristic. If applicable, set to 1; if not, set to 0.

{
  "transaction_type_code": "10000000000000000000"
}

{
  "transaction_type_code": "10000000000000000000"
}

Bit Positions:

Rules:

• [BTOM-001]: Transaction type code MUST be a string of exactly 20 characters consisting only of 0 and 1
• At least one of the non-reserved positions (1–15) MUST be set to 1
• Reserved positions (16–20) MUST be 0
• Multiple positions can be set simultaneously where applicable

note

UBL Tag: cbc:Note
Requirement: Conditional (multiple allowed) Type: Array of Objects

Free-text notes or additional information about the invoice. Each note is an object with a text field (required) and an optional subject_code.

{
  "note": [
    {
      "text": "Tax invoice for services rendered"
    }
  ]
}

{
  "note": [
    {
      "text": "Tax invoice for services rendered"
    }
  ]
}

Rules:

• [IBT-022]: Invoice note (free text)
• [ibr-160-om]: When Frequency of billing (BTOM-006) value is 'Others', then value should be provided in Invoice note (IBT-022)
• Multiple notes can be included
• Each note can have an optional subject code (IBT-021)

tax_point_date

UBL Tag: cbc:TaxPointDate
Requirement: Conditional
Type: Date (YYYY-MM-DD)

The date when VAT becomes accountable (delivery date or tax point).

{
  "tax_point_date": "2025-06-14"
}

{
  "tax_point_date": "2025-06-14"
}

Rules:

• [IBT-007]: Value added tax point date
• [ibr-124-om]: VAT point date MUST NOT be present when invoice type code (IBT-003) is Credit Note (381) or Self-Billing Credit Note (261)
• [ibr-141-om]: When VAT point date is present, it should be before the Invoice issue date (IBT-002)
• Must be in ISO 8601 format: YYYY-MM-DD
• Typically the delivery date or date of supply

document_currency

UBL Tag: cbc:DocumentCurrencyCode
Requirement: Mandatory Type: Code (ISO 4217)

The currency in which all invoice amounts are expressed.

{
  "document_currency": "OMR"
}

{
  "document_currency": "OMR"
}

Rules:

• [ibr-005]: Invoice MUST contain invoice currency code (IBT-005)
• [ibr-cl-03]: Currency ID MUST be coded using ISO 4217 alpha-3
• [ibr-126]: All currency ID attributes must match document currency code
• [ibr-159-om]: Currency exchange rate (BTOM-004) is MUST when the Invoice currency code (IBT-005) is different from 'OMR'
• [ibr-175-om]: When Invoice currency code (IBT-005) is other than 'OMR' and Tax accounting currency (IBT-006) is 'OMR', then the value in Invoice total VAT amount in tax accounting currency (IBT-111) and Invoice total amount with VAT in OMR (BTOM-020) MUST be present
• For Oman transactions, typically "OMR" (Omani Rial)

currency_exchange_rate

UBL Tag: cbc:ExchangeRate
Requirement: Conditional
Type: Decimal

The exchange rate for converting document currency to OMR.

{
  "currency_exchange_rate": 0.384615
}

{
  "currency_exchange_rate": 0.384615
}

Rules:

• [ibr-002-om]: Currency exchange rate (BTOM-004) should contain the values to a maximum of 6 decimal places
• [ibr-159-om]: Currency exchange rate (BTOM-004) is MUST when the Invoice currency code (IBT-005) is different from 'OMR'
• [ibr-153-om]: When the Tax accounting currency (IBT-006) is set to OMR and the invoice currency code (IBT-005) differs from OMR, the source currency must be designated as the invoice currency code (IBT-005), and the target currency must be specified as the Tax accounting currency (IBT-006), provided that the currency exchange rate (BTOM-004) is available

accounting_cost

UBL Tag: cbc:AccountingCost
Requirement: Optional
Type: String

Buyer's accounting reference or cost center code.

{
  "accounting_cost": "4025:123:4343"
}

{
  "accounting_cost": "4025:123:4343"
}

Rules:

• [IBT-019]: Buyer accounting reference
• Free-text field for buyer's internal accounting codes

buyer_reference

UBL Tag: cbc:BuyerReference
Requirement: Optional
Type: String

Unique identifier assigned by the buyer for routing purposes.

{
  "buyer_reference": "BR-001/23"
}

{
  "buyer_reference": "BR-001/23"
}

Rules:

• [IBT-010]: Buyer reference

invoice_period

UBL Tag: cac:InvoicePeriod
Requirement: Conditional Type: Object

The period (or specific date) to which the invoice relates.

{
  "invoice_period": {
    "start_date": "2025-06-01",
    "end_date": "2025-06-30",
    "description_code": "MTH"
  }
}

{
  "invoice_period": {
    "start_date": "2025-06-01",
    "end_date": "2025-06-30",
    "description_code": "MTH"
  }
}

Fields:

description_code Allowed Values:

Allowed values: DLY, WKY, Q15, MTH, Q45, Q60, QTR, YRL, HYR, OTH

Context: cac:InvoicePeriod/cbc:DescriptionCode

Test: ((not(contains(normalize-space(.), ' ')) and contains(' DLY WKY Q15 MTH Q45 Q60 QTR YRL HYR OTH ', concat(' ', normalize-space(.), ' '))))

Rules:

• [IBG-14]: Invoicing period (optional group)
• [ibr-030]: If period end date is provided, start date MUST also be provided
• [ibr-138-om]: Invoicing period (IBG-14) is MUST when transaction type code (BTOM-001) has position 5 set (Summary invoice)
• [ibr-005-om]: Frequency of billing (BTOM-006) should be taken from the frequency of billing code list
• Dates must be in ISO 8601 format: YYYY-MM-DD

order_reference

UBL Tag: cac:OrderReference
Requirement: Optional Type: Object

Reference to the buyer's purchase order.

{
  "order_reference": {
    "po_number": "PO-001/23",
    "so_number": "SO-001/23"
  }
}

{
  "order_reference": {
    "po_number": "PO-001/23",
    "so_number": "SO-001/23"
  }
}

Fields:

Rules:

• [IBT-013]: Purchase order reference
• [IBT-014]: Sales order reference

document_references

UBL Tag: cac:BillingReference
Requirement: Conditional (multiple allowed) Type: Array of Objects

Reference to preceding invoice (e.g., for credit notes or debit notes).

{
  "document_references": [
    {
      "id": "INV-1001/2025",
      "issue_date": "2025-05-15"
    }
  ]
}

{
  "document_references": [
    {
      "id": "INV-1001/2025",
      "issue_date": "2025-05-15"
    }
  ]
}

Fields:

Rules:

• [IBG-03]: Preceding invoice reference
• [ibr-055-om]: Preceding invoice reference (IBG-03) is mandatory when invoice type code (IBT-003) is 381 (Credit Note), 383 (Debit Note), or 261 (Self-Billing Credit Note)
• Multiple billing references can be provided

credit_note_reason_code

UBL Tag: cac:DiscrepancyResponse/cbc:ResponseCode
Requirement: Conditional
Type: Code

The reason code for issuing a credit note. Required when document_type is 381 (Credit Note) or 261 (Self-Billing Credit Note).

{
  "credit_note_reason_code": "CAN"
}

{
  "credit_note_reason_code": "CAN"
}

Allowed Values:

Rules:

• [ibr-001-om]: Credit note reason code (BTOM-003) value should be from the Reasons for credit note code list
• [ibr-158-om]: Where the Invoice type code (IBT-003) is Credit Note (381) or Self-Billing Credit Note (261), Credit note reason code (BTOM-003) MUST be present

prepayment_invoice_id

UBL Tag: cac:BillingReference/cac:InvoiceDocumentReference/cbc:ID
Requirement: Conditional
Type: String
PINT Reference: BTOM-027

Reference to the prepayment invoice number. Required when the transaction type code (BTOM-001) position 15 is set (Prepayment).

{
  "prepayment_invoice_id": "PREPAY-001/2025"
}

{
  "prepayment_invoice_id": "PREPAY-001/2025"
}

Rules:

• [BTOM-027]: Prepayment invoice reference number
• Required when the final invoice settles a prepayment
• Must reference a valid, previously issued prepayment invoice

prepayment_invoice_uuid

UBL Tag: cac:BillingReference/cac:InvoiceDocumentReference/cbc:UUID
Requirement: Conditional
Type: String (UUID v4)
PINT Reference: BTOM-014

The UUID of the referenced prepayment invoice. Required when prepayment_invoice_id is provided.

{
  "prepayment_invoice_uuid": "a4b2c8d1-3e5f-4a7b-9c1d-2e4f6a8b0c3d"
}

{
  "prepayment_invoice_uuid": "a4b2c8d1-3e5f-4a7b-9c1d-2e4f6a8b0c3d"
}

Rules:

• [BTOM-014]: Prepayment invoice UUID
• Must be a valid UUID v4 format
• Must match the UUID of the referenced prepayment invoice

other_references

Requirement: Optional
Type: Object

Additional document references related to the invoice transaction.

{
  "other_references": {
    "despatch_document_reference": "DESP-2025-001",
    "receipt_document_reference": "REC-2025-001",
    "originator_document_reference": "ORIG-2025-001",
    "contract_document_reference": {
      "id": "CONTRACT-2025-001",
      "document_description": "OMR 100000"
    },
    "customs_document_reference": "CUSTOMS-2025-001",
    "project_reference": "PROJECT-2025-001"
  }
}

{
  "other_references": {
    "despatch_document_reference": "DESP-2025-001",
    "receipt_document_reference": "REC-2025-001",
    "originator_document_reference": "ORIG-2025-001",
    "contract_document_reference": {
      "id": "CONTRACT-2025-001",
      "document_description": "OMR 100000"
    },
    "customs_document_reference": "CUSTOMS-2025-001",
    "project_reference": "PROJECT-2025-001"
  }
}

Fields:

Rules:

• [IBT-011]: Project reference (optional)
• [IBT-012]: Contract reference (optional)
• [IBT-015]: Receipt advice reference (optional)
• [IBT-016]: Despatch advice reference (optional)
• [IBT-017]: Originator document reference (optional)
• All fields within other_references are optional

Party Information

sending_party

UBL Tag: cac:AccountingSupplierParty
Requirement: Mandatory Type: Object

Information about the supplier (seller) issuing the invoice.

{
  "sending_party": {
    "trade_name": "Muscat Trading LLC",
    "peppol_id": "0248:OM1234567890",
    "street_address": "Al Qurum Heights, Way 2834",
    "city_address": "Muscat",
    "additional_street_address": "Building 45",
    "postal_zone": "112",
    "country_subdivision_code": "MO",
    "additional_address_lines": "Near City Centre",
    "country_code": "OM",
    "vat_number": "OM1234567890",
    "legal_name": "Muscat Trading LLC",
    "identifiers": [
      {
        "type": "CR",
        "value": "1234567"
      }
    ],
    "contact_name": "Ahmed Al-Busaidi",
    "contact_telephone": "+96824567890",
    "contact_email": "ahmed@muscattrading.om"
  }
}

{
  "sending_party": {
    "trade_name": "Muscat Trading LLC",
    "peppol_id": "0248:OM1234567890",
    "street_address": "Al Qurum Heights, Way 2834",
    "city_address": "Muscat",
    "additional_street_address": "Building 45",
    "postal_zone": "112",
    "country_subdivision_code": "MO",
    "additional_address_lines": "Near City Centre",
    "country_code": "OM",
    "vat_number": "OM1234567890",
    "legal_name": "Muscat Trading LLC",
    "identifiers": [
      {
        "type": "CR",
        "value": "1234567"
      }
    ],
    "contact_name": "Ahmed Al-Busaidi",
    "contact_telephone": "+96824567890",
    "contact_email": "ahmed@muscattrading.om"
  }
}

Key Fields:

Country Subdivision Codes:

Rules:

• [ibr-004]: Legal name (IBT-027) MUST be provided
• [ibr-006]: Postal address (IBG-05) MUST contain country code (IBT-040)
• [ibr-009-om]: Electronic address (IBT-034) MUST have scheme identifier 0248
• [ibr-144-om]: In postal address (IBG-05), Address line 1 (IBT-035), City (IBT-037) and country subdivision (IBT-039) must be provided
• [ibr-om-vat]: Supplier VAT number (IBT-031) MUST be provided

receiving_party

UBL Tag: cac:AccountingCustomerParty
Requirement: Mandatory Type: Object

Information about the party receiving the invoice.

{
  "receiving_party": {
    "trade_name": "Salalah Imports Co.",
    "peppol_id": "0248:OM0987654321",
    "street_address": "23rd July Street",
    "city_address": "Salalah",
    "additional_street_address": "Office 12, Block B",
    "postal_zone": "211",
    "country_subdivision_code": "SHRFZ",
    "additional_address_lines": "Industrial Area",
    "country_code": "OM",
    "vat_number": "OM0987654321",
    "legal_name": "Salalah Imports Co. SAOG",
    "identifiers": [
      {
        "type": "CR",
        "value": "7654321"
      }
    ],
    "contact_name": "Fatma Al-Lawati",
    "contact_telephone": "+96823456789",
    "contact_email": "fatma@salalahimports.om"
  }
}

{
  "receiving_party": {
    "trade_name": "Salalah Imports Co.",
    "peppol_id": "0248:OM0987654321",
    "street_address": "23rd July Street",
    "city_address": "Salalah",
    "additional_street_address": "Office 12, Block B",
    "postal_zone": "211",
    "country_subdivision_code": "SHRFZ",
    "additional_address_lines": "Industrial Area",
    "country_code": "OM",
    "vat_number": "OM0987654321",
    "legal_name": "Salalah Imports Co. SAOG",
    "identifiers": [
      {
        "type": "CR",
        "value": "7654321"
      }
    ],
    "contact_name": "Fatma Al-Lawati",
    "contact_telephone": "+96823456789",
    "contact_email": "fatma@salalahimports.om"
  }
}

Key Fields:

Country Subdivision Codes:

Rules:

• [ibr-007]: Legal name (IBT-044) MUST be provided
• [ibr-008]: Postal address (IBG-08) MUST contain country code (IBT-055)
• [ibr-011]: Electronic address (IBT-049) MUST have scheme identifier
• [ibr-CL-11]: Electronic address scheme MUST be from code list
• [ibr-144-om]: In postal address (IBG-08), Address line 1 (IBT-050), City (IBT-052) and country subdivision (IBT-054) must be provided
• [ibr-135-om]: Either identifier (IBT-046) or VAT identifier (IBT-048) MUST be present when the transaction type code (BTOM-001) does not indicate an Export (position 7) and scheme identifier (IBT-049-1) is '0248'
• [ibr-179-om]: VAT identifier (IBT-048) MUST occur maximum once

third_party

UBL Tag: cac:TaxRepresentativeParty
Requirement: Conditional
Type: Object

Third-party details for third-party invoices. Required when transaction type code (BTOM-001) position 4 is set (ThirdParty).

{
  "third_party": {
    "name": "Oman Agency Services LLC",
    "vat_number": "OM1122334455",
    "street_address": "Sultan Qaboos Street",
    "city_address": "Nizwa",
    "postal_zone": "611",
    "country_subdivision_code": "MO",
    "country_code": "OM"
  }
}

{
  "third_party": {
    "name": "Oman Agency Services LLC",
    "vat_number": "OM1122334455",
    "street_address": "Sultan Qaboos Street",
    "city_address": "Nizwa",
    "postal_zone": "611",
    "country_subdivision_code": "MO",
    "country_code": "OM"
  }
}

Key Fields:

Rules:

• [ibr-om-third]: When transaction type code (BTOM-001) position 4 is set (ThirdParty), the third_party group MUST be provided
• [ibr-056]: Third-party name (IBT-062) MUST be provided when group is present
• [ibr-057]: Third-party VAT number (IBT-063) MUST be provided when group is present
• [ibr-058]: Third-party country code (IBT-069) MUST be provided when group is present

Invoice Lines

invoice_lines

UBL Tag: cac:InvoiceLine
Requirement: Mandatory (at least one)
Type: Array of Objects

Individual line items in the invoice.

{
  "invoice_lines": [
    {
      "id": "1",
      "note": "Consulting services for Q2",
      "quantity": 10,
      "uom": "HUR",
      "accounting_cost": "SVC-001",
      "name": "IT Consulting",
      "description": "IT infrastructure consulting services",
      "item_type": "SV",
      "hs_code": "998311",
      "vat_category": "S",
      "vat_percentage": 5,
      "unit_price": 150.000,
      "base_quantity": 1,
      "line_total_including_vat": 1575.000
    },
    {
      "id": "2",
      "quantity": 50,
      "uom": "H87",
      "name": "Office Supplies",
      "description": "A4 paper boxes",
      "item_type": "GS",
      "hs_code": "48025610",
      "vat_category": "S",
      "vat_percentage": 5,
      "unit_price": 12.500,
      "base_quantity": 1,
      "line_total_including_vat": 656.250
    }
  ]
}

{
  "invoice_lines": [
    {
      "id": "1",
      "note": "Consulting services for Q2",
      "quantity": 10,
      "uom": "HUR",
      "accounting_cost": "SVC-001",
      "name": "IT Consulting",
      "description": "IT infrastructure consulting services",
      "item_type": "SV",
      "hs_code": "998311",
      "vat_category": "S",
      "vat_percentage": 5,
      "unit_price": 150.000,
      "base_quantity": 1,
      "line_total_including_vat": 1575.000
    },
    {
      "id": "2",
      "quantity": 50,
      "uom": "H87",
      "name": "Office Supplies",
      "description": "A4 paper boxes",
      "item_type": "GS",
      "hs_code": "48025610",
      "vat_category": "S",
      "vat_percentage": 5,
      "unit_price": 12.500,
      "base_quantity": 1,
      "line_total_including_vat": 656.250
    }
  ]
}

Key Fields:

Item Type Codes (BTOM-013):

VAT Category Codes:

VAT Exemption Reason Codes (IBT-186) — required when vat_category is E:

Zero-Rating Reason Codes — required when vat_category is Z:

Rules:

• [ibr-021]: Each invoice line MUST have unique identifier (IBT-126)
• [ibr-022]: Each invoice line MUST contain invoiced quantity (IBT-129)
• [ibr-023]: Each invoice line MUST contain unit of measure code (IBT-130)
• [ibr-024]: Each invoice line MUST contain line net amount (IBT-131)
• [ibr-025]: Unit of measure code MUST be from UN/ECE Recommendation 20
• [ibr-026]: Each invoice line MUST contain item net price (IBT-146)
• [ibr-027]: Item net price MUST NOT be negative
• [ibr-CL-23]: Unit code MUST be coded according to UN/ECE Rec 20 with Rec 21 extension
• [ibr-SR-50]: Item description (IBT-154) MUST occur maximum once
• [ibr-SR-58]: Invoiced item VAT category code (IBT-151) MUST be present
• [ibr-125-om]: In Item Information (IBG-31), Item description (IBT-154) MUST be there
• [ibr-145-om]: Each Invoice line (IBG-25) MUST be categorized with an Invoiced item VAT category code (IBT-151)
• [ibr-147-om]: Invoice line net amount (IBT-131) MUST equal (Invoiced quantity (IBT-129) × (Item net price (IBT-146) / Item price base quantity (IBT-149)) + Sum of invoice line charge amount (IBT-141) − Sum of invoice line allowance amount (IBT-136))
• [BTOM-013]: Item type MUST be either "GS" (goods) or "SV" (services)
• [BTOM-017]: Line total including VAT MUST be provided
• [ibr-167-om]: Line VAT Information (IBG-30) with Invoiced item VAT category code (IBT-151) as 'Exempt from VAT' MUST have a VAT exemption reason code (IBT-186)
• [ibr-163-om]: In Line VAT Information (IBG-30) where Invoiced item VAT category code (IBT-151) is 'Exempt', VAT Line amount shall not be present
• [ibr-165-om]: In Line VAT Information (IBG-30) where Invoiced item VAT category code (IBT-151) is 'Zero Rated', VAT Line amount MUST be zero
• [ibr-om-zero]: When VAT category code (IBT-151) is 'Z' (Zero-rated), a zero_rating_reason_code MUST be provided
• [ibr-194-om]: Invoice line amount payable (BTOM-010) must be provided
• [ibr-126-om]: In Price Details (IBG-29), Item price base quantity (IBT-149) and Item Gross Price (IBT-148) MUST be there

Import Details

import_details

Requirement: Conditional
Type: Object

Import-related details. Required when transaction type code (BTOM-001) position 13 is set (ImportGoods).

{
  "import_details": {
    "import_date": "2025-06-10",
    "customs_declaration_number": "CD-2025-OM-00456",
    "incoterms": "CIF"
  }
}

{
  "import_details": {
    "import_date": "2025-06-10",
    "customs_declaration_number": "CD-2025-OM-00456",
    "incoterms": "CIF"
  }
}

Fields:

Rules:

• [ibr-om-import]: When transaction type code (BTOM-001) position 13 is set (ImportGoods), import_details MUST be provided
• [ibr-om-import-date]: Import date MUST be in ISO 8601 format: YYYY-MM-DD
• [ibr-om-import-cdn]: Customs declaration number MUST be provided for import transactions

Totals

invoice_totals

UBL Tag: cac:LegalMonetaryTotal
Requirement: Mandatory
Type: Object

Summary of all monetary totals for the invoice.

{
  "invoice_totals": {
    "line_extension_amount": "2125.000",
    "tax_exclusive_amount": "2125.000",
    "tax_inclusive_amount": "2231.250",
    "allowance_total_amount": "0.000",
    "charge_total_amount": "0.000",
    "prepaid_amount": "500.000",
    "payable_rounding_amount": "0.000",
    "payable_amount": "1731.250"
  }
}

{
  "invoice_totals": {
    "line_extension_amount": "2125.000",
    "tax_exclusive_amount": "2125.000",
    "tax_inclusive_amount": "2231.250",
    "allowance_total_amount": "0.000",
    "charge_total_amount": "0.000",
    "prepaid_amount": "500.000",
    "payable_rounding_amount": "0.000",
    "payable_amount": "1731.250"
  }
}

Key Fields:

Rules:

• [ibr-009]: Invoice total amounts MUST be provided
• [ibr-012]: Invoice total VAT amount MUST equal sum of VAT category tax amounts
• [ibr-013]: Invoice total without VAT = Sum of line net amounts − allowances + charges
• [ibr-014]: Invoice total with VAT = Invoice total without VAT + Invoice total VAT amount
• [ibr-015]: Amount due for payment = Invoice total with VAT − Prepaid amount + Rounding amount
• All amounts must be in the document currency (IBT-005)
• OMR amounts should use 3 decimal places

Additional Datapoints

allowance_charge (Document Level)

UBL Tag: cac:AllowanceCharge
Requirement: Optional (multiple allowed)
Type: Array of Objects

Document-level allowances (discounts) or charges (fees).

{
  "allowance_charge": [
    {
      "charge_indicator": false,
      "allowance_charge_reason_code": "95",
      "allowance_charge_reason": "Discount",
      "multiplier_factor_numeric": "2.00",
      "amount": "42.500",
      "base_amount": "2125.000",
      "vat_category": "S",
      "vat_percentage": "5.00"
    }
  ]
}

{
  "allowance_charge": [
    {
      "charge_indicator": false,
      "allowance_charge_reason_code": "95",
      "allowance_charge_reason": "Discount",
      "multiplier_factor_numeric": "2.00",
      "amount": "42.500",
      "base_amount": "2125.000",
      "vat_category": "S",
      "vat_percentage": "5.00"
    }
  ]
}

Key Fields:

Rules:

• [ibr-036]: Document level allowance amount MUST NOT be negative
• [ibr-037]: Document level allowance base amount MUST be provided if percentage is provided
• [ibr-038]: Document level charge amount MUST NOT be negative
• [ibr-039]: Document level charge base amount MUST be provided if percentage is provided
• [ibr-041]: Document level allowance MUST have VAT category code (IBT-095)
• [ibr-042]: Document level charge MUST have VAT category code (IBT-102)
• [ibr-CO-04]: Allowance amount = Base amount × Multiplier factor
• [ibr-CO-05]: Charge amount = Base amount × Multiplier factor
• [ibr-131-om]: Allowance amount (IBT-092, IBT-136) must equal base amount (IBT-093, IBT-137) × percentage (IBT-094, IBT-138) ÷ 100 if base amount and percentage exist
• [ibr-146-om]: Charge amount (IBT-099, IBT-141) must equal base amount (IBT-100, IBT-142) × percentage (IBT-101, IBT-143) ÷ 100 if base amount and percentage exist
• [ibr-168-om]: Document level allowances (IBG-20) with Document level allowance VAT category code (IBT-095) as 'Exempt from VAT' MUST have a Document level allowance VAT exemption reason code (IBT-196)
• [ibr-169-om]: Document level charges (IBG-21) with Document level charge VAT category code (IBT-102) as 'Exempt from VAT' MUST have a Document level charge VAT exemption reason code (IBT-198)

payment_means

UBL Tag: cac:PaymentMeans
Requirement: Conditional (multiple allowed)
Type: Array of Objects

Payment method information including bank details or card information.

{
  "payment_means": [
    {
      "payment_means_code": "30",
      "payment_id": "INV-2025-001",
      "account_id": "OM070101234567890123456",
      "account_name": "Muscat Trading LLC",
      "financial_institution_branch": "BMUSTOMXXX"
    }
  ]
}

{
  "payment_means": [
    {
      "payment_means_code": "30",
      "payment_id": "INV-2025-001",
      "account_id": "OM070101234567890123456",
      "account_name": "Muscat Trading LLC",
      "financial_institution_branch": "BMUSTOMXXX"
    }
  ]
}

Common Payment Means Codes:

Rules:

• [ibr-049]: Payment means type code (IBT-081) MUST be from UN/ECE code list 4461
• [ibr-061]: If payment means is credit transfer, account identifier (IBT-084) MUST be provided
• [ibr-CL-16]: Payment means code MUST be from approved subset
• [ibr-191-om]: Payment means type code (IBT-081) must be provided except when the invoice type code (IBT-003) is Credit Note (381), Self-Billing Credit Note (261), or when the transaction type code (BTOM-001) indicates Deemed supply (position 8)
• [ibr-192-om]: When Payment means type code (IBT-081) is 'credit transfer' then Payment account identifier (IBT-084) must be provided

delivery_terms

UBL Tag: cac:DeliveryTerms
Requirement: Conditional
Type: Object

Delivery terms (Incoterms) for the transaction.

Rules:

• [ibr-196-om]: The Incoterms (BTOM-022) must be provided when applicable (e.g., for export and import transactions)

Oman eInvoicing Lifecycle

This guide covers the complete lifecycle of e-invoicing in Oman, from onboarding to the Peppol network through sending and receiving invoices.

Onboarding to Network

Before you can send or receive e-invoices through the Oman Peppol network, you must complete the onboarding process:

1. Register with an Accredited Service Provider (ASP)

The Oman e-invoicing system operates through Accredited Service Providers. You must:

• Select an ASP approved by the Tax Authority of Oman (OTA)
• Complete registration with your chosen ASP
• Provide your business registration details (Commercial Registration, VAT TIN)
• Obtain your Peppol participant identifier

2. Obtain Peppol Credentials

Your ASP will provide you with:

3. Configure Your System

Set up your integration:

• Configure API authentication
• Map your internal data models to PINT OM format
• Set up webhook endpoints (for receiving invoices)
• Test your connection in sandbox environment

4. Go Live

Once testing is complete:

• Activate your production account
• Begin exchanging invoices with registered Peppol participants
• Monitor compliance through your ASP dashboard

Sending an Invoice

Sending an invoice through Peppol involves four key steps: preparing the invoice data, verifying the recipient, sending the document, and handling responses.

Preparing the Invoice Data

Create your invoice following the PINT OM specification. Here's the basic structure:

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "document_identifier": "OM001-Test",
  "issue_date": "2025-01-30",
  "issue_time": "14:30:00",
  "due_date": "2025-02-06",
  "document_type": "380",
  "document_currency": "OMR",
  
  "receiving_party": {
    "peppol_id": "0248:OM1345678901",
    "street_address": "Street Name",
    "city_address": "Muscat",
    "country_subdivision_code": "MO",
    "country_code": "OM",
    "vat_number": "134567890123003",
    "legal_name": "Buyer Legal Name",
    "identifiers": [
      {
        "type": "CR",
        "value": "112345679000001"
      }
    ]
  },
  
  "payment_means": [
    {
      "payment_means_code": "30",
      "account_id": "OM070100000123456789012",
      "account_name": "Oman Trading SAOC",
      "financial_institution_branch": "BMUSCMCX"
    }
  ],
  
  "invoice_totals": {
    "line_extension_amount": "1000.00",
    "tax_exclusive_amount": "1000.00",
    "tax_inclusive_amount": "1050.00",
    "payable_amount": "1050.00"
  },
  
  "invoice_lines": [
    {
      "id": "1",
      "quantity": "100",
      "uom": "H87",
      "line_extension_amount": "1000.00",
      "name": "Item Name",
      "description": "Item Description",
      "commodity_code": "G",
      "hs_code": "84713000",
      "vat_category": "S",
      "vat_percentage": "5.00",
      "unit_price": "10.00",
      "base_quantity": "1"
    }
  ]
}

{
  "country": "OM",
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "document_identifier": "OM001-Test",
  "issue_date": "2025-01-30",
  "issue_time": "14:30:00",
  "due_date": "2025-02-06",
  "document_type": "380",
  "document_currency": "OMR",
  
  "receiving_party": {
    "peppol_id": "0248:OM1345678901",
    "street_address": "Street Name",
    "city_address": "Muscat",
    "country_subdivision_code": "MO",
    "country_code": "OM",
    "vat_number": "134567890123003",
    "legal_name": "Buyer Legal Name",
    "identifiers": [
      {
        "type": "CR",
        "value": "112345679000001"
      }
    ]
  },
  
  "payment_means": [
    {
      "payment_means_code": "30",
      "account_id": "OM070100000123456789012",
      "account_name": "Oman Trading SAOC",
      "financial_institution_branch": "BMUSCMCX"
    }
  ],
  
  "invoice_totals": {
    "line_extension_amount": "1000.00",
    "tax_exclusive_amount": "1000.00",
    "tax_inclusive_amount": "1050.00",
    "payable_amount": "1050.00"
  },
  
  "invoice_lines": [
    {
      "id": "1",
      "quantity": "100",
      "uom": "H87",
      "line_extension_amount": "1000.00",
      "name": "Item Name",
      "description": "Item Description",
      "commodity_code": "G",
      "hs_code": "84713000",
      "vat_category": "S",
      "vat_percentage": "5.00",
      "unit_price": "10.00",
      "base_quantity": "1"
    }
  ]
}

Key Points:

• The document_type "380" represents a standard commercial invoice
• Buyer must have valid Peppol ID
• At least one invoice line is mandatory

Verifying the Recipient

Before sending an invoice, verify that the recipient is registered in the Peppol network to avoid errors.

Single Lookup

Verify a single recipient by Peppol ID.

Endpoint: GET /v1/peppol/lookup/{peppol_id}

Example Request:

GET /v1/peppol/lookup/0248:OM1345678901

Response:

{
  "status": "success",
  "message": "Participant lookup completed.",
  "data": {
    "network": "peppol",
    "identifier": "0248:OM1345678901",
    "is_registered": true,
    "participant_name": "Buyer Legal Name",
    "country_code": "OM",
    "supported_document_types": [
      "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2",
      "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2"
    ]
  }
}

Lookup by Document Type

Check whether a specific participant supports a particular document type.

Endpoint: GET /v1/peppol/lookup/{peppol_id}/{document_type}

Example Request:

GET /v1/peppol/lookup/0248:OM1345678901/invoice

Response:

{
  "status": "success",
  "message": "Participant lookup completed.",
  "data": {
    "network": "peppol",
    "identifier": "0248:OM1345678901",
    "is_registered": true,
    "participant_name": "Buyer Legal Name",
    "country_code": "OM",
    "supported_document_types": [
      "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
    ]
  }
}

Best Practices:

• Always verify recipients before sending
• Cache verification results to avoid repeated checks
• Handle cases where is_registered is false
• Provide clear error messages to users

Validating a Document (Optional)

Before sending, you can validate your invoice against the PINT OM specification without submitting it to the network.

Endpoint: POST /v1/{participant_id}/documents/validate

Request Body:

{
  "document": {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "document_identifier": "OM001-Test",
    "issue_date": "2025-01-30",
    "issue_time": "14:30:00",
    "document_type": "380",
    "document_currency": "OMR",
    "receiving_party": { },
    "invoice_totals": { },
    "invoice_lines": [ ]
  }
}

Response (valid):

{
  "status": "success",
  "message": "Document validated.",
  "data": {
    "result": "valid",
    "error_count": 0,
    "errors": []
  }
}

Response (invalid):

{
  "status": "success",
  "message": "Document validated.",
  "data": {
    "result": "invalid",
    "error_count": 2,
    "errors": [
      {
        "field_name": "receiving_party.legal_name",
        "rule_code": "ibr-001",
        "error_message": "An Invoice MUST have a Buyer name (IBT-044).",
        "error_level": "fatal"
      }
    ]
  }
}

Sending the Document

Once the invoice data is prepared and the recipient is verified, send the invoice through the Peppol network.

Single Document Submission

Send a single invoice to the Peppol network.

Endpoint: POST /v1/{participant_id}/documents

The endpoint accepts two content types:

When submitting XML, the document is parsed, mapped to the internal PINT OM data model, and run through the same validation pipeline as the JSON path. The response is always application/json.

{
  "document": {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "document_identifier": "OM001-Test",
    "issue_date": "2025-01-30",
    "issue_time": "14:30:00",
    "due_date": "2025-02-06",
    "document_type": "380",
    "document_currency": "OMR",
    "receiving_party": {
      "peppol_id": "0248:OM1345678901",
      "country_code": "OM",
      "vat_number": "134567890123003",
      "legal_name": "Buyer Legal Name"
    },
    "invoice_totals": {
      "line_extension_amount": "1000.00",
      "tax_exclusive_amount": "1000.00",
      "tax_inclusive_amount": "1050.00",
      "payable_amount": "1050.00"
    },
    "invoice_lines": [ ]
  }
}

{
  "country": "OM",
  "document": {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "document_identifier": "OM001-Test",
    "issue_date": "2025-01-30",
    "issue_time": "14:30:00",
    "due_date": "2025-02-06",
    "document_type": "380",
    "document_currency": "OMR",
    "receiving_party": {
      "peppol_id": "0248:OM1345678901",
      "country_code": "OM",
      "vat_number": "134567890123003",
      "legal_name": "Buyer Legal Name"
    },
    "invoice_totals": {
      "line_extension_amount": "1000.00",
      "tax_exclusive_amount": "1000.00",
      "tax_inclusive_amount": "1050.00",
      "payable_amount": "1050.00"
    },
    "invoice_lines": [ ]
  }
}

Request Headers:

X-Flick-Auth-Key: your_api_key
 
Content-Type: application/json        # for JSON submission
# or
Content-Type: application/xml         # for PINT OM XML submission

Bulk Document Submission

Send multiple invoices in a single request for efficient batch processing.

Endpoint: POST /v1/{participant_id}/documents/bulk

{
  "documents": [
    {
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "document_identifier": "OM001-Test",
      "issue_date": "2025-01-30",
      "issue_time": "14:30:00",
      "document_type": "380",
      "document_currency": "OMR",
      "receiving_party": { },
      "invoice_totals": { },
      "invoice_lines": [ ]
    },
    {
      "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "document_identifier": "OM002-Test",
      "issue_date": "2025-01-30",
      "issue_time": "14:30:00",
      "document_type": "380",
      "document_currency": "OMR",
      "receiving_party": { },
      "invoice_totals": { },
      "invoice_lines": [ ]
    }
  ]
}

{
  "country": "OM",
  "documents": [
    {
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "document_identifier": "OM001-Test",
      "issue_date": "2025-01-30",
      "issue_time": "14:30:00",
      "document_type": "380",
      "document_currency": "OMR",
      "receiving_party": { },
      "invoice_totals": { },
      "invoice_lines": [ ]
    },
    {
      "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "document_identifier": "OM002-Test",
      "issue_date": "2025-01-30",
      "issue_time": "14:30:00",
      "document_type": "380",
      "document_currency": "OMR",
      "receiving_party": { },
      "invoice_totals": { },
      "invoice_lines": [ ]
    }
  ]
}

Bulk Submission Limits:

Best Practices for Bulk Submission:

• Split large batches into multiple requests if needed
• Monitor results[].status for individual document outcomes
• Implement retry logic for failed documents only (use POST /v1/{participant_id}/documents/{document_id}/retry)
• Use bulk submission for end-of-day batch processing
• Track document_id values in results for status checking

Handling Responses

The API returns different responses based on the outcome of your request.

Single Document Success Response

{
  "status": "success",
  "message": "Document accepted for Peppol network delivery.",
  "data": {
    "document_id": "019534a1-b7be-7212-8c77-685b3edf267f",
    "status": "processing",
    "document_identifier": "OM001-Test",
    "peppol_message_id": null,
    "envelope_id": null,
    "exchange_status": "pending",
    "reporting_status": "pending",
    "is_duplicate": false
  }
}

{
  "status": "success",
  "message": "Document accepted for Peppol network delivery.",
  "data": {
    "document_id": "019534a1-b7be-7212-8c77-685b3edf267f",
    "status": "processing",
    "document_identifier": "OM001-Test",
    "peppol_message_id": null,
    "envelope_id": null,
    "exchange_status": "pending",
    "reporting_status": "pending",
    "is_duplicate": false
  }
}

Response Fields:

Bulk Submission Success Response

{
  "status": "success",
  "message": "Batch accepted for Peppol network delivery.",
  "data": {
    "batch_id": "019534a1-b7be-7212-8c77-685aafd41e2b",
    "total_documents": 2,
    "submitted_count": 2,
    "failed_count": 0,
    "is_duplicate": false,
    "results": [
      {
        "document_id": "019534a1-b7be-7212-8c77-685b3edf267f",
        "status": "processing",
        "document_identifier": "OM001-Test",
        "exchange_status": "pending",
        "reporting_status": "pending",
        "error": null
      },
      {
        "document_id": "019534a2-c8cf-8323-9d88-796c4feg378g",
        "status": "processing",
        "document_identifier": "OM002-Test",
        "exchange_status": "pending",
        "reporting_status": "pending",
        "error": null
      }
    ]
  }
}

{
  "status": "success",
  "message": "Batch accepted for Peppol network delivery.",
  "data": {
    "batch_id": "019534a1-b7be-7212-8c77-685aafd41e2b",
    "total_documents": 2,
    "submitted_count": 2,
    "failed_count": 0,
    "is_duplicate": false,
    "results": [
      {
        "document_id": "019534a1-b7be-7212-8c77-685b3edf267f",
        "status": "processing",
        "document_identifier": "OM001-Test",
        "exchange_status": "pending",
        "reporting_status": "pending",
        "error": null
      },
      {
        "document_id": "019534a2-c8cf-8323-9d88-796c4feg378g",
        "status": "processing",
        "document_identifier": "OM002-Test",
        "exchange_status": "pending",
        "reporting_status": "pending",
        "error": null
      }
    ]
  }
}

Bulk Response Fields:

Error Response

{
  "status": "failed",
  "message": "Validation failed. The document contains errors.",
  "data": {
    "document_identifier": "OM001-Test",
    "field_name": ["This field is required."],
    "receiving_party.peppol_id": ["Participant not registered on Peppol network."]
  }
}

{
  "status": "failed",
  "message": "Validation failed. The document contains errors.",
  "data": {
    "document_identifier": "OM001-Test",
    "field_name": ["This field is required."],
    "receiving_party.peppol_id": ["Participant not registered on Peppol network."]
  }
}

HTTP Status Codes:

Checking Document Status

After submitting documents, you can check their processing status.

Single Document Status

Retrieve the status of a single submitted document using the document_id returned at submission.

Endpoint: GET /v1/{participant_id}/documents/{document_id}

Example Request:

GET /v1/019534a1-b7be-7212-8c77-685aafd41e2b/documents/019534a1-b7be-7212-8c77-685b3edf267f

{
  "status": "success",
  "message": "Document retrieved successfully.",
  "data": {
    "id": "019534a1-b7be-7212-8c77-685b3edf267f",
    "status": "completed",
    "document_identifier": "OM001-Test",
    "participant_id": "019534a1-b7be-7212-8c77-685aafd41e2b",
    "direction": "outgoing",
    "sender_id": "0248:OM1234567890",
    "receiver_id": "0248:OM1345678901",
    "type": "invoice",
    "exchange_status": "delivered",
    "reporting_status": "reported",
    "reporting_reference": "OTA-2025-ABC123",
    "peppol_message_id": "msg-uuid-here",
    "envelope_id": "env-uuid-here",
    "validation": {
      "result": "valid",
      "errors": []
    }
  }
}

{
  "status": "success",
  "message": "Document retrieved successfully.",
  "data": {
    "id": "019534a1-b7be-7212-8c77-685b3edf267f",
    "status": "completed",
    "document_identifier": "OM001-Test",
    "participant_id": "019534a1-b7be-7212-8c77-685aafd41e2b",
    "direction": "outgoing",
    "sender_id": "0248:OM1234567890",
    "receiver_id": "0248:OM1345678901",
    "type": "invoice",
    "exchange_status": "delivered",
    "reporting_status": "reported",
    "reporting_reference": "OTA-2025-ABC123",
    "peppol_message_id": "msg-uuid-here",
    "envelope_id": "env-uuid-here",
    "validation": {
      "result": "valid",
      "errors": []
    }
  }
}

Overall Status Values:

Exchange Status Values:

Reporting Status Values:

List Documents

Retrieve all documents for a participant with filtering and pagination.

Endpoint: GET /v1/{participant_id}/documents

Query Parameters:

Example Request:

GET /v1/{participant_id}/documents?is_unread=true&direction=incoming&limit=50

Receiving an Invoice

You can receive invoices through two methods: Push System (webhooks) or Pull System (API polling).

Push System - Webhooks

Webhooks provide real-time notifications when you receive a new invoice. Set up a webhook endpoint to receive immediate notifications.

Webhook Management

Manage your webhook endpoints programmatically.

Register a Webhook

Add a new webhook endpoint to receive document notifications.

Endpoint: POST /v1/webhooks/subscriptions

Request Body:

{
  "name": "Production Invoice Webhook",
  "endpoint": "https://your-domain.com/webhooks/peppol/document-received",
  "event_types": ["document.received", "document.failed"],
  "participant_ids": ["019534a1-b7be-7212-8c77-685aafd41e2b"]
}

Note: participant_ids is optional — omit or leave empty to receive events for all participants.

Response:

{
  "status": "success",
  "message": "Webhook subscription created.",
  "data": {
    "uuid": "wbhk_b35f6b3145074cf9ad513610786c19d5",
    "name": "Production Invoice Webhook",
    "endpoint": "https://your-domain.com/webhooks/peppol/document-received",
    "active": true,
    "event_types": ["document.received", "document.failed"],
    "created_at": "2025-01-30T14:23:45Z",
    "secret": "R50iP7JVKOE1m8SCNFgNXV4xT"
  }
}

Important: The secret is only returned once at creation. Store it securely — use it to verify incoming webhook signatures.

Available Event Types:

Use GET /v1/webhooks/event-types to retrieve the full list of supported event types. Common events include:

• document.received - New incoming document received
• document.exchange.delivered - Document successfully delivered to recipient's access point
• document.exchange.failed - Peppol network delivery failed
• document.reporting.reported - Document successfully reported to OTA
• document.reporting.failed - OTA reporting failed
• document.completed - Document fully processed (exchange delivered + OTA reported)
• document.failed - Document failed (exchange or reporting)

List Webhooks

Get all registered webhook subscriptions.

Endpoint: GET /v1/webhooks/subscriptions

Response:

{
  "status": "success",
  "message": "Subscriptions retrieved successfully.",
  "data": [
    {
      "uuid": "wbhk_b35f6b3145074cf9ad513610786c19d5",
      "name": "Production Invoice Webhook",
      "endpoint": "https://your-domain.com/webhooks/peppol/document-received",
      "active": true,
      "event_types": ["document.received", "document.failed"],
      "created_at": "2025-01-30T14:23:45Z"
    }
  ]
}

Remove a Webhook

Delete a webhook subscription.

Endpoint: DELETE /v1/webhooks/subscriptions/{uuid}

Example Request:

DELETE /v1/webhooks/subscriptions/wbhk_b35f6b3145074cf9ad513610786c19d5

Response:

{
  "status": "success",
  "message": "Webhook subscription deleted.",
  "data": null
}

Update a Webhook

Modify an existing webhook subscription.

Endpoint: PATCH /v1/webhooks/subscriptions/{uuid}

Request Body:

{
  "endpoint": "https://new-domain.com/webhooks/peppol",
  "event_types": ["document.received"],
  "active": true
}

Response:

{
  "status": "success",
  "message": "Webhook subscription updated.",
  "data": {
    "uuid": "wbhk_b35f6b3145074cf9ad513610786c19d5",
    "endpoint": "https://new-domain.com/webhooks/peppol",
    "event_types": ["document.received"],
    "active": true,
    "updated_at": "2025-01-30T15:00:00Z"
  }
}

Rotate Signature Key

Generate a new signing secret for a webhook subscription.

Endpoint: POST /v1/webhooks/subscriptions/{uuid}/signature-key

Response:

{
  "status": "success",
  "message": "Signature key rotated.",
  "data": {
    "secret": "NewSecret123XYZ"
  }
}

View Delivery History

Inspect recent delivery attempts for a webhook subscription.

Endpoint: GET /v1/webhooks/subscriptions/{uuid}/deliveries

Document Received Event

When a new invoice arrives, you'll receive a webhook payload:

{
  "event_type": "document.received",
  "subscription_uuid": "wbhk_b35f6b3145074cf9ad513610786c19d5",
  "timestamp": "2025-01-30T14:23:45Z",
  "data": {
    "document_id": "019534a1-b7be-7212-8c77-685b3edf267f",
    "participant_id": "019534a1-b7be-7212-8c77-685aafd41e2b",
    "direction": "incoming",
    "type": "invoice",
    "status": "processing",
    "exchange_status": "delivered",
    "reporting_status": "pending",
    "sender_id": "0248:OM1345678901",
    "receiver_id": "0248:OM1234567890",
    "document_identifier": "OM001-Test"
  }
}

Webhook Response:

Your endpoint should return a 200 OK status to acknowledge receipt:

{
  "acknowledged": true,
  "processed": true
}

Webhook Security:

All webhook requests include a signature header for verification:

X-Flick-Signature: sha256=abc123...
X-Flick-Timestamp: 2025-01-30T14:23:45Z

Verify Signature (Example in Node.js):

const crypto = require('crypto');
 
function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = 'sha256=' + hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

Best Practices:

• Respond quickly (within 5 seconds) to avoid timeouts
• Process the document asynchronously after acknowledging
• Implement retry logic for failed processing
• Always validate webhook signatures for security
• Store raw webhook payloads for debugging
• Use HTTPS endpoints only
• Handle duplicate webhook deliveries idempotently
• Monitor webhook delivery failures in your logs

Pull System

If you prefer polling over webhooks, use the Pull System to retrieve documents at your own pace.

Get Document

Retrieve the full invoice document and its parsed content by document ID.

Endpoint: GET /v1/{participant_id}/documents/{document_id}