Using the DigiTax Tanzania API

Overview

The DigiTax Tanzania API is a RESTful JSON API. It sits between your system and TRA's EFDMS, handling the complexity of the EFDMS XML protocol, PKI signing, counter management, and Z Report submission on your behalf.

You interact with DigiTax using clean, well-documented JSON endpoints. DigiTax does the rest.

Authentication

All API requests require an X-API-Key header:

X-API-Key: your-api-key-here

Read Prerequisites of using the API for how to generate an API Key.

Base URL

All DigiTax Tanzania API endpoints use the base URL:

https://api.digitax.tech/tz/v1

Typical workflow

The standard flow to generate a fiscalized receipt or invoice is:

1. POST /items                   - register your product or service
2. POST /customers               - register the buyer (optional for B2C walk-in retail)
3. POST /invoices                - submit the invoice; DigiTax fiscalizes with TRA
4. GET  /invoices/{id}           - retrieve the completed invoice with fiscal data
5. GET  /invoices/{id}/detailed  - inspect full customer, payment, and tax breakdowns

Invoice fiscalization lifecycle

When you submit an invoice via POST /invoices, DigiTax records the transaction and submits it to TRA's EFDMS. As the invoice progresses through fiscalization, its status transitions:

1. PENDING: The invoice is recorded and queued for transmission.
2. SUBMITTED: Transmitted to TRA's EFDMS and awaiting confirmation.
3. ISSUED: Successfully fiscalized by TRA. The verification_code, verification_url, and receipt_number are populated.
4. FAILED: Rejected by TRA (e.g. invalid customer TIN).

{
  "id": "invoice_01HC3J1VVVM05YCTS61G7V3KC6",
  "status": "ISSUED",
  "receipt_number": 42,
  "verification_code": "ABCD1234",
  "verification_url": "https://virtual.tra.go.tz/efdmsRctVerify/Home/Index?rctvnum=ABCD1234",
  "tax_exclusive_total": 100000,
  "tax_inclusive_total": 118000
}

Counter management

TRA's EFDMS requires every submission to carry sequential counters:

DigiTax manages all counters automatically. Incorrect counter values cause EFDMS rejections and can disrupt your fiscal sequence. You never need to supply or track counter values - DigiTax ensures they are always correct.

Z Reports

TRA requires a daily Z Report to be submitted after the last transaction of each business day. DigiTax TZ submits Z Reports automatically. You will see a Z Report record in your DigiTax Dashboard each day.

Rate limiting

All endpoints are rate-limited. If you exceed the rate limit, you receive a 429 Too Many Requests response. Retry at a slower cadence.

Pagination

GET endpoints that return lists support cursor-based pagination via optional query parameters: