# Oman: request and response examples

Send an Omani tax invoice and credit note to the sandbox and read each response up to the final status. You need a sandbox API key and an Omani company onboarded with its invoice source.

> **Before you start**
>
> You need a [sandbox API key](https://docs.complyance.io/api-reference/authentication/) and a company [onboarded in Oman](https://docs.complyance.io/countries/om/onboarding/) with its source name and version. All names, VATINs, participant IDs, UUIDs and amounts below are made up. Replace them with your company’s and your buyer’s real values.

## Save the request

Save this body as `oman-invoice.json`. It is a standard tax invoice in Omani rials (OMR) for two standard-rated service lines at 5% VAT. It passes the PINT OM rules for a tax invoice as written.

```json title="oman-invoice.json"
{
  "country": "OM",
  "environment": "sandbox",
  "purpose": "invoicing",
  "source": "acme-erp:1.0.0",
  "documentType": { "base": "tax_invoice", "modifiers": [] },
  "payload": {
    "header": {
      "documentType": { "base": "tax_invoice", "modifiers": [] },
      "documentNumber": "INV-2026-0142",
      "uuid": "e2dcb6e9-6538-53e9-b13b-1806f388e14a",
      "issueDate": "2026-09-18",
      "issueTime": "10:42:00",
      "dueDate": "2026-10-18",
      "currency": "OMR"
    },
    "parties": {
      "seller": {
        "name": "Sohar Trading LLC",
        "address": {
          "addressLine1": "Way 3021",
          "addressLine2": "Building 14",
          "addressLine3": "Office 22",
          "city": "Muscat",
          "postalCode": "112",
          "country": "OM"
        },
        "contact": { "phone": "+968 2412 3456" },
        "taxIds": [{ "type": "VAT", "value": "OM1100012345" }],
        "registrationNumbers": [{ "type": "CR", "value": "1234567" }],
        "peppolId": "OM1100012345"
      },
      "buyer": {
        "name": "Nizwa Retail SAOC",
        "address": {
          "addressLine1": "Way 1507",
          "addressLine2": "Building 3",
          "addressLine3": "Floor 2",
          "city": "Nizwa",
          "postalCode": "611",
          "country": "OM"
        },
        "taxIds": [{ "type": "VAT", "value": "OM1100054321" }],
        "registrationNumbers": [{ "type": "CR", "value": "1234589" }],
        "peppolId": "OM1100054321"
      }
    },
    "lineItems": [
      {
        "id": "1",
        "name": "Software consulting",
        "quantity": 10,
        "unitCode": "HUR",
        "price": { "amount": 45, "baseQuantity": 1 },
        "netPrice": 45,
        "lineTaxableValue": 450,
        "taxCategory": "S",
        "taxRate": 5,
        "taxAmount": 22.5,
        "lineTotal": 472.5,
        "extensions": {
          "om_itemType": "S",
          "om_industrialClassifications": [{ "code": "620201" }],
          "om_serviceTypes": [{ "code": "72000000" }]
        }
      },
      {
        "id": "2",
        "name": "Annual support plan",
        "quantity": 1,
        "unitCode": "C62",
        "price": { "amount": 120, "baseQuantity": 1 },
        "netPrice": 120,
        "lineTaxableValue": 120,
        "taxCategory": "S",
        "taxRate": 5,
        "taxAmount": 6,
        "lineTotal": 126,
        "extensions": {
          "om_itemType": "S",
          "om_industrialClassifications": [{ "code": "620201" }],
          "om_serviceTypes": [{ "code": "72000000" }]
        }
      }
    ],
    "taxTotals": [
      {
        "taxAmount": 28.5,
        "taxSubtotals": [
          {
            "taxCategory": "S",
            "percent": 5,
            "taxableAmount": 570,
            "taxAmount": 28.5
          }
        ]
      }
    ],
    "totals": {
      "totalLineTaxableAmount": 570,
      "totalAmountExcludingTax": 570,
      "totalTaxAmount": 28.5,
      "totalAmountIncludingTax": 598.5,
      "amountDue": 598.5
    },
    "extensions": {
      "peppol_seller_peppolIdScheme": "0248",
      "peppol_buyer_peppolIdScheme": "0248"
    }
  }
}
```

The envelope’s `documentType` decides which PINT OM rules apply. Complyance copies it into `payload.header.documentType`, replacing any value there.

Before you send it, change these values:

- **`source`**: your onboarded `name:version`.
- **`documentNumber`**: a number you have not sent before.
- **`uuid`**: a new UUID version 5 for each invoice. PINT OM accepts no other UUID version; see [IBR-002-OM](https://docs.peppol.eu/poac/om/pint-om/trn-invoice/rule/IBR-002-OM/).
- **`issueDate`** and **`issueTime`**: the issue date and time. The date cannot be in the future in Oman’s time zone.
- **Seller and buyer**: names, addresses, phone, VATINs and commercial registration numbers. For a buyer registered on Peppol with its VATIN, `peppolId` is the VATIN and the scheme in `extensions.peppol_buyer_peppolIdScheme` is `0248`.

Each line carries the item type in `extensions.om_itemType` (`S` for services, `G` for goods), an ISIC industrial classification code and a service type code. Choose codes from the [PINT OM code lists](https://docs.peppol.eu/poac/om/pint-om/trn-invoice/codelist/). A goods line also needs an HS code in `commodityClassification`, with `scheme` set to `HS`.

The `payload` uses GETS field names. If your source’s mapping expects other field names, send the same values under those names. For other document types and their fields, see the [Oman field reference](https://docs.complyance.io/countries/om/fields/).

## Send the request

Sandbox and production use the same host, `https://prod.gets.complyance.io`. The `"environment": "sandbox"` field in the request body is what sends this invoice to sandbox.

```bash title="Submit an Omani invoice in sandbox"
curl --request POST 'https://prod.gets.complyance.io/api/v3/unify' \
  --header "Authorization: Bearer ${COMPLYANCE_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'new-api: true' \
  --data @oman-invoice.json
```

## Read the response

HTTP `200` means the invoice passed validation and was stored. This response is illustrative: the real `Base64XML` holds the generated PINT OM invoice, not this short fragment.

```json title="Validated invoice — HTTP 200"
{
  "documentId": "01K5EXAMPLE00000000000142",
  "documentNumber": "INV-2026-0142",
  "message": "Your invoice was validated and is ready for submission.",
  "Base64XML": "PEludm9pY2U+PElEPklOVi0yMDI2LTAxNDI8L0lEPjwvSW52b2ljZT4="
}
```

If the request returns HTTP `422`, read every entry in `errors`. This one is the response to the same request without the seller’s phone number:

```json title="Missing seller phone — HTTP 422"
{
  "documentId": "01K5EXAMPLE00000000000143",
  "documentNumber": "INV-2026-0142",
  "message": "Your invoice could not be validated. Review the errors and try again.",
  "validationStage": "gets",
  "errors": [
    {
      "code": "IBR-011-OM",
      "getsPath": "parties.seller.contact.phone",
      "payloadPath": "parties.seller.contact.phone",
      "message": "[IBR-011-OM] - In Seller Contact (IBG-06), Seller contact telephone number (IBT-042) must be provided.",
      "severity": "error",
      "ruleSet": "om:tax_invoice"
    }
  ]
}
```

Correct the field named by `getsPath`, then send the request again. The `code` is the PINT OM rule; [Oman validation rules](https://docs.complyance.io/countries/om/validation-rules/) lists the common ones. See [Unify errors](https://docs.complyance.io/api-reference/unify/errors/) for other statuses.

## Check the final status

A `200` is not a delivery receipt. Follow the document by `documentId`, as described in [Submit and retrieve](https://docs.complyance.io/api-reference/unify/submit-and-retrieve/#follow-the-document), until `isTerminal` is `true`. This response is shortened: `government`, which holds the Peppol exchange’s answer, and `artifacts` are left out.

```json title="Accepted by the buyer's access point — HTTP 200"
{
  "success": true,
  "data": {
    "documentId": "01K5EXAMPLE00000000000142",
    "documentNumber": "INV-2026-0142",
    "country": "OM",
    "environment": "sandbox",
    "state": "final_valid",
    "isTerminal": true,
    "lastUpdatedAt": "2026-09-18T06:44:20.000Z",
    "errors": [],
    "validationResults": {
      "status": "Valid",
      "validationSteps": [
        { "name": "Validation Passed", "status": "Valid", "error": null },
        { "name": "Queue Admitted", "status": "Valid", "error": null },
        {
          "name": "Delivery Processing Started",
          "status": "Valid",
          "error": null
        },
        { "name": "Final Valid", "status": "Valid", "error": null }
      ]
    }
  }
}
```

`final_valid` means the buyer’s Peppol access point accepted the e-invoice. Oman is available in sandbox only, and the sandbox does not report invoices to the OTA.

## Credit note

A credit note refers to the original invoice in a `supportingDocuments` entry with `documentType` `precedingInvoiceReference`: the invoice’s number in `id`, its `issueDate`, its UUID in `extensions.om_uuid` and a reason in `extensions.om_reasonCode` (`CAN`, `VAT`, `VAL`, `QTY` or `OTH`). See [IBR-023-OM](https://docs.peppol.eu/poac/om/pint-om/trn-invoice/rule/IBR-023-OM/). This one cancels the support line of the invoice above.

```json title="oman-credit-note.json"
{
  "country": "OM",
  "environment": "sandbox",
  "purpose": "invoicing",
  "source": "acme-erp:1.0.0",
  "documentType": { "base": "credit_note", "modifiers": [] },
  "payload": {
    "header": {
      "documentType": { "base": "credit_note", "modifiers": [] },
      "documentNumber": "CN-2026-0037",
      "uuid": "0b8c1f5e-7a1d-5c2e-9f3a-6d4b2e8a1c07",
      "issueDate": "2026-09-25",
      "issueTime": "09:05:00",
      "currency": "OMR"
    },
    "parties": {
      "seller": {
        "name": "Sohar Trading LLC",
        "address": {
          "addressLine1": "Way 3021",
          "addressLine2": "Building 14",
          "addressLine3": "Office 22",
          "city": "Muscat",
          "postalCode": "112",
          "country": "OM"
        },
        "contact": { "phone": "+968 2412 3456" },
        "taxIds": [{ "type": "VAT", "value": "OM1100012345" }],
        "registrationNumbers": [{ "type": "CR", "value": "1234567" }],
        "peppolId": "OM1100012345"
      },
      "buyer": {
        "name": "Nizwa Retail SAOC",
        "address": {
          "addressLine1": "Way 1507",
          "addressLine2": "Building 3",
          "addressLine3": "Floor 2",
          "city": "Nizwa",
          "postalCode": "611",
          "country": "OM"
        },
        "taxIds": [{ "type": "VAT", "value": "OM1100054321" }],
        "registrationNumbers": [{ "type": "CR", "value": "1234589" }],
        "peppolId": "OM1100054321"
      }
    },
    "lineItems": [
      {
        "id": "2",
        "name": "Annual support plan",
        "quantity": 1,
        "unitCode": "C62",
        "price": { "amount": 120, "baseQuantity": 1 },
        "netPrice": 120,
        "lineTaxableValue": 120,
        "taxCategory": "S",
        "taxRate": 5,
        "taxAmount": 6,
        "lineTotal": 126,
        "extensions": {
          "om_itemType": "S",
          "om_industrialClassifications": [{ "code": "620201" }],
          "om_serviceTypes": [{ "code": "72000000" }]
        }
      }
    ],
    "taxTotals": [
      {
        "taxAmount": 6,
        "taxSubtotals": [
          {
            "taxCategory": "S",
            "percent": 5,
            "taxableAmount": 120,
            "taxAmount": 6
          }
        ]
      }
    ],
    "totals": {
      "totalLineTaxableAmount": 120,
      "totalAmountExcludingTax": 120,
      "totalTaxAmount": 6,
      "totalAmountIncludingTax": 126,
      "amountDue": 126
    },
    "extensions": {
      "peppol_seller_peppolIdScheme": "0248",
      "peppol_buyer_peppolIdScheme": "0248"
    },
    "supportingDocuments": [
      {
        "id": "INV-2026-0142",
        "documentType": "precedingInvoiceReference",
        "issueDate": "2026-09-18",
        "extensions": {
          "om_uuid": "e2dcb6e9-6538-53e9-b13b-1806f388e14a",
          "om_reasonCode": "CAN"
        }
      }
    ]
  }
}
```

This request passes Unify’s validation as written. Send it and follow it the same way as the invoice.

Source: https://docs.complyance.io/countries/om/examples/