KRA eTims SDK

A comprehensive Node.js SDK for integrating with the Kenya Revenue Authority (KRA) Electronic Tax Invoice Management System (eTims).

Features

Complete KRA eTims API integration
Express.js server mode for easy API endpoint exposure
CORS support with domain whitelisting
Comprehensive validation for all API requests
Detailed logging and error handling
Environment-based configuration
TypeScript support

Author

Shadrack Matata
Email: kisamba.debug@gmail.com
Tel: +254722854082 / +254733854082

Installation

npm install kra-etims-sdk

Quick Start

Basic Usage

const KRAeTimsSDK = require('kra-etims-sdk');

// Initialize the SDK
const sdk = new KRAeTimsSDK();

// Authenticate with KRA eTims API
async function authenticate() {
  try {
    const token = await sdk.authenticate('your_username', 'your_password');
    console.log('Authentication successful:', token);
    return token;
  } catch (error) {
    console.error('Authentication failed:', error);
  }
}

// Send a sales transaction
async function sendSalesTransaction() {
  try {
    // Authenticate first
    await authenticate();
    
    // Prepare sales transaction data
    const salesData = {
      tin: 'P000000045R',
      bhfId: '00',
      invcNo: 'INV001',
      salesTrnsItems: [
        {
          itemCd: 'ITEM001',
          itemNm: 'Test Item',
          qty: 1,
          prc: 100,
          splyAmt: 100,
          dcRt: 0,
          dcAmt: 0,
          taxTyCd: 'V',
          taxAmt: 16
        }
      ]
    };
    
    // Send sales transaction
    const result = await sdk.sendSalesTransaction(salesData);
    console.log('Sales transaction sent:', result);
  } catch (error) {
    console.error('Failed to send sales transaction:', error);
  }
}

Express Server Integration

Complete Express Integration Example

Below is a comprehensive example of integrating the KRA eTims SDK with an Express application as middleware:

const express = require('express');
const bodyParser = require('body-parser');
const morgan = require('morgan'); // Optional for logging
const KRAeTimsSDK = require('kra-etims-sdk');

// Initialize Express app
const app = express();
const port = process.env.PORT || 3000;

// Middleware
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({ extended: true }));
app.use(morgan('dev')); // Optional for logging

// Initialize the KRA eTims SDK
const etimsSDK = new KRAeTimsSDK({
  // Optional configuration
  logLevel: 'info', // 'debug', 'info', 'warn', 'error'
  timeout: 30000, // API request timeout in ms
});

// Mount the SDK as middleware
app.use('/etims-api', etimsSDK.middleware());

// Custom routes that use the SDK directly

// Authentication example
app.post('/api/login', async (req, res) => {
  try {
    const { username, password } = req.body;
    const token = await etimsSDK.authenticate(username, password);
    res.json({ success: true, token });
  } catch (error) {
    console.error('Authentication error:', error);
    res.status(401).json({ success: false, error: error.message });
  }
});

// Sales transaction example
app.post('/api/sales', async (req, res) => {
  try {
    // Authenticate first (or use middleware to handle this)
    await etimsSDK.authenticate(process.env.API_USERNAME, process.env.API_PASSWORD);
    
    // Send sales transaction
    const result = await etimsSDK.sendSalesTransaction(req.body);
    res.json({ success: true, data: result });
  } catch (error) {
    console.error('Sales transaction error:', error);
    res.status(400).json({ success: false, error: error.message });
  }
});

// Get stock information example
app.post('/api/stock/info', async (req, res) => {
  try {
    await etimsSDK.authenticate(process.env.API_USERNAME, process.env.API_PASSWORD);
    const result = await etimsSDK.getStockMoveList(req.body);
    res.json({ success: true, data: result });
  } catch (error) {
    console.error('Stock info error:', error);
    res.status(400).json({ success: false, error: error.message });
  }
});

// Error handling middleware
app.use((err, req, res, next) => {
  console.error('Application error:', err);
  res.status(500).json({ success: false, error: 'Internal server error' });
});

// Start the server
app.listen(port, () => {
  console.log(`Server running on port ${port}`);
});

Authentication Middleware Example

Create a reusable authentication middleware for your Express routes:

// auth.middleware.js
const KRAeTimsSDK = require('kra-etims-sdk');
const sdk = new KRAeTimsSDK();

const authMiddleware = async (req, res, next) => {
  try {
    // You could also check for an existing token and validate it
    await sdk.authenticate(process.env.API_USERNAME, process.env.API_PASSWORD);
    req.etimsSDK = sdk; // Attach the authenticated SDK to the request
    next();
  } catch (error) {
    console.error('KRA eTims authentication error:', error);
    res.status(401).json({ success: false, error: 'Authentication failed' });
  }
};

module.exports = authMiddleware;

Then use it in your routes:

const express = require('express');
const authMiddleware = require('./auth.middleware');
const router = express.Router();

// Apply authentication middleware to all routes
router.use(authMiddleware);

// Now all routes have access to the authenticated SDK via req.etimsSDK
router.post('/sales/send', async (req, res) => {
  try {
    const result = await req.etimsSDK.sendSalesTransaction(req.body);
    res.json({ success: true, data: result });
  } catch (error) {
    res.status(400).json({ success: false, error: error.message });
  }
});

module.exports = router;

Setting Up as a Standalone Server

For comparison, here's how to set up the SDK as a standalone server:

const KRAeTimsSDK = require('kra-etims-sdk');

// Initialize the SDK with server option
const sdk = new KRAeTimsSDK({ server: true });

// Start the server
const port = process.env.PORT || 5000;
sdk.start(port).then(() => {
  console.log(`KRA eTims server started on port ${port}`);
}).catch(err => {
  console.error('Failed to start server:', err);
});

Environment Configuration

Create a .env file in your project root:

# API Base URLs
DEV_API_BASE_URL=https://etims-api-sbx.kra.go.ke
PROD_API_BASE_URL=https://etims-api.kra.go.ke/etims-api

# Authentication
API_USERNAME=your_username
API_PASSWORD=your_password

# Environment
NODE_ENV=development
PORT=5000

# CORS Configuration
CORS_ALLOWED_ORIGINS=http://localhost:3000,https://yourdomain.com

Switching Between Production and Development Endpoints

The SDK automatically selects the appropriate API base URL based on the NODE_ENV environment variable:

When NODE_ENV=development (or not set), the SDK uses DEV_API_BASE_URL (sandbox environment)
When NODE_ENV=production, the SDK uses PROD_API_BASE_URL (production environment)

Method 1: Using Environment Variables

# For development (sandbox)
NODE_ENV=development npm start

# For production
NODE_ENV=production npm start

Method 2: Setting NODE_ENV in Your Code

// Before initializing the SDK
process.env.NODE_ENV = 'production'; // or 'development'

const KRAeTimsSDK = require('kra-etims-sdk');
const sdk = new KRAeTimsSDK();

Method 3: Explicitly Setting the API Base URL

You can also override the automatic selection by explicitly setting the API base URL when initializing the SDK:

const KRAeTimsSDK = require('kra-etims-sdk');

// For development (sandbox)
const devSdk = new KRAeTimsSDK({
  apiBaseUrl: 'https://etims-api-sbx.kra.go.ke'
});

// For production
const prodSdk = new KRAeTimsSDK({
  apiBaseUrl: 'https://etims-api.kra.go.ke/etims-api'
});

CORS and Security

The SDK includes built-in CORS support with domain whitelisting to secure your API endpoints.

Configuring CORS

You can configure allowed origins in your .env file:

CORS_ALLOWED_ORIGINS=https://yourdomain.com,https://app.yourdomain.com

By default, the SDK allows requests from http://localhost:3000 and http://localhost:5000 in development.

API Endpoints and Integration Examples

This section provides comprehensive examples of how to use each endpoint in your Express application.