OmniTax API

A small REST API over the same engine the application uses. Every figure is computed server-side, and every response is the same shape the application receives.

Authentication

Send the key issued to you as a bearer token. A key belongs to exactly one client company and cannot reach another, whatever it asks for.

curl https://omnitax-uae-tax-suite.netlify.app/api/invoices \
  -H "Authorization: Bearer mzn_your_key_here"

Keys are stored only as hashes and are shown once, when created. If a key is lost, revoke it and issue another. A revoked key stops working immediately.

Scopes

Scope	Grants
read:invoices	Read sales invoices, credit notes and their lines
write:invoices	Issue sales invoices
read:purchases	Read supplier bills
write:purchases	Record supplier bills
read:customers	Read customers
write:customers	Create customers
read:reports	Read the VAT summary and report figures

Endpoints

Method	Path	Scope	Description
GET	/api/bootstrap	read:reports	The company the key belongs to, and today's date as the server sees it.
GET	/api/invoices	read:invoices	Sales invoices and credit notes, newest first. Optional filters: date_from, date_to (YYYY-MM-DD, on the issue date), type (standard, simplified, credit_note), status (issued, cancelled), payment (unpaid, part_paid, paid), customer (id), currency, q (number or customer), min, max (AED).
GET	/api/invoices/{id}	read:invoices	One invoice with its lines, payments, credit notes and outstanding balance.
POST	/api/invoices/issue	write:invoices	Issue a tax invoice. Body: customer_id, issue_date, date_of_supply, currency, lines[] (description, quantity, unit_price, discount_amount, vat_treatment). Returns the numbered invoice or 422 with structured violations.
GET	/api/invoices/{id}/print	read:invoices	The statutory invoice as printable HTML.
GET	/api/customers	read:customers	Customers of the company.
POST	/api/customers	write:customers	Create a customer. Body: name, trn, address, emirate, country, is_b2c.
GET	/api/purchases	read:purchases	Supplier bills and debit notes, newest first, up to 500. Optional filters: date_from, date_to, account (id), vat (standard_5, zero_rated, exempt, reverse_charge, out_of_scope), recoverable (yes, no), payment, kind (bill, debit_note, voided), q, min, max.
POST	/api/purchases	write:purchases	Record a supplier bill. Body: supplier_name, supplier_trn, supplier_invoice_no, invoice_date, account_id, vat_treatment, net_amount.
GET	/api/reports/summary	read:reports	Output VAT, input VAT and the net position for a period. Query: date_from, date_to.

Issuing an invoice

curl -X POST https://omnitax-uae-tax-suite.netlify.app/api/invoices/issue \
  -H "Authorization: Bearer mzn_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": 1,
    "issue_date": "2026-09-04",
    "date_of_supply": "2026-09-04",
    "currency": "AED",
    "lines": [
      {"description": "Consulting", "quantity": 2, "unit_price": 1500,
       "discount_amount": 0, "vat_treatment": "standard_5"}
    ]
  }'

VAT treatments are standard_5, zero_rated, exempt, reverse_charge and out_of_scope.

Errors

A request that fails validation returns 422 with structured violations - the same objects the application renders, so you can show them to your own users verbatim:

{"violations":[{"code":"CUSTOMER_TRN_INVALID","field":"customer.trn",
  "message":"Recipient TRN (15 digits) is mandatory on a full Tax Invoice…","severity":"error"}]}

401 means the key is missing, wrong or revoked. 403 means the key is valid but lacks the scope, or is reaching for another company's data. Rate limits are not applied yet; keep requests reasonable and expect that to change.

Notes

Dates are YYYY-MM-DD in UTC. Money is a number, already rounded half-up to two decimals. Invoice numbering is gapless per company, so a request that fails validation consumes no number. Credit notes appear in /api/invoices with negative amounts and a related_invoice_id.

Generated by OmniTax - UAE Tax Suite. Figures require review by a licensed tax agent.