How do you test a tax API?
Turn on the simulator for a sandbox credential and submit test invoices — they are answered locally with no network call. Use the magic invoice-number prefixes TEST-REJECT and TEST-TIMEOUT to trigger rejection and timeout paths on demand, verify idempotent replays, and read the request logs to confirm each response.
Trigger every outcome on demand
| Invoice number | Result |
|---|---|
TEST-REJECT... | Rejected (authority error) |
TEST-TIMEOUT... | Failed / timeout |
| anything else | Approved after 50–250 ms with a SIM-<AUTHORITY>-<hex> number |
Example — force a rejection to prove your error handling:
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": "TEST-REJECT-0001",
"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
}'A test checklist
- Approved invoice — you store
submissionIdand printqrCode - Validation error (400) — you surface the
details[]fields - Rejection (422) — you show
authorityMessage - Duplicate (409 / 200 replay) — you do not resubmit
- Timeout (502/504) — you retry with the same Idempotency-Key
- Quota exceeded (402) — you prompt to upgrade/renew
Read the logs
Every test submission is logged with the full request, response and normalized status. Use the logs to confirm the authority received exactly what you intended before you switch to a tbk_live_ key.
Frequently asked questions
Do I need real credentials to test?
No. The simulator answers locally, so you can build and prove your integration before any authority issues credentials.
How do I test retries?
Send the same Idempotency-Key twice and confirm the second call returns the stored response with no quota consumed.
Will test invoices reach the real authority?
No. Sandbox never files real invoices; production is a separate environment.