@extends('layouts.admin') @section('title', 'API Documentation') @section('content')

API Documentation

Export Postman Collection
Quick Start
Base URL
{{ url('/api/v1') }}
Authentication

Most endpoints require API key authentication:

Authorization: Bearer YOUR_API_KEY
Response Format
{
    "success": true,
    "data": { ... },
    "message": "Operation successful"
}
Error Format
{
    "success": false,
    "error": "Error message",
    "code": 400
}
Tax Calculation API
GET /api/v1/tax-calculate Public
Description

Calculate import taxes for goods based on HS code, value, and other parameters.

Parameters
Parameter Type Required Description Example
hs_code string Yes HS Code of the product 870321
cif_value number Yes CIF value in KES 1500000
country_of_origin string Yes ISO country code CN
weight_kg number Optional Weight in kilograms 1500
description string Optional Product description Passenger vehicles
currency string Optional Currency code (default: KES) USD
Example Request
GET {{ url('/api/v1/tax-calculate') }}?hs_code=870321&cif_value=1500000&country_of_origin=CN&weight_kg=1500
Example Response
{
    "success": true,
    "data": {
        "calculation_id": "calc_123456",
        "hs_code": "870321",
        "description": "Passenger motor vehicles",
        "cif_value": 1500000,
        "country_of_origin": "CN",
        "tax_breakdown": {
            "import_duty": {
                "rate": 25,
                "amount": 375000,
                "type": "percentage"
            },
            "vat": {
                "rate": 16,
                "amount": 300000,
                "base": 1875000
            },
            "excise_duty": {
                "rate": 20,
                "amount": 375000,
                "applicable": true
            }
        },
        "total_taxes": 1050000,
        "total_payable": 2550000,
        "calculation_steps": [...],
        "timestamp": "2024-01-15T10:30:00Z"
    },
    "message": "Tax calculation completed successfully"
}
HS Codes API
GET /api/v1/hs-codes Public

Retrieve all HS codes with their tax configurations.

Parameters
Parameter Type Required Description
search string Optional Search by HS code or description
page integer Optional Page number for pagination
per_page integer Optional Items per page (default: 20)
Example Response
{
    "success": true,
    "data": {
        "data": [
            {
                "hs_code": "870321",
                "description": "Passenger motor vehicles",
                "default_duty_type": "percentage",
                "default_duty_value": 25,
                "excise_applicable": true,
                "sensitive": false
            }
        ],
        "current_page": 1,
        "total": 1500
    }
}
GET /api/v1/hs-codes/{code} Public

Retrieve detailed information for a specific HS code.

Example Request
GET {{ url('/api/v1/hs-codes/870321') }}
Example Response
{
    "success": true,
    "data": {
        "hs_code": "870321",
        "description": "Passenger motor vehicles with spark-ignition engine",
        "default_duty_type": "percentage",
        "default_duty_value": 25,
        "excise_applicable": true,
        "excise_formula": {
            "rate": 20,
            "minimum": 0
        },
        "sensitive": false,
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z",
        "benchmarks": [...],
        "country_overrides": [...]
    }
}
Reference Data APIs
GET /api/v1/countries Public

Get list of supported countries with their codes and trade agreements.

Example Response
{
    "success": true,
    "data": [
        {
            "code": "CN",
            "name": "China",
            "region": "Asia",
            "trade_agreement": "none"
        }
    ]
}
GET /api/v1/currencies Public

Get supported currencies and their current exchange rates.

Example Response
{
    "success": true,
    "data": [
        {
            "code": "USD",
            "name": "US Dollar",
            "exchange_rate": 157.50,
            "updated_at": "2024-01-15T10:00:00Z"
        }
    ]
}
GET /api/v1/exchange-rates Public

Get current exchange rates against KES.

Authenticated APIs
These endpoints require API key authentication. Contact administrators to get your API key.
POST /api/v1/bulk-calculate Authenticated

Perform multiple tax calculations in a single request.

Request Body
{
    "calculations": [
        {
            "hs_code": "870321",
            "cif_value": 1500000,
            "country_of_origin": "CN",
            "weight_kg": 1500
        },
        {
            "hs_code": "030211",
            "cif_value": 500000,
            "country_of_origin": "JP",
            "weight_kg": 1000
        }
    ]
}
Headers
Authorization: Bearer your_api_key_here
GET /api/v1/calculation-history Authenticated

Retrieve calculation history for your account.

Parameters
Parameter Type Required Description
date_from string Optional Filter from date (YYYY-MM-DD)
date_to string Optional Filter to date (YYYY-MM-DD)
Error Codes
Code Message Description
400 Bad Request Invalid parameters or missing required fields
401 Unauthorized Missing or invalid API key
403 Forbidden API key doesn't have permission for this endpoint
404 Not Found HS code or resource not found
422 Unprocessable Entity Validation errors in request data
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server-side error
Rate Limiting
Public Endpoints
  • 60 requests per minute per IP address
  • Applies to tax calculation and data lookup endpoints
Authenticated Endpoints
  • 1000 requests per hour per API key
  • Higher limits available for enterprise plans
Exceeding rate limits will result in 429 Too Many Requests responses.
@endsection @push('styles') @endpush