Introduction

The Railway Consignment Note (RCN) API extracts structured data from CIM and SMGS rail consignment notes using advanced OCR and machine learning. Purpose-built for the China-Laos-Thailand (CLT) corridor and ASEAN cross-border rail freight, the API handles the complexity of multi-format, multi-language railway documentation with enterprise-grade accuracy.

The API supports both CIM (Convention concerning International Carriage by Rail, used across Europe) and SMGS (Agreement on International Goods Transport by Rail, used across Russia, CIS states, and China) consignment note formats. Multi-language OCR capabilities cover Chinese (Simplified and Traditional), Thai, English, Russian, and Lao scripts simultaneously within a single document.

Key capabilities include automatic format detection (CIM vs SMGS), Mohan/Boten border crossing data extraction, wagon and container tracking, customs declaration parsing, HS code identification, and seal number verification. The API returns 40+ structured fields with per-field confidence scores, enabling seamless integration with freight management, customs clearance, and logistics tracking systems.

Supported file formats: PDF, JPEG, PNG, TIFF (max 20 MB per file). Average processing time: 1.2-2.8 seconds depending on document complexity and number of languages detected.

Authentication

All API requests must include a valid API key in the Authorization header using the Bearer token scheme. API keys are scoped to your organization and can be created, rotated, and revoked from the dashboard.

Authorization: Bearer YOUR_API_KEY

Obtain your API key from dashboard.kabytech.com → Settings → API Keys. Each key can be assigned granular permissions (read, write, batch) and rate limit tiers. We recommend creating separate keys for development and production environments.

Security best practices:

• Never expose API keys in client-side code or public repositories
• Rotate keys every 90 days or immediately if compromised
• Use environment variables or a secrets manager to store keys
• Enable IP allowlisting for production keys in the dashboard

Quick Start

Parse a railway consignment note in seconds. Upload a CIM or SMGS document and receive structured JSON with 40+ extracted fields, confidence scores, and processing metadata.

curl -X POST https://api.kabytech.com/v1/rcn/parse \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/consignment-note.pdf" \
  -F "language=zh" \
  -F "format_hint=smgs"

The API automatically detects whether the document is CIM or SMGS format. For optimal accuracy on multi-language documents (e.g., Chinese-English or Russian-English), pass the primary language as the language parameter. The OCR engine will still detect and extract text in secondary languages.

Example response for a Kunming-Vientiane-Laem Chabang auto parts shipment:

{
  "id": "job_rcn_8f3a2b1c9d4e",
  "status": "completed",
  "document_type": "rcn",
  "format_detected": "smgs",
  "data": {
    "consignment_number": "RCNKBT2026005678",
    "format": "smgs",
    "date_of_consignment": "2026-03-15",
    "sender": {
      "name": "Kunming Precision Auto Parts Co., Ltd.",
      "address": "88 Dianchi Road, Xishan District, Kunming, Yunnan 650228",
      "country": "CN",
      "contact_phone": "+86-871-6812-3456"
    },
    "recipient": {
      "name": "Laem Chabang Auto Distribution Co., Ltd.",
      "address": "456 Port Road, Si Racha, Chonburi 20230, Thailand",
      "country": "TH",
      "contact_phone": "+66-38-491-2345"
    },
    "station_from": {
      "name": "Kunming South",
      "code": "KMS",
      "country": "CN"
    },
    "station_to": {
      "name": "Laem Chabang",
      "code": "LCB",
      "country": "TH"
    },
    "route_via": ["Yuxi", "Mohan", "Boten", "Luang Prabang", "Vientiane", "Nong Khai", "Laem Chabang"],
    "wagon_number": "KZ4-5678901",
    "wagon_type": "covered",
    "container_numbers": ["KBTU2234567", "KBTU2234568"],
    "goods_description": "Automotive brake assemblies and suspension components, new, in cartons",
    "hs_code": "8708.30",
    "gross_weight": "24800 kg",
    "net_weight": "23200 kg",
    "number_of_packages": 480,
    "customs_declaration_number": "CD-2026-KM-001234",
    "seal_numbers": ["KBTS-20260315-001", "KBTS-20260315-002", "CN-CUSTOMS-887654"],
    "border_crossing": {
      "primary": { "checkpoint": "Mohan", "country_from": "CN", "country_to": "LA" },
      "secondary": { "checkpoint": "Nong Khai", "country_from": "LA", "country_to": "TH" }
    },
    "estimated_arrival": "2026-03-18T14:00:00+07:00",
    "freight_charges": { "currency": "CNY", "amount": 45600.00, "terms": "prepaid" },
    "special_declarations": "Fragile - Handle with care. Keep dry.",
    "document_language": "zh",
    "ocr_languages_detected": ["zh", "en"]
  },
  "confidence": 0.96,
  "field_confidences": {
    "consignment_number": 0.99,
    "sender.name": 0.97,
    "goods_description": 0.94,
    "hs_code": 0.95,
    "seal_numbers": 0.92
  },
  "processing_time_ms": 2140,
  "pages_processed": 3
}

POST /v1/rcn/parse

Upload a railway consignment note (CIM or SMGS format) for parsing. The API accepts PDF, JPEG, PNG, and TIFF files up to 20 MB. Multi-page documents are fully supported — the parser correlates data across all pages to build a complete extraction.

For documents containing multiple languages (common in CLT corridor shipments), the OCR engine automatically detects and processes all present scripts. Passing the language parameter as the primary language improves extraction accuracy for ambiguous characters.

Request Parameters

Response Fields

GET /v1/rcn/{id}

Retrieve the parsed results for a previously submitted railway consignment note by its job ID. This endpoint is especially useful when the initial parse request returned a "processing" status, indicating the document is still being analyzed.

Results are retained for 30 days after parsing. After this period, the job ID expires and a 404 error is returned.

Path Parameters

Query Parameters

curl https://api.kabytech.com/v1/rcn/job_rcn_8f3a2b1c9d4e \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G -d "include_raw=false" -d "fields=consignment_number,sender,station_from,station_to,route_via"

{
  "id": "job_rcn_8f3a2b1c9d4e",
  "status": "completed",
  "document_type": "rcn",
  "format_detected": "smgs",
  "data": {
    "consignment_number": "RCNKBT2026005678",
    "sender": {
      "name": "Kunming Precision Auto Parts Co., Ltd.",
      "address": "88 Dianchi Road, Xishan District, Kunming, Yunnan 650228",
      "country": "CN"
    },
    "station_from": { "name": "Kunming South", "code": "KMS", "country": "CN" },
    "station_to": { "name": "Laem Chabang", "code": "LCB", "country": "TH" },
    "route_via": ["Yuxi", "Mohan", "Boten", "Luang Prabang", "Vientiane", "Nong Khai", "Laem Chabang"]
  },
  "confidence": 0.96,
  "processing_time_ms": 2140
}

POST /v1/rcn/batch

Submit up to 50 railway consignment notes for batch processing. Batch parsing is ideal for processing daily manifests, customs declaration packages, or historical document digitization. Each file is processed independently and results are aggregated.

Batch jobs always run asynchronously. Use the returned batch_id to poll for results or provide a webhook_url to receive a callback when all documents are complete.

Request Parameters

curl -X POST https://api.kabytech.com/v1/rcn/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files[]=@consignment-001.pdf" \
  -F "files[]=@consignment-002.pdf" \
  -F "files[]=@consignment-003.pdf" \
  -F "language=zh" \
  -F "format_hint=smgs" \
  -F "webhook_url=https://your-server.com/webhooks/rcn-batch"

{
  "batch_id": "batch_rcn_7k2m9x4p",
  "status": "processing",
  "total_files": 3,
  "completed": 0,
  "failed": 0,
  "estimated_completion_seconds": 12,
  "results_url": "https://api.kabytech.com/v1/rcn/batch/batch_rcn_7k2m9x4p"
}

GET /v1/status

Health check endpoint for the RCN parsing service. Returns current operational status, API version, and queue depth. This endpoint does not require authentication and can be used for monitoring and uptime checks.

curl https://api.kabytech.com/v1/status

{
  "service": "rcn-parser",
  "status": "operational",
  "version": "2.4.1",
  "queue_depth": 7,
  "avg_processing_time_ms": 2050,
  "supported_formats": ["cim", "smgs"],
  "ocr_languages": ["zh", "en", "th", "lo", "ru"],
  "uptime_percent": 99.97,
  "last_incident": "2026-02-10T03:22:00Z"
}

RCN Sections Reference

Railway consignment notes (both CIM and SMGS formats) are organized into standardized sections. The API maps extracted data to these logical sections, making it easy to access specific parts of the document. Each section contains related fields grouped by their function in the consignment note.

Header Section

Core identification fields at the top of the consignment note.

Sender / Recipient Section

Parties involved in the consignment. Both CIM and SMGS formats capture sender (consignor) and recipient (consignee) details, though field positions differ between formats.

Route Section

Origin and destination stations, intermediate routing, and border crossing points. The CLT corridor typically routes through Mohan (China) / Boten (Laos) and Nong Khai (Thailand) / Thanaleng (Laos) border crossings.

Wagon Details Section

Information about the railway wagon(s) and containers used for transport.

Goods and Weight Section

Description of goods, quantities, and weight measurements.

Customs Section

Customs and border clearance data extracted from the consignment note.

Seals Section

Seal numbers applied to wagons and containers for security verification. The API extracts seal numbers from both printed text and photographed seal images.

Response Field Reference

Complete reference of all 40+ fields extracted from railway consignment notes. Each field includes a confidence score (0.0 to 1.0) available in the field_confidences object. Fields not present on the source document are returned as null.

Error Codes

The API returns standard HTTP status codes along with a JSON error body containing a machine-readable code and a human-readable message. Use the code field for programmatic error handling.

Rate Limits

Rate limits are applied per API key and vary by plan tier. Limits are enforced using a sliding window algorithm. The API returns rate limit headers with every response:

• X-RateLimit-Limit — Maximum requests allowed per minute
• X-RateLimit-Remaining — Requests remaining in the current window
• X-RateLimit-Reset — Unix timestamp when the window resets
• Retry-After — Seconds to wait before retrying (only on 429 responses)

Official SDKs

KabyTech provides official SDKs for popular languages to simplify integration with the RCN API. All SDKs handle authentication, retries, file uploads, and response parsing automatically.

# Python
pip install kabytech
from kabytech import KabyTech
client = KabyTech(api_key="YOUR_API_KEY")
result = client.rcn.parse("consignment-note.pdf", language="zh", format_hint="smgs")
print(result.data.consignment_number)
print(result.data.sender.name)
print(result.data.route_via)

// Node.js
npm install @kabytech/sdk
const { KabyTech } = require("@kabytech/sdk");
const client = new KabyTech({ apiKey: "YOUR_API_KEY" });
const result = await client.rcn.parse("consignment-note.pdf", {
  language: "zh",
  formatHint: "smgs",
  validateRoute: true
});
console.log(result.data.consignmentNumber);
console.log(result.data.sender.name);
console.log(result.data.borderCrossing.primary.checkpoint);

Additional SDKs available: Go (go get github.com/kabytech/kabytech-go), Java (Maven Central: com.kabytech:kabytech-sdk), PHP (composer require kabytech/sdk). Full SDK documentation is available at docs.kabytech.com/sdks.