Connect your own system

Sending an invoice or a credit note

One call creates the document, validates it and queues it for the network. documentType decides which kind it is: 380 a commercial invoice, 480 an invoice out of scope of tax, 381 a credit note, 81 a credit note for goods or services.

What happens, in order

1. 1.The document is created and validated as one operation. If validation fails, nothing is created at all — a 422 comes back listing every reason.
2. 2.Attachments are stored and scanned before validation completes.
3. 3.The send to the Access Point then happens in the background, which is what submissionQueued: true is telling you.

POST /api/public/v1/outbound
X-Api-Key: tvk_live_a1b2c3d4_<secret>
Content-Type: application/json

{
  "invoiceNo": "INV-2026-00125",
  "documentType": "380",
  "transactionType": "00000000",
  "invoiceDate": "03/14/2026",
  "dueDate": "04/13/2026",
  "currency": "AED",
  "buyer": {
    "name": "Gulf Trading LLC",
    "taxId": "100123456700003",
    "email": "ap@gulftrading.ae",
    "countryCode": "AE",
    "city": "Dubai",
    "addressLine1": "Office 1204, Business Bay"
  },
  "lines": [
    {
      "lineNo": 1,
      "description": "Consulting services, March 2026",
      "quantity": 10,
      "unitPrice": 450.00,
      "vatCategory": "S",
      "vatRate": 5
    }
  ],
  "attachments": [
    { "fileName": "timesheet.pdf", "contentType": "application/pdf", "content": "<base64>" }
  ]
}

HTTP/1.1 202 Accepted

{
  "success": true,
  "alreadyExisted": false,
  "submissionQueued": true,
  "header": {
    "id": "7c9f1a44-55e2-4a1d-9d0b-2f0e8c6b31aa",
    "invoiceNo": "INV-2026-00125",
    "status": "Submitted"
  }
}

HTTP/1.1 422 Unprocessable Entity

{
  "success": false,
  "message": "The document failed validation.",
  "validations": [
    { "field": "buyer.taxId", "message": "A 15-digit UAE TRN is required for a 380 document." },
    { "field": "lines[0].vatRate", "message": "vatRate must be 5 when vatCategory is S." }
  ]
}

Receiving what suppliers send you

Documents that arrive for you over the network are pushed to a URL you provide. You do not poll for them.

What to set up

1. 1.An HTTPS endpoint of your own that accepts a POST and answers 2xx. Plain http is refused.
2. 2.In the portal: Company Information, then API credentials, then the Purchase invoice webhook card. Enter the delivery URL and enable delivery.
3. 3.For any ERP other than Business Central, choose Other ERP and generate a webhook secret. It is shown once.
4. 4.Press Send test event to check it, and read the Delivery log for the outcome of every call, real or test.

The events

POST /your/webhook/endpoint
X-TV-Event: purchase_document.received
X-TV-Timestamp: 1773480764
X-TV-Signature: v1=4f1c0b7e…

{
  "event": "purchase_document.received",
  "purchaseDocumentId": "b17d3e90-6a21-4c88-9f3e-77aa1c2d5e04",
  "invoiceNo": "SUP-9921",
  "supplierName": "Emirates Stationery LLC",
  "receivedAt": "2026-03-14T09:14:02Z"
}

Checking a call really came from the portal

Signed calls carry X-TV-Timestamp and X-TV-Signature. Build the string {timestamp}.{raw body}, take HMAC-SHA256 of it with your webhook secret, write it as lowercase hex, and compare it in constant time with the value after v1=. Reject anything more than 300 seconds old, which stops a captured call being replayed.

import crypto from "node:crypto";

export function verify(rawBody: string, headers: Headers, secret: string) {
  const timestamp = headers.get("X-TV-Timestamp") ?? "";
  const signature = (headers.get("X-TV-Signature") ?? "").replace(/^v1=/, "");

  // Outside five minutes, treat it as a replay of a captured call.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(signature, "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Answering, and retries

• Answer 2xx as soon as you have the event and do the work afterwards. A slow endpoint holds up delivery.
• On 5xx, 429 or no connection the portal retries: three attempts in all, roughly five then ten seconds apart.
• Any other 4xx is read as a refusal and is not retried.
• After the last attempt nothing is sent again. The failure stays in the Delivery log, and the document is stored in the portal either way.
• The same event can reach you more than once. Key on purchaseDocumentId and make your handling safe to repeat.

Fetching the document

One call returns everything: the header, every line, allowances and charges, attachments and the original UBL exactly as it was delivered. Pass includeXml=false or includeAttachmentContent=false to leave the heavy parts out.

GET /api/public/v1/purchase-documents/b17d3e90-6a21-4c88-9f3e-77aa1c2d5e04?includeXml=false
X-Api-Key: tvk_live_a1b2c3d4_<secret>

A 404 means the id does not exist — or belongs to a company that is not the one your key represents.

Getting a key, and getting help

API keys are generated by a company's own administrator from Company Information in the portal. For the production host, the full field reference, or anything the guide above does not answer, talk to us.