Developer integration

Connect your ERP to Oman e-invoicing.

Use the Faturathi API to validate, submit and monitor e-invoices from your ERP, billing or POS system.

View quick start Request integration access

Public guide

A safe overview for evaluation and planning

The examples below intentionally show only a representative subset of fields. The complete production schema, conditional rules, mappings and certification material are provided securely during onboarding.

Downloadable documentation

Technical and API reference PDFs

Download the current technical overview or the expanded API documentation for offline review.

Technical DocumentationFaturathi Technical Details V1.01 · PDF API DocumentationFaturathi API Documentation V1.0.1 · PDF

Quick start

A straightforward integration flow

Keep credentials on your server and exchange JSON over HTTPS.

Authenticate

Obtain secure credentials for your approved environment.

Validate

Check representative invoice data before submission.

Submit

Send the invoice and retain the returned Faturathi ID.

Track

Read processing status and handle any validation response.

Supported scenarios

Invoices and adjustment documents

Faturathi supports the common Oman e-invoicing document flows below. The complete conditional requirements are supplied with your approved integration profile.

380

B2B

Standard tax invoice

For supplies to a registered business. Include the buyer’s registered identity and electronic address when the document is routed through PEPPOL.

380

B2C

Simplified tax invoice

For a consumer sale. Buyer tax and PEPPOL identifiers are generally not supplied; the applicable transaction profile is confirmed during onboarding.

381

Adjustment

Credit note

Reduces the value of an earlier invoice, for example after a return or price correction. Reference the preceding invoice number and date.

383

Adjustment

Debit note

Increases the value of an earlier invoice, for example for an additional charge. Reference the preceding invoice number and date.

389

Self-billing

Self-billed invoice

The buyer creates the invoice on behalf of the supplier. Supplier information remains in seller_details; the issuing buyer is represented in buyer_details.

261

Self-billing

Self-billed credit note

Corrects a previously issued self-billed invoice. Use the self-billing specification and reference the preceding self-billed document.

Scenario	Buyer information	Original invoice reference	Typical use
B2B invoice	Business name, VATIN and electronic address as applicable	Not normally required	Business-to-business sale
B2C invoice	Minimal consumer information	Not normally required	Retail or consumer sale
Credit note	Match the relevant invoice parties	Required for the corrected invoice	Reduce an invoiced amount
Debit note	Match the relevant invoice parties	Required for the adjusted invoice	Increase an invoiced amount
Self-billed invoice	Supplier as seller; issuing customer as buyer	Not normally required	Buyer invoices on the supplier’s behalf
Self-billed credit note	Match the self-billing parties	Required for the corrected self-billed invoice	Reduce a self-billed amount

Document code alone does not determine every rule. Transaction profile, party type, tax treatment and routing determine the final required fields.

Endpoint overview

Core operations

Your onboarding pack supplies the approved base URL and credentials for each environment.

POST/api/v1/invoices/validate/

Validate invoice data.

POST/api/v1/invoices/

Submit an invoice.

GET/api/v1/invoices/{id}/

Read processing status.

Authentication

Send both credentials with every request

Credentials are issued for an approved environment. Keep them in server-side secrets and use placeholders in source code, documentation and Postman exports.

Header 01Authorization: Bearer <YOUR_BEARER_TOKEN>

Identifies the authenticated user or integration session.

Header 02X-API-KEY: <YOUR_API_KEY>

Identifies the authorised Faturathi API client.

Header 03Content-Type: application/json

Send and receive JSON for the operations shown here.

Validate a B2B invoicecURL

curl --request POST \
  "https://uat-api.faturathi.net/api/v1/invoices/validate/" \
  --header "Authorization: Bearer <YOUR_BEARER_TOKEN>" \
  --header "X-API-KEY: <YOUR_API_KEY>" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "header": {
      "invoice_number": "INV-2026-0001",
      "invoice_type_code": "380",
      "issue_date": "2026-10-01",
      "currency_code": "OMR"
    },
    "seller_details": {
      "name": "Example Supplier LLC",
      "vatin": "OM1100123456"
    },
    "buyer_details": {
      "name": "Example Buyer LLC",
      "vatin": "OM1100654321",
      "electronic_address": "OM1100654321"
    },
    "lines": [{
      "line_id": "1",
      "quantity": "1.000",
      "unit_code": "EA",
      "item_name": "Integration service",
      "net_price": "100.000",
      "vat_rate": "5.00"
    }]
  }'

Illustrative request

Selected example fields

This sample demonstrates the general JSON structure only. It is not a complete production payload and must not be treated as the full field specification.

Amounts are strings with controlled decimal precision.
Dates use the ISO YYYY-MM-DD format.
Country, currency and unit values use standard codes.

Example invoiceJSON

{
  "header": {
    "invoice_number": "INV-2026-0001",
    "invoice_type_code": "380",
    "issue_date": "2026-10-01",
    "currency_code": "OMR"
  },
  "seller_details": {
    "name": "Example Supplier LLC",
    "vatin": "OM1100123456"
  },
  "buyer_details": {
    "name": "Example Buyer LLC",
    "electronic_address": "OM1100654321"
  },
  "lines": [{
    "line_id": "1",
    "quantity": "1.000",
    "unit_code": "EA",
    "item_name": "Integration service",
    "net_price": "100.000",
    "vat_rate": "5.00"
  }]
}

Response handling

Store the Faturathi ID and track status

A successful submission returns an identifier for subsequent status checks. Typical lifecycle states include processing, completed, rejected and failed.

Accepted response202

{
  "id": "inv_example_01",
  "invoice_number": "INV-2026-0001",
  "status": "processing"
}

Credit and debit notes

Reference the document being adjusted

Use the same document structure, change the invoice type code and include a reference to the original invoice. The production schema contains additional reason, tax and total requirements.

Credit note381

{
  "header": {
    "invoice_number": "CN-2026-0001",
    "invoice_type_code": "381",
    "preceding_invoice_number": "INV-2026-0001",
    "preceding_invoice_date": "2026-10-01"
  }
}

Debit note383

{
  "header": {
    "invoice_number": "DN-2026-0001",
    "invoice_type_code": "383",
    "preceding_invoice_number": "INV-2026-0001",
    "preceding_invoice_date": "2026-10-01"
  }
}

Self-billing

The buyer issues the document for the supplier

Self-billing changes who creates the invoice, not the commercial roles. The supplier remains the seller and the customer remains the buyer. Both parties must use the approved self-billing process and identifiers supplied during onboarding.

Invoice UUIDProvide a deterministic UUID version 5 in header.invoice_uuid.

Self-billing profileUse the self-billing specification identifier and business process issued for your integration.

CorrectionsA self-billed credit note references the original self-billed invoice number and date.

Selected self-billed fields389

{
  "header": {
    "invoice_number": "SB-2026-0001",
    "invoice_type_code": "389",
    "invoice_uuid": "2ed6657d-e927-568b-95e1-2665a8aea6a2",
    "specification_identifier": "urn:peppol:pint:selfbilling-1@om-1",
    "business_process": "urn:peppol:bis:selfbilling"
  },
  "seller_details": {
    "name": "Example Supplier LLC",
    "vatin": "OM1100222333"
  },
  "buyer_details": {
    "name": "Example Buyer LLC",
    "vatin": "OM1100123456"
  }
}

HTTP responses

Handle immediate API results separately from network acknowledgements

HTTP status reports what Faturathi did with the API request. PEPPOL MLS or MLR information can arrive later and is exposed through document tracking.

HTTP	Meaning	Recommended client action
200	Validation completed successfully, or a requested document/status was returned.	Continue to submission or process the returned resource.
202	Document accepted for asynchronous processing.	Store the Faturathi ID and invoice UUID, then poll the tracking endpoint.
400	Malformed JSON or an invalid request envelope.	Correct the request structure before retrying.
401	Bearer token is missing, invalid or expired.	Refresh or replace the token; do not retry unchanged credentials.
403	API key, environment or permission does not authorise the operation.	Check the API key, environment and assigned access.
409	Duplicate invoice number, UUID or conflicting document state.	Retrieve the existing document before deciding whether to resubmit.
422	PINT-OM, schema or business-rule validation failed.	Read the rule code and field path, correct the source document and validate again.
429	Request rate limit exceeded.	Retry with exponential backoff and jitter.
5xx	Temporary Faturathi or upstream service failure.	Retry safely using idempotency controls; escalate persistent failures.

A successful HTTP response confirms API handling only. It does not by itself confirm final PEPPOL delivery, receiver validation or OTA reporting.

Accepted for processing202

{
  "id": "inv_example_01",
  "invoice_number": "INV-2026-0001",
  "invoice_uuid": "2ed6657d-e927-568b-95e1-2665a8aea6a2",
  "status": "processing"
}

PINT-OM validation error422

{
  "status": "validation_failed",
  "errors": [{
    "code": "IBR-002-OM",
    "path": "header.invoice_uuid",
    "message": "Invoice UUID must be version 5."
  }]
}

PEPPOL acknowledgements

Track MLS and receiver validation after submission

Faturathi correlates later network responses with the submitted document and makes the latest delivery state available through tracking.

Delivery confirmed

MLS indicates that delivery to the receiving service provider’s end user succeeded with confirmation.

Delivery performed

MLS indicates that delivery was performed without receiver confirmation, such as forwarding through another channel.

Message rejected

MLS indicates rejection. The response contains a description and issue details to support correction and resubmission.

MLS is not the same as MLR

MLS reports service-provider processing and delivery. A Message Level Response (MLR) reports whether the receiver accepted, rejected or merely acknowledged the document after content validation.

The MLS document reference is the original PEPPOL envelope instance identifier, which is typically a UUID. It is separate from the PINT-OM invoice UUID, which must be UUID version 5.

Illustrative tracking resultMLS

{
  "id": "inv_example_01",
  "status": "mls_acknowledged",
  "invoice_uuid": "2ed6657d-e927-568b-95e1-2665a8aea6a2",
  "mls": {
    "response_code": "AP",
    "document_reference": "90f14eff-3705-4869-ad3c-caae270a234e",
    "description": "Delivery confirmed"
  }
}

Ready to integrate?

Get the complete specification securely.

Our integration team will provide the production contract, validation rules and onboarding support after access approval.

Request API access