How does a tax API work?
Your software builds an invoice and POSTs it to the API with an authentication key and an idempotency key. The gateway validates and normalizes the invoice, reserves quota, calls the tax authority, stores the result and returns a normalized response containing the fiscal invoice number and QR. Retries with the same idempotency key replay the stored result safely.
The request pipeline
Authenticate
A scoped bearer key identifies your company and environment.
Validate & normalize
The gateway checks the canonical invoice and translates it to the authority format.
Reserve quota & check idempotency
A repeated Idempotency-Key replays the stored response with no double submission.
Call the authority
The correct provider adapter submits the invoice (or the simulator answers locally in sandbox).
Persist & respond
The result is stored and returned as one normalized envelope with status, fiscal number and QR.
What comes back
{
"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"
}Why idempotency matters
Networks fail mid-request. Without idempotency, a retry could file the same invoice twice or double-charge quota. An Idempotency-Key makes a retry safe: a completed key replays the exact stored response and makes no upstream call. Always send one.