Skip to content

Developers

Build with InvoTax.

Connect any finance system in one of three ways — no rip-and-replace. Pick what fits each platform; mix them across a group.

  • Embed snippet

    Paste one script tag into your financials page, map the common fields, and records flow to InvoTax. No developers needed.

  • Webhook

    Register the InvoTax endpoint in your platform and subscribe the events. Every new record posts itself automatically.

  • REST API

    Integrate directly against documented endpoints with a bearer key — push records, pull tax summaries and reports.

Embed snippet

<script src="https://cdn.invotax.qa/embed.js"
  data-client="acme-trading"
  data-key="pk_test_••••"
  data-system="odoo"></script>

REST API

curl -X POST https://api-invotax.idealsolutions-apps.com/v1/documents \
  -H "Authorization: Bearer sk_live_••••" \
  -H "Content-Type: application/json" \
  -d '{"type":"INVOICE","issuedAt":"2027-01-14T09:00:00+03:00","deviceId":"dev_••••",
       "buyerName":{"en":"Acme","ar":"Acme"},
       "lines":[{"description":"Steel","quantity":"3","unitPrice":"7800.00"}]}'

Core endpoints

POST/v1/documentsCreate an invoice, credit/debit note, or simplified document
POST/v1/integrations/ingestInbound record from a connected system
GET/v1/tax/summaryComputed GTA tax for a period
GET/v1/reports/categoriesCategorized totals across systems

Authentication

Integration calls use a bearer key (sk_test_… in the sandbox, sk_live_… in production). Portal sessions use an HttpOnly cookie. Never expose a secret key in client-side code — the embed snippet uses a publishable key instead.

Verifying webhook signatures

Every webhook delivery carries an X-InvoTax-Signature header so your endpoint can confirm it came from InvoTax and was not altered in transit. The scheme is HMAC-based but not identical to Stripe or most providers — read the key derivation below before wiring a verifier.

Header
X-InvoTax-Signature: t=<unix-seconds>,v1=<hex HMAC-SHA256>. t is the Unix timestamp, in seconds, when the signature was generated; v1 is the hex-encoded HMAC-SHA256 signature.
Signed content
The signature covers the UTF-8 string "<t>.<raw body>" — the timestamp from the header, a literal period, then the exact raw bytes of the request body as received. Verify against those raw bytes; never re-serialize the parsed JSON first.
Signing key — unlike Stripe
InvoTax never stores your webhook secret in the clear, so unlike Stripe and most providers, deliveries are not signed with the raw secret itself. The key is SHA-256(secret) — the 32-byte SHA-256 digest of the whsec_... secret you were shown once at creation or rotation. Hash your secret before using it as the HMAC key, or verification will fail silently.
Replay and timing safety
Reject any delivery whose t is more than 5 minutes from your current clock, and compare your computed signature to v1 with a constant-time comparison — never a plain string or === check.
Payload envelope
Every delivery posts a JSON body shaped { id, event, occurredAt, data }. event is one of invoice.cleared, invoice.rejected, reporting.deadline, or invoice.submission_result. The first three are only sent for live-environment documents, to active endpoints subscribed to that event; invoice.submission_result carries the GTA result of an invoice submitted through the outsource integration API, in sandbox and live.

Node.js

const crypto = require('crypto');

// rawBody must be the exact bytes received (e.g. a Buffer from your raw
// body middleware) -- never the re-serialized, parsed JSON.
function verifyInvoTaxSignature(rawBody, signatureHeader, secret) {
  const signingKey = crypto.createHash('sha256').update(secret, 'utf8').digest();

  const parts = Object.fromEntries(signatureHeader.split(',').map((p) => p.split('=')));
  const { t, v1 } = parts;

  const toleranceSeconds = 5 * 60;
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > toleranceSeconds) {
    throw new Error('signature timestamp outside tolerance');
  }

  const signedContent = Buffer.concat([Buffer.from(`${t}.`, 'utf8'), rawBody]);
  const expected = crypto.createHmac('sha256', signingKey).update(signedContent).digest('hex');

  const expectedBuf = Buffer.from(expected, 'utf8');
  const receivedBuf = Buffer.from(v1, 'utf8');
  const valid =
    expectedBuf.length === receivedBuf.length && crypto.timingSafeEqual(expectedBuf, receivedBuf);

  if (!valid) throw new Error('signature mismatch');
}

Python

import hashlib
import hmac
import time

# raw_body must be the exact bytes received on the wire -- never
# json.dumps(parsed_body).encode(), which can reorder or reformat.
def verify_invotax_signature(raw_body: bytes, signature_header: str, secret: str) -> None:
    signing_key = hashlib.sha256(secret.encode("utf-8")).digest()

    parts = dict(p.split("=", 1) for p in signature_header.split(","))
    t, v1 = parts["t"], parts["v1"]

    tolerance_seconds = 5 * 60
    if abs(int(time.time()) - int(t)) > tolerance_seconds:
        raise ValueError("signature timestamp outside tolerance")

    signed_content = f"{t}.".encode("utf-8") + raw_body
    expected = hmac.new(signing_key, signed_content, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected, v1):
        raise ValueError("signature mismatch")

Base URL: https://api-invotax.idealsolutions-apps.com/v1 (sandbox: sandbox-api-invotax…). Figures and keys shown are illustrative.