Invoices API

Create and manage fiscal documents through TaxIntents. The invoices API provides a high-level abstraction over EFRIS T109/T110/T111 operations.

Overview

The Invoices API is centered around TaxIntents - long-lived objects that represent the lifecycle of fiscal document issuance. This provides reliability, auditability, and correction capabilities that raw T-code calls lack.

TaxIntent Lifecycle

Every invoice starts as a TaxIntent that goes through: creation → normalization → confirmation → processing → success/failure. This ensures data integrity and provides recovery from failures.

Create TaxIntent

Create a new TaxIntent with your invoice data. This creates a draft that can be reviewed and confirmed before fiscalization.

POST /v1/tax-intents

# Request

curl -X POST https://api.taxbridge.com/v1/tax-intents \
  -H "Authorization: Bearer sk_test_1234567890abcdef" \
  -H "X-Tax-Payer-ID: tp_your_taxpayer_id" \
  -H "Content-Type: application/json" \
  -d '{
    "taxMethodId": "DOMESTIC_B2B_STANDARD",
    "externalRef": "INV-2025-001",
    "buyerName": "Acme Corporation Ltd",
    "buyerTin": "1000058899",
    "currency": "UGX",
    "paymentMode": "101",
    "items": [
      {
        "externalRef": "CHIA-50KG",
        "description": "Organic Chia Seeds",
        "quantity": 10,
        "unitPrice": 50000,
        "unit": "PA"
      }
    ]
  }'

201 Created Response

{
  "id": "ti_xyz789",
  "taxpayerId": "tp_123",
  "externalRef": "INV-2025-001",
  "status": "REQUIRES_NORMALIZATION",
  "taxMethodId": "DOMESTIC_B2B_STANDARD",
  "buyerName": "Acme Corporation Ltd",
  "buyerTin": "1000058899",
  "totalGross": "500000",
  "currency": "UGX",
  "items": [
    {
      "externalRef": "CHIA-50KG",
      "quantity": 10,
      "unitPrice": 50000,
      "unit": "PA"
    }
  ],
  "createdAt": "2025-12-10T10:00:00Z"
}

Confirm TaxIntent

Confirm a normalized TaxIntent to trigger fiscalization. This is the point of no return - the invoice will be submitted to URA.

POST /v1/tax-intents/{id}/confirm

# Request

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

202 Accepted Response

{
  "message": "Submission queued",
  "status": "PROCESSING"
}

Get TaxIntent

Retrieve the current status and details of a TaxIntent. Poll this endpoint to track fiscalization progress.

GET /v1/tax-intents/{id}

# Request

curl https://api.taxbridge.com/v1/tax-intents/ti_xyz789 \
  -H "Authorization: Bearer sk_test_1234567890abcdef"

200 OK Response (Succeeded)

{
  "id": "ti_xyz789",
  "status": "SUCCEEDED",
  "fdn": "1234567890",
  "verificationCode": "ABC123XYZ",
  "qrCode": "base64_encoded_qr_data",
  "lastError": null
}

List TaxIntents

Get all TaxIntents for a specific taxpayer. Useful for displaying invoice history and status in your application.

GET /v1/tax-intents

# Request

curl "https://api.taxbridge.com/v1/tax-intents" \
  -H "Authorization: Bearer sk_test_1234567890abcdef" \
  -H "X-Tax-Payer-ID: tp_your_taxpayer_id"

Request Parameters

Create TaxIntent

Parameter	Type	Required	Description
taxMethodId	string	Yes	Tax method ID (e.g., "DOMESTIC_B2B_STANDARD")
externalRef	string	Yes	Idempotency key for your reference
buyerName	string	No*	Required for B2B and Export
buyerTin	string	No*	Required for B2B
buyerPassportNum	string	No*	Export only (Passport of buyer)
currency	string	Yes	ISO Currency Code (e.g. "UGX", "USD")
items	array	Yes	Line items array

Item Object

Field	Type	Required	Description
externalRef	string	Yes	Your SKU (must be mapped in catalog)
quantity	number	Yes	Quantity in your units
unitPrice	number	Yes	Price per unit (excluding tax)
unit	string	Yes	Unit code (e.g. "PA", "KGM")

Error Responses

400 Bad Request

Invalid request parameters or business logic violation.

{"message": "Missing taxpayer id", "error": "Bad Request"}

409 Conflict

Duplicate externalRef.

{"message": "TaxIntent with this externalRef already exists", "error": "Conflict"}

422 Unprocessable Entity

Business validation failed (e.g., unmapped SKU).

{"error": "ValidationError", "message": "SKU 'UNKNOWN-001' is not configured"}

Available Tax Methods

Method ID	Description	VAT	Required Fields
DOMESTIC_B2B_STANDARD	Standard local B2B invoice	18%	buyerTin, buyerName
DOMESTIC_B2C	Simplified B2C receipt	18%	(None)
EXPORT_ZERO_RATED	Export invoice	0%	buyerName, currency, buyerPassportNum (if applicable)
DOMESTIC_EXEMPT	VAT-Exempt Invoice	0%	buyerName