VSCU Devices API

Configure and manage VSCU (Virtual Sales Control Unit) devices for KRA eTIMS compliance.

Overview

VSCU devices are required for tax compliance with Kenya Revenue Authority (KRA). Each branch requires a configured and initialized VSCU device to process transactions.

Device Lifecycle

Create - Register device configuration
Test - Verify connectivity to VSCU server
Initialize - Activate device and sync reference data
Operate - Process transactions
Maintain - Periodic sync and monitoring

List Devices

Get all VSCU devices for your account.

GET/api/v1/devices

List Devices

Retrieve all VSCU devices configured for your client account.

Authentication

Response

Status: 200 OK


{
  "status": "success",
  "data": [
    {
      "id": 1,
      "branch_id": 1,
      "bhf_id": "00",
      "tin": "P000123456X",
      "dvc_srl_no": "VSCU-KE-001",
      "vscu_url": "http://localhost:8080",
      "is_active": true,
      "last_initialized_at": "2025-01-15T10:00:00Z",
      "device_info": {},
      "created_at": "2025-01-10T08:00:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "timestamp": "2025-01-15T14:30:00Z"
  }
}

Create Device

Configure a new VSCU device for a branch.

POST/api/v1/devices

Create Device

Configure a new VSCU device for a branch. The branch must exist before creating a device.

Authentication

Request BodyJSON

Field Descriptions

Field	Type	Required	Description
`bhf_id`	string	Yes	Branch identifier (must exist)
`tin`	string	Yes	Tax Identification Number
`dvc_srl_no`	string	Yes	Device serial number from KRA
`vscu_url`	string	Yes	VSCU server URL
`credentials`	object	No	Encrypted authentication credentials

Response

Status: 201 Created


{
  "status": "success",
  "message": "Device created successfully",
  "data": {
    "id": 1,
    "bhf_id": "00",
    "tin": "P000123456X",
    "dvc_srl_no": "VSCU-KE-001",
    "vscu_url": "http://vscu.kra.go.ke:8080",
    "is_active": false,
    "last_initialized_at": null,
    "created_at": "2025-01-15T14:30:00Z"
  },
  "meta": {
    "timestamp": "2025-01-15T14:30:00Z",
    "next_step": "Initialize the device using POST /api/v1/devices/00/initialize"
  }
}

Get Device Details

Retrieve details of a specific VSCU device.

GET/api/v1/devices/{bhfId}

Get Device Details

Retrieve detailed information about a specific VSCU device.

Authentication

Parameters

bhfId*

string · path

Branch identifier (e.g., '00')

Response

Status: 200 OK


{
  "status": "success",
  "data": {
    "id": 1,
    "branch_id": 1,
    "bhf_id": "00",
    "tin": "P000123456X",
    "dvc_srl_no": "VSCU-KE-001",
    "vscu_url": "http://vscu.kra.go.ke:8080",
    "is_active": true,
    "last_initialized_at": "2025-01-15T10:00:00Z",
    "device_info": {
      "device_type": "VSCU",
      "firmware_version": "1.0.0"
    },
    "created_at": "2025-01-10T08:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z"
  }
}

Update Device

Update an existing VSCU device configuration.

PUT/api/v1/devices/{bhfId}

Update Device

Update VSCU device configuration. Note: Device must be re-initialized after URL change.

Authentication

Parameters

bhfId*

string · path

Branch identifier

Request BodyJSON

Response

Status: 200 OK


{
  "status": "success",
  "message": "Device updated successfully",
  "data": {
    "id": 1,
    "bhf_id": "00",
    "vscu_url": "http://new-vscu-server:8080",
    "updated_at": "2025-01-17T15:00:00Z"
  },
  "meta": {
    "note": "Device must be re-initialized after URL change"
  }
}

Delete Device

Remove a VSCU device configuration.

DELETE/api/v1/devices/{bhfId}

Delete Device

Remove a VSCU device configuration. Warning: This prevents the branch from processing transactions.

Authentication

Parameters

bhfId*

string · path

Branch identifier

Response

Status: 200 OK


{
  "status": "success",
  "message": "Device deleted successfully"
}

Warning: Deleting a device prevents the branch from processing transactions until a new device is configured.

Initialize Device

Initialize or re-initialize a VSCU device with KRA. This is required before processing transactions.

POST/api/v1/devices/{bhfId}/initialize

Initialize Device

Initialize the device with KRA. This fetches reference data and activates the device for transaction processing.

Authentication

Parameters

bhfId*

string · path

Branch identifier

Request BodyJSON

What Happens During Initialization

Connects to VSCU server using device credentials
Registers/validates the device with KRA
Fetches reference data (tax types, codes, classifications)
Stores configuration locally for offline validation
Validates bidirectional connectivity

Response

Status: 200 OK


{
  "status": "success",
  "message": "Device initialized successfully",
  "data": {
    "bhf_id": "00",
    "is_active": true,
    "last_initialized_at": "2025-01-17T15:00:00Z",
    "synced_data": {
      "tax_types": 5,
      "item_classes": 120,
      "packaging_units": 15,
      "quantity_units": 20,
      "payment_types": 8,
      "countries": 195
    }
  },
  "meta": {
    "timestamp": "2025-01-17T15:00:00Z"
  }
}

Error Response

Status: 422 Unprocessable Entity


{
  "status": "error",
  "message": "Device initialization failed",
  "data": {
    "bhf_id": "00",
    "error_details": "Connection to VSCU server timed out"
  }
}

Test Device Connection

Test connectivity to the VSCU server without full initialization.

POST/api/v1/devices/{bhfId}/test

Test Device Connection

Test connectivity to the VSCU server. Use this before initialization to verify network access.

Authentication

Parameters

bhfId*

string · path

Branch identifier

Request BodyJSON

Response

Status: 200 OK (Success)


{
  "status": "success",
  "message": "Connection test successful",
  "data": {
    "bhf_id": "00",
    "vscu_url": "http://vscu.kra.go.ke:8080",
    "connectivity": "ok",
    "response_time_ms": 145,
    "tested_at": "2025-01-17T15:30:00Z"
  }
}

Status: 422 Unprocessable Entity (Failed)


{
  "status": "error",
  "message": "Connection test failed",
  "data": {
    "bhf_id": "00",
    "vscu_url": "http://vscu.kra.go.ke:8080",
    "connectivity": "failed",
    "error": "Connection refused"
  }
}

Device Status Values

Status	Description
`is_active: false`	Device created but not initialized
`is_active: true`	Device initialized and operational

Code Examples

JavaScript


const axios = require('axios');
 
const apiKey = process.env.CTAX_API_KEY;
const baseURL = 'https://c-tax.1809ltd.co.ke/api/v1';
 
// Create device
const device = await axios.post(`${baseURL}/devices`, {
  bhf_id: '00',
  tin: 'P000123456X',
  dvc_srl_no: 'VSCU-KE-001',
  vscu_url: 'http://vscu.kra.go.ke:8080'
}, {
  headers: { Authorization: `Bearer ${apiKey}` }
});
 
// Test connection before initialization
const test = await axios.post(`${baseURL}/devices/00/test`, {}, {
  headers: { Authorization: `Bearer ${apiKey}` }
});
 
if (test.data.data.connectivity === 'ok') {
  // Initialize device
  const init = await axios.post(`${baseURL}/devices/00/initialize`, {}, {
    headers: { Authorization: `Bearer ${apiKey}` }
  });
  console.log('Device initialized:', init.data);
}

PHP


use GuzzleHttp\Client;
 
$client = new Client([
    'base_uri' => 'https://c-tax.1809ltd.co.ke/api/v1/',
    'headers' => [
        'Authorization' => 'Bearer ' . env('CTAX_API_KEY'),
        'Content-Type' => 'application/json',
    ],
]);
 
// Create device
$response = $client->post('devices', [
    'json' => [
        'bhf_id' => '00',
        'tin' => 'P000123456X',
        'dvc_srl_no' => 'VSCU-KE-001',
        'vscu_url' => 'http://vscu.kra.go.ke:8080',
    ],
]);
 
// Test connection
$test = $client->post('devices/00/test');
 
// Initialize device
$init = $client->post('devices/00/initialize');

Python


import requests
import os
 
api_key = os.environ['CTAX_API_KEY']
base_url = 'https://c-tax.1809ltd.co.ke/api/v1'
headers = {'Authorization': f'Bearer {api_key}'}
 
# Create device
response = requests.post(
    f'{base_url}/devices',
    json={
        'bhf_id': '00',
        'tin': 'P000123456X',
        'dvc_srl_no': 'VSCU-KE-001',
        'vscu_url': 'http://vscu.kra.go.ke:8080'
    },
    headers=headers
)
 
# Test and initialize
test = requests.post(f'{base_url}/devices/00/test', headers=headers)
if test.json()['data']['connectivity'] == 'ok':
    init = requests.post(f'{base_url}/devices/00/initialize', headers=headers)

Device Setup Workflow

Step 1: Create Branch

First, create a branch using the Branches API.

Step 2: Create Device Configuration


const device = await createDevice({
  bhf_id: '00',
  tin: 'P000123456X',
  dvc_srl_no: 'VSCU-KE-001',
  vscu_url: 'http://vscu.kra.go.ke:8080'
});

Step 3: Test Connection

Verify connectivity before initialization:


const testResult = await testDevice('00');
if (testResult.connectivity !== 'ok') {
  console.error('Connection failed:', testResult.error);
  return;
}

Step 4: Initialize Device

Initialize with KRA to fetch configuration:


const initResult = await initializeDevice('00');
console.log('Synced data:', initResult.synced_data);

Step 5: Start Processing

Branch is now ready to process transactions!

Best Practices

Test Before Initialize - Always test connection before full initialization
Monitor Status - Regularly check device status
Handle Errors - Implement retry logic for connection issues
Sync Periodically - Re-initialize weekly to refresh reference data
Secure Credentials - Store TIN and serial numbers securely (encrypted)
Log Operations - Keep logs of initialization and errors
Backup Configuration - Store retrieved reference data locally
Update URLs Carefully - Changing VSCU URL requires re-initialization

Troubleshooting

Device Initialization Fails

Symptoms: Initialization returns error

Solutions:

Test connection first: POST /devices/{bhfId}/test
Verify VSCU URL is correct and accessible
Check TIN and device serial number are valid
Ensure network allows connection to VSCU server
Check firewall rules
Contact KRA support if issues persist

Connection Timeouts

Symptoms: Requests to VSCU timeout

Solutions:

Check network connectivity
Verify firewall rules allow outbound connections
Check VSCU server status with KRA
Try during off-peak hours

Configuration Out of Date

Symptoms: Tax codes or item classes not found

Solutions:

Re-initialize device to refresh reference data
Check if KRA has updated code lists
Verify device is still registered with KRA

Error Codes

Code	Description	Action
`000`	Success	None required
`400`	Invalid request	Check request parameters
`401`	Authentication failed	Verify TIN and device serial
`404`	Device not found	Check device registration
`500`	Server error	Contact support
`503`	Service unavailable	Try again later
`504`	Gateway timeout	Network issue, retry

Security Considerations

Encrypted Credentials - Device credentials are encrypted at rest
TLS/SSL - All communication uses HTTPS
Access Control - Only authorized users can manage devices
Audit Logging - All device operations are logged

Branches API - Manage branches
Sales API - Process sales transactions
Codes API - View synced reference data
Notices API - Receive KRA notifications

VSCU Devices API

Overview

Device Lifecycle

List Devices

List Devices

Response

Create Device

Create Device

Field Descriptions

Response

Get Device Details

Get Device Details

Response

Update Device

Update Device

Response

Delete Device

Delete Device

Response

Initialize Device

Initialize Device

What Happens During Initialization

Response

Error Response

Test Device Connection

Test Device Connection

Response

Device Status Values

Code Examples

JavaScript

PHP

Python

Device Setup Workflow

Step 1: Create Branch

Step 2: Create Device Configuration

Step 3: Test Connection

Step 4: Initialize Device

Step 5: Start Processing

Best Practices

Troubleshooting

Device Initialization Fails

Connection Timeouts

Configuration Out of Date

Error Codes

Security Considerations

Related Endpoints