Sales API

{
  "status": "success",
  "message": "Sale processed successfully with KRA",
  "data": {
    "transaction_id": "9d3f4b1a-7c8e-4d2f-b5a6-1e3c9f8d2b4a",
    "invoice_no": "C-USRU-0000001",
    "receipt_no": "20250115-00-00001",
    "receipt_date": "2025-01-15",
    "total_amount": 2000,
    "tax_amount": 275.86,
    "qr_code": "data:image/png;base64,...",
    "synced_to_kra": true
  },
  "meta": {
    "timestamp": "2025-01-15T14:30:30Z",
    "request_id": "req_abc123"
  }
}

{
  "status": "processing",
  "message": "Transaction is being processed",
  "data": {
    "transaction_id": "9d3f4b1a-7c8e-4d2f-b5a6-1e3c9f8d2b4a",
    "invoice_no": "C-USRU-0000001",
    "status": "pending"
  },
  "meta": {
    "timestamp": "2025-01-15T14:30:00Z",
    "request_id": "req_abc123",
    "check_status_url": "/api/v1/transactions/9d3f4b1a-7c8e-4d2f-b5a6-1e3c9f8d2b4a"
  }
}

{
  "status": "success",
  "data": {
    "transaction_id": "9d3f4b1a-7c8e-4d2f-b5a6-1e3c9f8d2b4a",
    "branch_id": "00",
    "invoice_no": "C-USRU-0000001",
    "receipt_no": "20250115-00-00001",
    "sale_date": "20250115",
    "sale_time": "143000",
    "payment_type": "CASH",
    "customer_name": "John Doe",
    "total_amount": 2000,
    "tax_amount": 275.86,
    "status": "success",
    "synced_to_kra": true,
    "items": [
      {
        "item_code": "KE2BXU0000001",
        "item_name": "Laptop Computer - HP ProBook 450",
        "quantity": 2,
        "unit_price": 1000,
        "supply_amount": 1724.14,
        "tax_type": "B",
        "tax_rate": 16,
        "tax_amount": 275.86,
        "total_amount": 2000
      }
    ],
    "qr_code": "data:image/png;base64,...",
    "created_at": "2025-01-15T14:30:00Z",
    "processed_at": "2025-01-15T14:30:05Z"
  }
}

{
  "status": "error",
  "message": "Sale transaction not found"
}

{
  "data": [
    {
      "transaction_id": "9d3f4b1a-7c8e-4d2f-b5a6-1e3c9f8d2b4a",
      "branch_id": "00",
      "invoice_no": "C-USRU-0000001",
      "receipt_no": "20250115-00-00001",
      "sale_date": "20250115",
      "customer_name": "John Doe",
      "total_amount": 2000,
      "status": "success",
      "synced_to_kra": true,
      "created_at": "2025-01-15T14:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total": 156,
    "total_pages": 4
  }
}

Tax Types: A (16%), B (0%), C (0%), D (0%), E (0%)

For each item:
  taxable_amount = supply_amount - discount_amount
  tax_amount = taxable_amount * tax_rate / 100

Totals are aggregated by tax type for VSCU submission.

const item = {
  quantity: 2,
  unit_price: 1000,
  supply_amount: 1724.14,     // 2000 ÷ 1.16 (tax-inclusive)
  discount_amount: 0,
  tax_type: 'B',              // 16% VAT
  tax_rate: 16,
  tax_amount: 275.86,         // 2000 - 1724.14
  total_amount: 2000          // 2 x 1000
};

const axios = require('axios');
 
const apiKey = process.env.CTAX_API_KEY;
const baseURL = 'https://c-ushuru.com/api/v1';
 
// Create sale (synchronous) - invoice_no is auto-generated if not provided
const sale = await axios.post(`${baseURL}/sales`, {
  branch_id: '00',
  sale_date: new Date().toISOString().slice(0,10).replace(/-/g,''),
  sale_time: new Date().toTimeString().slice(0,8).replace(/:/g,''),
  payment_type: 'CASH',
  customer_name: 'John Doe',
  items: [
    {
      item_seq: 1,
      item_code: 'KE2BXU0000001',
      item_class_code: '5020230201',
      item_name: 'Laptop Computer - HP ProBook 450',
      bcd: '8471000001234',
      pkg_unit_code: 'NT',
      pkg: 1,
      qty_unit_code: 'U',
      qty: 2,
      unit_price: 1000,
      supply_amount: 1724.14,
      discount_rate: 0,
      discount_amount: 0,
      tax_type: 'B',
      tax_rate: 16,
      tax_amount: 275.86,
      total_amount: 2000
    }
  ]
}, {
  headers: { 'Authorization': `Bearer ${apiKey}` }
});
 
console.log('Invoice:', sale.data.data.invoice_no); // e.g., C-USRU-0000001
console.log('Receipt:', sale.data.data.receipt_no);

// Submit sale asynchronously
const response = await axios.post(`${baseURL}/sales?async=true`, saleData, {
  headers: { 'Authorization': `Bearer ${apiKey}` }
});
 
const transactionId = response.data.data.transaction_id;
console.log('Transaction queued:', transactionId);
 
// Webhook will receive transaction.completed or transaction.failed event

// invoice_no is auto-generated if not provided
$data = [
    'branch_id' => '00',
    'sale_date' => date('Ymd'),
    'sale_time' => date('His'),
    'payment_type' => 'CASH',
    'customer_name' => 'John Doe',
    'items' => [
        [
            'item_seq' => 1,
            'item_code' => 'KE2BXU0000001',
            'item_class_code' => '5020230201',
            'item_name' => 'Laptop Computer - HP ProBook 450',
            'bcd' => '8471000001234',
            'pkg_unit_code' => 'NT',
            'pkg' => 1,
            'qty_unit_code' => 'U',
            'qty' => 2,
            'unit_price' => 1000,
            'supply_amount' => 1724.14,
            'discount_rate' => 0,
            'discount_amount' => 0,
            'tax_type' => 'B',
            'tax_rate' => 16,
            'tax_amount' => 275.86,
            'total_amount' => 2000,
        ],
    ],
];
 
$response = $client->post('/api/v1/sales', [
    'json' => $data,
    'headers' => ['Authorization' => 'Bearer ' . $apiKey],
]);
 
$result = json_decode($response->getBody(), true);
echo "Invoice: " . $result['data']['invoice_no']; // e.g., C-USRU-0000001
echo "Receipt: " . $result['data']['receipt_no'];

import requests
from datetime import datetime
import os
 
api_key = os.environ['CTAX_API_KEY']
base_url = 'https://c-ushuru.com/api/v1'
 
now = datetime.now()
# invoice_no is auto-generated if not provided
sale_data = {
    'branch_id': '00',
    'sale_date': now.strftime('%Y%m%d'),
    'sale_time': now.strftime('%H%M%S'),
    'payment_type': 'CASH',
    'customer_name': 'John Doe',
    'items': [{
        'item_seq': 1,
        'item_code': 'KE2BXU0000001',
        'item_class_code': '5020230201',
        'item_name': 'Laptop Computer - HP ProBook 450',
        'bcd': '8471000001234',
        'pkg_unit_code': 'NT',
        'pkg': 1,
        'qty_unit_code': 'U',
        'qty': 2,
        'unit_price': 1000,
        'supply_amount': 1724.14,
        'discount_rate': 0,
        'discount_amount': 0,
        'tax_type': 'B',
        'tax_rate': 16,
        'tax_amount': 275.86,
        'total_amount': 2000
    }]
}
 
response = requests.post(
    f'{base_url}/sales',
    json=sale_data,
    headers={'Authorization': f'Bearer {api_key}'}
)
 
result = response.json()
print(f"Invoice: {result['data']['invoice_no']}")  # e.g., C-USRU-0000001
print(f"Receipt: {result['data']['receipt_no']}")

{
  "status": "error",
  "message": "Invalid request data. Please check your input and try again.",
  "meta": {
    "timestamp": "2025-01-15T14:30:00Z",
    "request_id": "req_abc123"
  }
}

{
  "status": "error",
  "message": "Sale could not be processed. Please try again.",
  "data": {
    "transaction_id": "9d3f4b1a-7c8e-4d2f-b5a6-1e3c9f8d2b4a",
    "synced_to_kra": false,
    "can_retry": true
  },
  "meta": {
    "timestamp": "2025-01-15T14:30:30Z",
    "request_id": "req_abc123"
  }
}

{
  "status": "error",
  "message": "An error occurred while processing the sale. Please try again or contact support.",
  "meta": {
    "timestamp": "2025-01-15T14:30:00Z",
    "request_id": "req_abc123"
  }
}