API Documentation

Authentication

Send a scoped bearer key in the Authorization header. Choose the authority with the X-Tax-Authority header and always include an Idempotency-Key.

POST /api/v1/invoices

curl -X POST https://taxbridge.themetasum.com/api/v1/invoices \
  -H "Authorization: Bearer tbk_test_9f3a21c7b4d6e8f0_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b6d1c4e-7f9a-4a51-8d3c-2e5f7a91b204" \
  -H "X-Tax-Authority: PRA" \
  -d '{
    "invoiceNumber": "INV-10001",
    "invoiceDate": "2026-08-10T10:30:00",
    "invoiceType": "Sale",
    "currency": "PKR",
    "paymentMode": "Cash",
    "customer": { "name": "Walk-in Customer" },
    "items": [{
      "description": "Chicken Karahi Full", "hsCode": "11001010",
      "quantity": 1, "unitPrice": 1500.00,
      "taxRate": 16, "taxAmount": 240.00, "total": 1740.00
    }],
    "subTotal": 1500.00, "tax": 240.00, "total": 1740.00
  }'

Environments & base URLs

Environment	Base URL	Key prefix	Notes
Sandbox	`https://taxbridge.themetasum.com`	`tbk_test_`	Never consumes production quota. Own soft monthly cap. Simulator available.
Production	`http://taxbridge-api-live.themetasum.com`	`tbk_live_`	Real submissions with your production credentials. A sandbox key never works here.

All endpoints below are relative to the base URL for your environment, e.g. https://taxbridge.themetasum.com/api/v1/invoices in sandbox.

Core endpoints

Method	Path	Purpose
`POST`	`/api/v1/invoices`	Submit a canonical invoice to the selected authority
`GET`	`/api/v1/invoices/{id}/status`	Retrieve the stored status of a prior submission
`POST`	`/api/auth/register`	Create a company and owner user

Response envelope

201 Created — one shape, every authority

{
  "success": true,
  "data": {
    "invoiceId": "INV-10001",
    "submissionId": "sub_01J8ZK7M4QW3RTYV6XB2N9C5PD",
    "authority": "PRA",
    "environment": "sandbox",
    "status": "APPROVED",
    "authorityInvoiceNumber": "PRA-123456",
    "qrCode": "PRA-123456",
    "quota": { "limit": 10000, "used": 6501, "remaining": 3499 }
  },
  "requestId": "REQ-20260810-A1B2C3D4"
}

Status & error codes

HTTP	Meaning	What your code does
`201`	Approved by the authority	Print `qrCode`, store `submissionId`
`200`	Idempotent replay (`duplicate:true`)	Treat like the original — no quota consumed
`400 INVALID_INVOICE`	Normalizer rejected it; `details[]` lists every problem	Fix and resubmit — no quota consumed
`402 QUOTA_EXCEEDED`	Plan limit hit or subscription expired	Upgrade or renew
`409 DUPLICATE_INVOICE`	Invoice number already approved for this authority + environment	Do not resubmit
`422`	Authority rejected it (`status:"REJECTED"`)	Read `authorityMessage`, fix the data
`429`	Rate limit or sandbox soft cap	Honour `Retry-After`
`502 / 504`	Authority errored or timed out	Retry with the same `Idempotency-Key`

Webhooks, rate limits & quotas

Webhooks

Signed payloads deliver asynchronous status so your system updates without polling.

Rate limits

Per-plan request rates (60–120 req/min). A 429 includes Retry-After.

Quotas

Monthly invoice limits per authority subscription. Every response includes quota.

Production activation

Production keys are issued after your company is approved and your production credentials and company/branch configuration are complete. Some authorities also require their own registration before live submissions succeed — see Production.