Prerequisites of using the API

All you need to start using the API

Prerequisites of using the API

📘

You can test the DigiTax API before reaching out to us

We've designed the developer experience to be Hands-off. Meaning you can get started with your first API call without engaging with our team. Should you need our support or want to onboard your business to LIVE, reach out to us.

The following are the steps to creating a sandbox business and getting an X-API-Key (for testing before you go LIVE):

  1. Sign up on DigiTax
  2. Create a Zimbabwe profile.
  3. Create a test/sandbox business.
  4. Generate an API Key under the "Integrations" tab. See screenshots below.
  5. Use the copied API Key as X-API-Key in your header when making API calls through the interactive API docs, your local environment or directly in your system integration.

See screenshots below.

Generate an API Key

In a test/sandbox or LIVE business,

  1. Navigate to the "Integrations" menu tab

  2. Select "Add API KEY"

    Integrations module

  3. Enter a name and select "API Key"

    Create API Key

    Please record the value that you generate for later use, as you will not see it from the dashboard on subsequent visits. Save it securely.

License Key

In step 3 above, under API Type, we have two options:

  • API Key - Stick with 'API Key' for standard integrations.
  • License Key - Use 'License Key' only if directed by the support team. Its use is restricted to specific systems.

Use the API Key

Once you've generated the API Key you can use it directly via our interactive API reference, on your local environment, or directly in your system integration.

Below is an example of a request made on our interactive API reference.

Successful API request

Steps:

  1. Add your API Key in this field to include it in the header
  2. Click "Try it!" to make a request.
  3. View API response

A good first call is GET /fdms-info, which shows your fiscal device as ZIMRA holds it.

Test businesses share a device

A test business doesn't need a device of its own from ZIMRA. It is linked to a test device that DigiTax has already registered on ZIMRA's test FDMS, so GET /fdms-info shows is_test: true and is_live: true, and you can issue receipts straight away. Test receipts carry no tax effect.

That device is shared with other test businesses, so:

  • fiscal days, and the receipt counters on them, are shared. Your receipt numbers won't be consecutive, and a fiscal day may already be open when you issue your first receipt.
  • another business's receipt can halt sending or hold a fiscal day open for everyone on the device. See When sending halts.
  • a fiscal day's X and Z reports cover only your own receipts (own_receipts_only: true).

Go LIVE

A production business has a fiscal device of its own, registered with ZIMRA:

  1. Create a LIVE business under your Zimbabwe profile. Its device starts UNREGISTERED.
  2. Get your device ID and activation key from ZIMRA.
  3. Reach out to DigiTax support. Commercial conversations are finalized at this point (if not sooner), and DigiTax registers your device with ZIMRA.
  4. Once GET /fdms-info shows status: ACTIVE and is_live: true, generate an API Key for the LIVE business under the "Integrations" tab.
👍

Your integration is LIVE 🎉

Using the LIVE X-API-Key, your receipts go to ZIMRA's production FDMS.