FAQ

The AltiTax API (KRA eTIMS Integrator) is a REST interface for connecting your systems to Kenya Revenue Authority eTIMS. You can initialize devices, manage customers and products, submit sales, issue credit notes, and sync stock without building raw KRA payloads yourself.

Use https://altitax.altifysolutions.com/api/v1 for all versioned public endpoints.

1) Copy an API key from Settings → API Settings.
2) Call GET https://altitax.altifysolutions.com/api/v1/credits/balance with X-API-Key.
3) For branch workflows, initialize once with POST https://altitax.altifysolutions.com/api/v1/initialize using a Branch API Key, then explore the API Reference.

List endpoints typically accept per_page (and page parameters where documented) and return Laravel-style paginated JSON with data plus pagination meta/links. See each endpoint in the API Reference for exact query parameters.

Send your API key in the X-API-Key header on every documented request.

X-API-Key: YOUR_BRANCH_API_KEY
Accept: application/json

In the Business Panel, open Settings → API Settings. Authorized users can view, generate, and regenerate Business API Keys and Branch API Keys. Copy keys when revealed — they are not emailed in full later.

A Business API Key authenticates API requests within the scope of the associated business. Use it for business-scoped endpoints such as credits, listing branches, subscriptions, and suppliers. It cannot call branch operations such as sales or stock, and it cannot access other businesses.

A Branch API Key authenticates API requests within the scope of the associated branch only. It is required for device initialization, products, inventory, sales, purchases, credit notes, notices, and related branch workflows. It may also call business-scoped endpoints for the same business — not other branches or businesses.

Business API Key — business-scoped and blocked from branch routes (BRANCH_API_KEY_REQUIRED).
Branch API Key — branch-scoped and unlocks operational eTIMS workflows for that branch.

Your Business API Key or Branch API Key resolves the business (and branch, for Branch API Keys) automatically. Prefer public API IDs in payloads (for example customer_01H…, item_01H…, branch_01H…) — never rely on internal numeric database IDs.

Use a Branch API Key and POST https://altitax.altifysolutions.com/api/v1/customers with the required customer fields. See Customers in the API Reference for validation rules and response shape.

Use a Branch API Key and POST https://altitax.altifysolutions.com/api/v1/items. Send price (tax-inclusive), classification, tax type, product type, and quantity unit. The application generates the KRA item_code automatically — do not send it. See Code Definitions for valid codes, and retrieve live code lists when needed.

Use a Branch API Key, ensure the branch is initialized, then POST https://altitax.altifysolutions.com/api/v1/sales with invoice details and line items. This typically consumes 5 credits. Follow create → validate → process → response in the Sales section of the API Reference.

Use a Branch API Key and POST https://altitax.altifysolutions.com/api/v1/credit-notes against an existing successful sale (whole-receipt). Provide the required reason and original receipt/invoice reference. See Credit Notes in the API Reference.

Use a Branch API Key and GET https://altitax.altifysolutions.com/api/v1/code-lists. Code lists supply valid values for fields used when creating items, sales, and other KRA-bound requests. Pass refresh=true when you need a fresh sync from KRA.

Validation failures typically return HTTP 422 with a JSON body containing message and an errors object keyed by field name. Fix the listed fields and retry.

Missing or invalid API key — commonly MISSING_API_KEY or INVALID_API_KEY. Confirm the header name is X-API-Key and the Business API Key or Branch API Key is active.

Access denied — inactive business, missing permission, or a Business API Key used on a branch endpoint (BRANCH_API_KEY_REQUIRED). Switch to a Branch API Key for that location.

Request validation failed or KRA rejected the payload. Read the field-level errors (or message) and correct the request.

Rate limited. Slow down and retry with backoff. Shared limits apply per API key.

Call POST https://altitax.altifysolutions.com/api/v1/initialize once per branch with a valid device_serial_number and a Branch API Key before other branch operations.

Use the contact form. Include the endpoint, timestamp, and X-Transaction-Reference when available — never send production API keys.