C-Tax API Documentation

Welcome to the C-Tax API documentation. C-Tax is a comprehensive tax compliance and transaction management system designed to integrate with Kenya Revenue Authority’s (KRA) eTIMS/VSCU system.

Overview

C-Tax provides a complete solution for businesses to automate tax compliance, manage transactions, and integrate seamlessly with KRA’s electronic Tax Invoice Management System (eTIMS).

Key Features

• Automated KRA Integration - Direct VSCU connectivity for real-time tax compliance
• Multi-Branch Support - Manage multiple business locations from a single account
• Transaction Management - Sales, purchases, stock movements, and imports
• Async Processing - Queue-based processing for high-volume transactions
• Webhook Notifications - Real-time event notifications via webhooks
• Comprehensive API - RESTful API for seamless integration with existing systems

Base URL

https://your-domain.com/api/v1

All API requests should be prefixed with this base URL.

Authentication

All endpoints require API key authentication via the Authorization header:

Authorization: Bearer YOUR_API_KEY

Your API key is generated when your client account is approved. Keep it secure and never expose it in client-side code.

See Authentication for detailed information.

Environments

C-Tax supports two environments:

API Endpoints Overview

Core Transaction APIs

Management APIs

Reference Data APIs

Supporting APIs

Standard Response Format

Success Response

{
  "status": "success",
  "message": "Operation completed successfully",
  "data": {
    // Response data
  },
  "meta": {
    "timestamp": "2025-01-15T14:30:00Z",
    "request_id": "req_abc123"
  }
}

Error Response

{
  "status": "error",
  "message": "Human-readable error message",
  "errors": {
    "field_name": ["Validation error message"]
  },
  "meta": {
    "timestamp": "2025-01-15T14:30:00Z",
    "request_id": "req_abc123"
  }
}

Pagination

List endpoints support pagination:

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total": 156,
    "total_pages": 4
  }
}

Date/Time Formats

HTTP Status Codes

Rate Limiting

• 60 requests per minute per API key
• Rate limit headers included in responses:
  • X-RateLimit-Limit: Maximum requests allowed
  • X-RateLimit-Remaining: Requests remaining
  • X-RateLimit-Reset: Time until limit resets

Async Processing

For high-volume transactions, use async processing:

POST /api/v1/sales?async=true

Returns 202 Accepted with transaction ID:

{
  "status": "processing",
  "message": "Transaction is being processed",
  "data": {
    "transaction_id": "uuid-here",
    "status": "pending"
  },
  "meta": {
    "check_status_url": "/api/v1/transactions/{id}"
  }
}

Use webhooks for real-time status updates or poll the transaction endpoint.

Tax Types

C-Tax supports Kenya’s tax classification system:

Transaction Types

Transaction Statuses

Quick Start

1. Get API Credentials

After your account is approved, you’ll receive your API key.

2. Configure VSCU Device

// Create and initialize device
await axios.post('/api/v1/devices', {
  bhf_id: '00',
  tin: 'YOUR_TIN',
  dvc_srl_no: 'DEVICE_SERIAL',
  vscu_url: 'VSCU_URL'
});
 
await axios.post('/api/v1/devices/00/initialize');

3. Sync Reference Data

// Sync codes from KRA
await axios.post('/api/v1/codes/sync', {
  bhf_id: '00'
});

4. Submit Your First Sale

const sale = await axios.post('/api/v1/sales', {
  branch_id: '00',
  invoice_no: 'INV-001',
  sale_date: '20250115',
  sale_time: '143000',
  payment_type: 'CASH',
  customer_name: 'John Doe',
  items: [{
    item_sequence: 1,
    item_code: 'ITEM001',
    item_name: 'Product A',
    quantity: 2,
    unit_price: 1000,
    supply_amount: 2000,
    tax_type: 'A',
    tax_rate: 16,
    tax_amount: 320,
    total_amount: 2320
  }]
});

SDKs and Tools

• Postman Collection - Available on request
• PHP SDK - Coming soon
• JavaScript SDK - Coming soon

Support

• Documentation Issues - Report on GitHub
• API Support - support@c-tax.ke
• Emergency Support - Contact your account manager

Next Steps

• Authentication - Learn about API authentication
• Sales API - Start processing sales
• Webhooks - Set up real-time notifications
• Features - Explore all features