Tax Intents

TaxIntents are the core abstraction for fiscal document management. They transform TaxBridge from a simple API wrapper into a Smart Registry that normalizes your data, ensures compliance, and handles the complexity of EFRIS.

The Smart Registry

In a standard integration, you are forced to change your ERP to speak "EFRIS" (codes like 204024... and units like KGM). TaxBridge flips this: it learns your language.

Normalization Engine

You send "CHIA-BAG" and "BAG". We map it to the URA commodity code, convert the unit to "KGM" (or "TNE" for exports), and calculate the precise tax rates.

Compliance Shield

URA codes change. Tax rates update. By decoupling your ERP from URA master data, TaxBridge updates the rules centrally without you needing to deploy code changes.

The "Explicit Confirm" Flow

TaxBridge uses a Create → Confirm pattern rather than "Fire and Forget". This ensures safety and predictability for fiscal data.

Step 1: Create Draft (Preview)

Send your raw data. We validate it, normalize it, and save it as a draft. You get a response showing exactly how we mapped your items and the calculated tax.

Step 2: Confirm (Fiscalize)

Once you (or your user) accepts the draft, call confirm. This queues the background fiscalization job. This separation prevents accidental submissions and broken partial states.

Status Lifecycle

TaxIntents move through a strictly defined state machine.

1

ready_for_submission

The intent is created, validated, and normalized. It is saved in the database but not yet sent to URA.

2

processing

You have confirmed the intent. It is queued for crypto-signing and submission to EFRIS.

3

succeeded

Fiscalization complete. FDN, Verification Code, and QR Code are available.

4

requires_correction

URA rejected the payload (e.g. duplicate reference, limit exceeded). You can update the intent and retry.

Preview (Simulation)

Want to see how your data maps without creating a record? Use the preview endpoint. It runs the full Normalization Engine and returns the calculated outcome.

POST /v1/tax-intents/preview

curl -X POST https://api.taxbridge.com/v1/tax-intents/preview \
  -H "Authorization: Bearer sk_test_..." \
  -d '{
    "taxMethodId": "DOMESTIC_B2B_STANDARD",
    "items": [
      { "externalRef": "CHIA-BAG", "quantity": 10, "unit": "BAG", "unitPrice": 50000 }
    ]
  }'

Response Preview

{
  "summary": { "totalGross": 500000, "totalTax": 90000 },
  "uraPayload": {
    "goodsDetails": [
      {
        "item": "Organic Chia Seeds",
        "unitOfMeasure": "KGM",   // <-- Normalized to KGM
        "qty": "500",             // <-- 10 Bags * 50kg
        "taxRate": "18"
      }
    ]
  }
}

Create & Confirm

The standard flow for issuing an invoice.

1. Create Draft

POST /v1/tax-intents

curl -X POST https://api.taxbridge.com/v1/tax-intents \
  -H "Authorization: Bearer sk_test_..." \
  -d '{
    "taxMethodId": "DOMESTIC_B2B_STANDARD",
    "externalRef": "INV-101",
    "buyerName": "Acme Corp",
    "buyerTin": "100058...",
    "items": [...]
  }'

2. Confirm

POST /v1/tax-intents/:id/confirm

curl -X POST https://api.taxbridge.com/v1/tax-intents/ti_123abc/confirm \
  -H "Authorization: Bearer sk_test_..."

Corrections

If an intent fails with requires_correction, you don't need to start over. Just PATCH the fields that were wrong and confirm again.

Idempotency & Retries

The id and externalRef stay the same. This maintains a clean audit trail showing the failed attempt and the subsequent correction under the same transaction ID.