Skip to Content
C-Tax v1.0 is now available
API ReferenceImports API

Imports API

Retrieve and manage imported items from the VSCU system for customs compliance.

Select Import Items

Retrieve imported items from VSCU based on the last request date.

POST /api/v1/imports/select-items

Headers

Authorization: Bearer YOUR_API_KEY
X-Branch-ID: YOUR_BRANCH_ID
Content-Type: application/json

Request Body

{
  "last_request_date": "20190524000000"
}

Field Descriptions

FieldTypeRequiredDescription
last_request_datestringYesLast request date in YYYYMMDDHHmmss format

Response

Status: 200 OK

{
  "status": "success",
  "data": {
    "items": [
      {
        "task_code": "2231943",
        "declaration_date": "20191217",
        "item_sequence": 1,
        "declaration_number": "C123456",
        "hs_code": "1231531231",
        "item_name": "Imported Product",
        "import_item_status_code": "1",
        "origin_nation_code": "CN",
        "export_nation_code": "CN",
        "package": 10.5,
        "package_unit_code": "CT",
        "quantity": 100,
        "quantity_unit_code": "U",
        "gross_weight": 150.5,
        "net_weight": 145.0,
        "supplier_name": "ABC Imports Ltd",
        "agent_name": "XYZ Customs Agent",
        "invoice_foreign_currency_amount": 5000.00,
        "invoice_foreign_currency": "USD",
        "invoice_foreign_currency_exchange_rate": 1.25
      }
    ],
    "total_items": 1,
    "result_code": "000",
    "result_message": "Success",
    "result_date": "20250107143000"
  },
  "meta": {
    "timestamp": "2025-01-07T14:30:00Z",
    "request_id": "req_123abc"
  }
}

Response Item Fields

FieldTypeDescription
task_codestringCustoms task code
declaration_datestringDeclaration date (YYYYMMDD)
item_sequenceintegerItem sequence number
declaration_numberstringCustoms declaration number
hs_codestringHarmonized System code
item_namestringItem description
import_item_status_codestringImport status code
origin_nation_codestringCountry of origin code
export_nation_codestringCountry of export code
packagenumberPackage quantity
package_unit_codestringPackage unit code
quantitynumberItem quantity
quantity_unit_codestringQuantity unit code
gross_weightnumberGross weight
net_weightnumberNet weight
supplier_namestringSupplier name
agent_namestringCustoms agent name
invoice_foreign_currency_amountnumberInvoice amount in foreign currency
invoice_foreign_currencystringForeign currency code
invoice_foreign_currency_exchange_ratenumberExchange rate

Update Import Item Status

Update the status of an imported item in the VSCU system.

POST /api/v1/imports/update-items

Headers

Authorization: Bearer YOUR_API_KEY
X-Branch-ID: YOUR_BRANCH_ID
Content-Type: application/json

Request Body

{
  "task_code": "2231943",
  "declaration_date": "20191217",
  "item_sequence": 1,
  "hs_code": "1231531231",
  "item_class_code": "5022110801",
  "item_code": "KE1NTXU0000001",
  "import_item_status_code": "1",
  "remark": "Item cleared for release",
  "modifier_name": "Admin",
  "modifier_id": "Admin"
}

Field Descriptions

FieldTypeRequiredDescription
task_codestringYesCustoms task code (max 50 chars)
declaration_datestringYesDeclaration date in YYYYMMDD format (8 chars)
item_sequenceintegerYesItem sequence number
hs_codestringYesHarmonized System code (max 17 chars)
item_class_codestringYesItem classification code (max 10 chars)
item_codestringYesItem code (max 20 chars)
import_item_status_codestringYesImport item status code (max 5 chars)
remarkstringNoOptional remark (max 400 chars)
modifier_namestringYesName of person updating (max 60 chars)
modifier_idstringYesID of person updating (max 20 chars)

Import Item Status Codes

Refer to the VSCU documentation section 4.18 for valid import item status codes.

Response

Status: 200 OK

{
  "status": "success",
  "message": "Import item status updated successfully",
  "data": {
    "result_code": "000",
    "result_message": "Successful",
    "result_date": "20250107143023"
  },
  "meta": {
    "timestamp": "2025-01-07T14:30:23Z",
    "request_id": "req_456def"
  }
}

Error Responses

422 Unprocessable Entity

Validation error:

{
  "status": "error",
  "message": "Invalid request data",
  "errors": {
    "task_code": [
      "The task code field is required."
    ],
    "declaration_date": [
      "The declaration date must be 8 characters."
    ]
  }
}

400 Bad Request

VSCU error:

{
  "status": "error",
  "message": "VSCU processing failed",
  "error": "Item not found in VSCU system"
}

500 Internal Server Error

Server error:

{
  "status": "error",
  "message": "An error occurred while retrieving import items",
  "error": "Internal server error"
}

Code Examples

PHP

// Select import items
$data = [
    'last_request_date' => date('YmdHis', strtotime('-30 days')),
];
 
$response = $client->post('/api/v1/imports/select-items', [
    'json' => $data,
    'headers' => [
        'Authorization' => 'Bearer ' . $apiKey,
        'X-Branch-ID' => '01',
    ],
]);
 
$items = $response->json()['data']['items'];
 
// Update import item status
$updateData = [
    'task_code' => '2231943',
    'declaration_date' => '20191217',
    'item_sequence' => 1,
    'hs_code' => '1231531231',
    'item_class_code' => '5022110801',
    'item_code' => 'KE1NTXU0000001',
    'import_item_status_code' => '1',
    'remark' => 'Item cleared',
    'modifier_name' => 'John Doe',
    'modifier_id' => 'admin123',
];
 
$response = $client->post('/api/v1/imports/update-items', [
    'json' => $updateData,
    'headers' => [
        'Authorization' => 'Bearer ' . $apiKey,
        'X-Branch-ID' => '01',
    ],
]);

JavaScript

// Select import items
const lastRequestDate = moment().subtract(30, 'days').format('YYYYMMDDHHmmss');
 
const selectResponse = await axios.post('/api/v1/imports/select-items',
  { last_request_date: lastRequestDate },
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'X-Branch-ID': '01'
    }
  }
);
 
const items = selectResponse.data.data.items;
 
// Update import item status
const updateData = {
  task_code: '2231943',
  declaration_date: '20191217',
  item_sequence: 1,
  hs_code: '1231531231',
  item_class_code: '5022110801',
  item_code: 'KE1NTXU0000001',
  import_item_status_code: '1',
  remark: 'Item cleared',
  modifier_name: 'John Doe',
  modifier_id: 'admin123'
};
 
const updateResponse = await axios.post('/api/v1/imports/update-items',
  updateData,
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'X-Branch-ID': '01'
    }
  }
);

cURL

# Select import items
curl -X POST https://c-tax.1809ltd.co.ke/api/v1/imports/select-items \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Branch-ID: 01" \
  -H "Content-Type: application/json" \
  -d '{
    "last_request_date": "20190524000000"
  }'
 
# Update import item status
curl -X POST https://c-tax.1809ltd.co.ke/api/v1/imports/update-items \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Branch-ID: 01" \
  -H "Content-Type: application/json" \
  -d '{
    "task_code": "2231943",
    "declaration_date": "20191217",
    "item_sequence": 1,
    "hs_code": "1231531231",
    "item_class_code": "5022110801",
    "item_code": "KE1NTXU0000001",
    "import_item_status_code": "1",
    "remark": "Item cleared for release",
    "modifier_name": "Admin",
    "modifier_id": "Admin"
  }'

Best Practices

  1. Regular Synchronization - Retrieve import items regularly to stay up-to-date with customs data
  2. Store Last Request Date - Save the last successful request date for incremental updates
  3. Validate Status Codes - Ensure import item status codes are valid before submission
  4. Error Handling - Implement proper error handling for VSCU connection issues
  5. Branch Context - Always specify the correct branch ID in headers
  6. Audit Trail - Record modifier name and ID for compliance tracking
  7. Item Matching - Verify item codes exist in your system before updating status

Use Cases

Customs Compliance Workflow

  1. Retrieve Pending Items: Call select-items to get new imported items
  2. Process Clearance: Review items and obtain customs clearance
  3. Update Status: Call update-items to update item status in VSCU
  4. Inventory Integration: Add cleared items to inventory system

Periodic Synchronization

// Sync every hour
setInterval(async () => {
  const lastSync = await getLastSyncDate();
  const response = await syncImportItems(lastSync);
 
  if (response.data.items.length > 0) {
    await processNewImports(response.data.items);
    await saveLastSyncDate(response.data.result_date);
  }
}, 3600000); // 1 hour

VSCU Integration

These endpoints integrate with the VSCU (Virtual SDC Unit) system:

  • Select Items Endpoint: /imports/selectImportItems
  • Update Items Endpoint: /imports/updateImportItems

All requests are forwarded to VSCU with proper authentication and branch context. Responses include VSCU result codes and messages for troubleshooting.

Notes

  • Import items are managed at the branch level; ensure the correct branch ID is specified
  • The last_request_date should be stored and used for incremental synchronization
  • Import item status codes must match VSCU specifications (see section 4.18)
  • All dates use YYYYMMDD format, and datetimes use YYYYMMDDHHmmss format
  • Exchange rates and amounts are stored for audit and reporting purposes
Last updated on
Stock APITransactions API