Fiscalize an invoice¶

The canonical invoice¶

Every connector maps its document into one canonical schema. The TaxCore-specific shaping happens once, inside the Bridge.

{
  "shop_id": "shp_123",
  "external_ref": "SO-1042",
  "invoice_type": "NORMAL",       // NORMAL | PROFORMA | COPY | TRAINING | ADVANCE
  "transaction_type": "SALE",     // SALE | REFUND
  "datetime_iso": "2026-06-10T03:00:00Z",
  "cashier": "Jane",
  "buyer_tin": "1000234",
  "currency": "VUV",
  "items": [
    {
      "name": "Premium Kava 500g",
      "gtin": "9415xxxxxxxxx",
      "quantity": 1,
      "unit_price_incl": 1725.00,
      "total_incl": 1725.00,
      "tax_labels": ["D"]
    }
  ],
  "payments": [{ "type": "CASH", "amount": 1725.00 }]
}

Field	Notes
`external_ref`	Your stable document id. Drives idempotency — must be unique per shop.
`unit_price_incl` / `total_incl`	Tax-inclusive. The SDC derives tax from the label.
`tax_labels`	Validated against the shop's SDC-synced rates; unknown labels are rejected.
`payments[].type`	`CASH \\| CARD \\| CHECK \\| WIRE \\| VOUCHER \\| MOBILE \\| OTHER`

The response¶

POST /v1/fiscalize signs the invoice synchronously and returns 200 OK with the full result. Internally Tax-Bridge absorbs the V-SDC's transient failures with a two-tier retry, so the call returns either a signed document or a clear failure:

{
  "request_id": "84cdb2803703ceb1f5b29392b6f594e0",
  "status": "FISCALIZED",
  "external_ref": "SO-1042",
  "invoice_number": "DX73WJZV-KMVACKO0-7877",
  "verification_url": "https://sandbox.taxcore.online/v/?vl=…",
  "qr_gif_base64": "R0lGODlh…",
  "journal": "============ FISCAL INVOICE ============ …"
}

status is FISCALIZED or FAILED (with an error). Render the verbatim journal, the QR (base64 GIF) and the verification URL to produce a compliant fiscal receipt. Look an invoice up again at any time with GET /v1/invoices/{request_id}.

Idempotent retries

Safe to retry on a network error — the deterministic request id means a repeat of the same (shop_id, external_ref) returns the existing fiscalization rather than signing twice.

Roadmap — fully async

A queue-backed mode (202 Accepted + interim non-fiscal slip → signed webhook callback) is on the roadmap for high-volume / offline POS, mirroring the interim-slip→fiscal-receipt UX in the connectors. The synchronous response above is the current contract.