eTIMS Device & Configuration API

Configure and manage your eTIMS OSCU (Online Sales Control Unit) device. Initialize devices with KRA, set up CMC keys, and monitor connection health.

Table of Contents

1. Overview
2. Get Device Info
3. Initialize Device
4. Health Check
5. Get Business Info
6. Get Branch List
7. CMC Key Setup
8. Status Codes

Overview

Required Scopes

Endpoint Summary

eTIMS Architecture

Your POS / ERP System
        |
        v
  Salami Gateway API    (Bearer token auth)
        |
        v
  eTIMS OSCU Client     (TIN + BHFID + CMC Key headers)
        |
        v
  KRA eTIMS Server      (https://etims-api.kra.go.ke)

Get Device Info

Retrieve your eTIMS device configuration and current status.

Endpoint: GET /api/etims/device/info

Required Scope: etims:read

Request:

curl -X GET \
  https://yourtenant.salami.dgl.co.ke/api/etims/device/info \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Response:

{
  "success": true,
  "data": {
    "tin": "P051234567A",
    "bhfid": "00",
    "device_serial": "DVC2026001",
    "business_name": "Acme Limited",
    "branch_name": "Main Branch",
    "status": "active",
    "last_sync": "2026-03-29T15:30:00Z",
    "initialized": true,
    "environment": "production",
    "cmc_key_set": true
  }
}

Response Fields

Initialize Device

Initialize your OSCU device with KRA. This is a one-time setup step required before any other eTIMS operations.

Endpoint: POST /api/etims/device/initialize

Required Scope: etims:write

Request Body:

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/etims/device/initialize \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "tin": "P051234567A",
    "bhfid": "00",
    "device_serial": "DVC2026001"
  }'

Response:

{
  "success": true,
  "data": {
    "status": "initialized",
    "tin": "P051234567A",
    "bhfid": "00",
    "device_id": "DEV-KE-001",
    "cmc_key": "ABCD1234EFGH5678IJKL9012MNOP3456",
    "registration_date": "2026-03-29T16:00:00Z"
  },
  "message": "Device initialized successfully with KRA"
}

Response Fields

Important: The cmc_key is returned only during initialization. Store it securely -- it is required for all subsequent eTIMS API calls.

Health Check

Check the connection status with KRA eTIMS servers. Performs a lightweight ping request.

Endpoint: GET /api/etims/health

Required Scope: etims:read

Request:

curl -X GET \
  https://yourtenant.salami.dgl.co.ke/api/etims/health \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Response (healthy):

{
  "success": true,
  "data": {
    "status": "healthy",
    "kra_server": "reachable",
    "last_successful_sync": "2026-03-29T15:30:00Z",
    "response_time_ms": 234
  }
}

Response (unhealthy):

{
  "success": true,
  "data": {
    "status": "unhealthy",
    "kra_server": "unreachable",
    "last_successful_sync": "2026-03-29T10:00:00Z",
    "response_time_ms": null,
    "error": "Connection timed out"
  }
}

Get Business Info

Retrieve the taxpayer/business information registered with KRA for the configured eTIMS device.

Endpoint: GET /api/etims/business/info

Required Scope: etims:read

Request:

curl -X GET \
  https://yourtenant.salami.dgl.co.ke/api/etims/business/info \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Response:

{
  "success": true,
  "data": {
    "tin": "P051234567A",
    "taxpayer_name": "ACME LIMITED",
    "business_type": "Company",
    "address": "P.O. Box 12345-00100, Nairobi",
    "phone": "+254712345678",
    "email": "info@acme.co.ke",
    "station": "Nairobi"
  }
}

Get Branch List

Retrieve all branches registered under the taxpayer's TIN.

Endpoint: GET /api/etims/business/branches

Required Scope: etims:read

Request:

curl -X GET \
  https://yourtenant.salami.dgl.co.ke/api/etims/business/branches \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Response:

{
  "success": true,
  "data": [
    {
      "bhfid": "00",
      "branch_name": "Head Office",
      "address": "Nairobi CBD",
      "status": "Active"
    },
    {
      "bhfid": "01",
      "branch_name": "Mombasa Branch",
      "address": "Moi Avenue, Mombasa",
      "status": "Active"
    }
  ]
}

CMC Key Setup

The CMC Key (Communication Key) is a cryptographic key assigned by KRA during device initialization. It authenticates all subsequent API requests to the eTIMS server.

How CMC Keys Work

1. Generation: KRA generates and returns a CMC key during device initialization
2. Storage: Salami stores the CMC key in the KRA App configuration
3. Usage: Every eTIMS API request includes the CMC key in request headers
4. Rotation: CMC keys do not expire but can be regenerated via re-initialization

Request Header Format

All eTIMS requests include these headers (handled automatically by Salami):

tin: P051234567A
bhfId: 00
cmcKey: ABCD1234EFGH5678IJKL9012MNOP3456

Troubleshooting CMC Key Issues

Status Codes

Best Practices

1. Initialize once -- Device initialization is a one-time operation per branch
2. Store CMC key securely -- Treat it like a password; Salami handles this automatically
3. Monitor health -- Periodically check the health endpoint to detect connectivity issues
4. One device per branch -- Each physical branch needs its own BHFID and device
5. Test in sandbox -- Use the eTIMS test environment (etims-api-test.kra.go.ke) first

Related Documentation

• eTIMS Sales -- Submit and manage sales
• eTIMS Items -- Register and manage items
• eTIMS Codes -- Reference code tables
• KRA Overview -- General KRA integration architecture

Back to: KRA Overview | eTIMS Sales