ERGE ASIA — External Shipping API Documentation

Overview

ERGE ASIA Shipping API allows third-party applications to integrate with our international shipping network. Ship packages from Indonesia to 50+ destination countries with automated rate calculation, real-time tracking, and secure payment via wallet system.

Integration Flow

1. Get API Key → 2. Get Countries & Couriers → 3. Calculate Rate → 4. Create Shipment → 5. Track Package

Key Features

Ship to 50+ countries across Asia, Middle East, Europe, Americas, and Oceania
Multiple courier options per destination country
Multi-colly (multi-package) support for complex shipments
Real-time tracking with 18-stage status updates
Automatic rate calculation based on weight, destination, and item category
Domestic pickup quote — combine home-to-warehouse pickup with international shipping in one total (send origin_subdistrict_id to /rates/calculate)
Wallet-based payment — top up once, ship multiple times
Webhook notifications for tracking status changes

Authentication

All API requests (except Tracking) require your API Key as a Bearer token in the header. Get your key yourself from your dashboard: Profile → API Saya.

HTTP Header
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

ℹ️

Getting your API Key
Log in to system.ergeasia.com, open Profile → API Saya. You get a ea_test_ key for sandbox and an ea_live_ key for production. Each key is tied to your wallet. The mode (sandbox vs live) is set by the key prefix, not a different URL.

Example — cURL

cURL
curl -X GET "https://system.ergeasia.com/api/external/v1/countries" \
  -H "Authorization: Bearer ea_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Environments

The base URL is the same for both environments. The mode is determined by your API key prefix, not by a different URL.

Environment	Base URL	Activated by	Description
Sandbox	`https://system.ergeasia.com/api/external/v1`	`ea_test_...` key	Testing — dummy balance, no real charges, no vendor calls
Production	`https://system.ergeasia.com/api/external/v1`	`ea_live_...` key	Live — real wallet deductions

Error Handling

All responses use a consistent structure. Errors include an error code and a human-readable message.

Response Format

Success Response
{
  "success": true,
  "data": { ... }
}

Error Response
{
  "success": false,
  "error_code": "INSUFFICIENT_BALANCE",
  "message": "Wallet balance is not enough"
}

HTTP Status Codes

Code	Meaning
200	Success
400	Bad Request — Invalid parameters or missing required fields
401	Unauthorized — Invalid or missing API key
403	Forbidden — Insufficient permissions
404	Not Found — Resource does not exist
422	Unprocessable — Validation error (e.g., rate not found)
429	Too Many Requests — Rate limit exceeded
500	Internal Server Error

Error Codes

Error Code	Description
`INVALID_AUTH`	API key is invalid or expired
`MISSING_FIELD`	A required field is missing
`INVALID_COUNTRY`	Destination country is not supported
`INVALID_COURIER`	Courier is not active or doesn't serve this route
`RATE_NOT_FOUND`	No rate available for this route/weight/category
`INSUFFICIENT_BALANCE`	Wallet balance is too low for this shipment
`WEIGHT_EXCEEDED`	Package weight exceeds maximum (100kg)
`CATEGORY_MISMATCH`	Items across collies have mixed categories
`AWB_NOT_FOUND`	AWB number not found in the system

Rate Limits

Standard Plan

100 requests/minute, 5,000 requests/day

Premium Plan

500 requests/minute, 50,000 requests/day

⚠️

Rate limit headers are included in every response: X-RateLimit-Remaining and X-RateLimit-Reset.

Endpoints

GET /v1/countries Available Destination Countries

Returns the list of all supported destination countries with available shipping routes.

Response

JSON Response
{
  "success": true,
  "data": [
    { "code": "TW", "name": "Taiwan" },
    { "code": "SG", "name": "Singapore" },
    { "code": "JP", "name": "Japan" },
    { "code": "MY", "name": "Malaysia" },
    { "code": "SA", "name": "Saudi Arabia" },
    // ... more countries
  ]
}

GET /v1/couriers?country_code={code} Available Couriers

Returns the list of available couriers for a specific destination country. If no country is specified, returns all active couriers.

Query Parameters

Param	Type	Required	Description
country_code	string	Optional	ISO 2-letter country code to filter couriers that serve this route

Response

JSON Response
{
  "success": true,
  "data": [
    {
      "code": "ERGE",
      "name": "Erge Asia",
      "description": "International Express Shipping"
    }
  ],
  "count": 1
}

POST /v1/rates/calculate Calculate Shipping Rate

Calculate shipping cost before creating a shipment. Returns the final rate after tier discounts are applied.

Request Body

Field	Type	Required	Description
country_code	string	Required	Destination country ISO code (e.g., "TW")
courier_code	string	Required	Courier code from `/v1/couriers`
weight	number	Required	Total package weight in kg (max: 100)
items	array	Required	List of items (determines category pricing)
items[].name	string	Required	Item description
items[].quantity	integer	Required	Quantity
items[].category	string	Required	One of: `general_cargo`, `sensitif_items`, `electronic`
delivery_type	string	Optional	`home` (default) or `store`. Store adds Rp 50,000/colly fee, max 5kg/colly
collies	array	Optional	Multi-colly breakdown. If omitted, single colly with total weight is used

Request Example

JSON Request
{
  "country_code": "TW",
  "courier_code": "ERGE",
  "weight": 2,
  "delivery_type": "home",
  "items": [
    {
      "name": "Snack Indomie",
      "quantity": 10,
      "category": "general_cargo"
    }
  ]
}

Response

JSON Response
{
  "success": true,
  "data": {
    "country": "Taiwan",
    "country_code": "TW",
    "courier": { "code": "ERGE", "name": "Erge Asia" },
    "category": { "code": "general_cargo", "name": "Barang Umum" },
    "weight": 2,
    "rounded_weight": 2,
    "delivery_type": "home",
    "pricing": {
      "shipping_cost": 140700,
      "store_fee": 0,
      "total_cost": 140700
    },
    "tier": {
      "name": "Bronze",
      "discount_percent": 3
    },
    "wallet": {
      "sufficient": true,
      "balance": 5000000,
      "required": 140700
    },
    "formatted": {
      "shipping_cost": "Rp 140.700",
      "total_cost": "Rp 140.700",
      "wallet_balance": "Rp 5.000.000"
    }
  }
}

ℹ️

Tier Discounts are automatically applied based on your account's membership tier. Higher tiers enjoy bigger discounts. Tiers upgrade automatically as your total shipping spending increases.

POST /v1/shipments Create Shipment

Create a new shipment. The cost is automatically calculated and deducted from your wallet balance. Returns the AWB (Air Waybill) number for tracking.

⚠️

Important: This endpoint deducts your wallet balance immediately. Always call /v1/rates/calculate first to confirm pricing. Ensure sufficient wallet balance before calling.

Request Body

Field	Type	Required	Description
sender_name	string	Required	Sender's full name
sender_phone	string	Required	Sender's phone number
sender_location	string	Required	Sender's city/area in Indonesia (e.g., "DKI Jakarta")
receiver_country	string	Required	Destination country name or ISO code
receiver_name	string	Required	Receiver's full name
receiver_phone	string	Required	Receiver's phone number (include country code)
receiver_postal	string	Required	Receiver's postal code
receiver_address	string	Required	Full delivery address
receiver_id	string	Conditional	Receiver's ID/Passport number. Required for Taiwan
receiver_email	string	Optional	Receiver's email address
package_weight	number	Required	Total weight in kg (max: 100)
courier_service	string	Required	Courier code from `/v1/couriers`
delivery_type	string	Optional	`home` (default) or `store`
items	array	Required	At least 1 item. See Item Object below
collies	array	Optional	Multi-colly details. See Colly Object below
voucher_code	string	Optional	Discount voucher code (if available)

Item Object

Field	Type	Required	Description
name	string	Required	Item description (e.g., "Indomie Goreng")
quantity	integer	Required	Quantity
unit	string	Optional	Unit of measure: pcs, box, pack, kg, etc.
price	number	Required	Unit price in IDR (for customs declaration)
category	string	Required	See Item Categories

Colly Object (for Multi-Package)

Field	Type	Required	Description
weight	number	Required	Weight of this colly in kg
items	array	Required	Items in this colly (same Item Object format)

🚫

Category Mixing Not Allowed: All collies in a single shipment must contain items of the same category. If you have mixed categories, create separate shipments.

Request Example

JSON Request
{
  "sender_name": "Rifki Fauzi",
  "sender_phone": "0811980108",
  "sender_location": "DKI Jakarta",
  "receiver_country": "TW",
  "receiver_name": "Chen Wei",
  "receiver_phone": "886912345678",
  "receiver_id": "A123456789",
  "receiver_postal": "10617",
  "receiver_address": "No. 7, Section 5, Xinyi Rd, Xinyi District, Taipei City",
  "package_weight": 3,
  "courier_service": "ERGE",
  "delivery_type": "home",
  "items": [
    {
      "name": "Indomie Goreng",
      "quantity": 20,
      "unit": "pcs",
      "price": 3500,
      "category": "general_cargo"
    },
    {
      "name": "Sambal ABC",
      "quantity": 5,
      "unit": "pcs",
      "price": 15000,
      "category": "general_cargo"
    }
  ]
}

Success Response

JSON Response — 200 OK
{
  "success": true,
  "message": "Shipment created successfully",
  "data": {
    "shipment_id": 12345,
    "awb_number": "88826028HXDYD",
    "status": "submitted",
    "courier": "Erge Asia",
    "delivery_type": "home",
    "category": "Barang Umum",
    "colly_count": 1,
    "colly_awbs": ["88826028HXDYD"],
    "pricing": {
      "shipping_cost": 211000,
      "discount": 0,
      "store_fee": 0,
      "total_cost": 211000,
      "total_formatted": "Rp 211.000"
    },
    "wallet_balance": 4789000
  }
}

GET /v1/shipments/{id} Get Shipment Detail

Retrieve full details of a specific shipment by ID or AWB number.

Path Parameters

Param	Type	Description
id	string	Shipment ID or AWB number

Response

JSON Response
{
  "success": true,
  "data": {
    "id": 12345,
    "awb_number": "88826028HXDYD",
    "status": "submitted",
    "sender": {
      "name": "Rifki Fauzi",
      "phone": "0811980108",
      "location": "DKI Jakarta"
    },
    "receiver": {
      "name": "Chen Wei",
      "phone": "886912345678",
      "country": "Taiwan",
      "country_code": "TW",
      "postal_code": "10617",
      "address": "No. 7, Section 5, Xinyi Rd..."
    },
    "package": {
      "weight": 3,
      "colly_count": 1,
      "delivery_type": "home"
    },
    "courier": "Erge Asia",
    "pricing": {
      "shipping_cost": 211000,
      "discount": 0,
      "total_cost": 211000
    },
    "items": [
      {
        "name": "Indomie Goreng",
        "quantity": 20,
        "unit": "pcs",
        "price": 3500,
        "category": "general_cargo"
      }
    ],
    "payment_status": "paid",
    "created_at": "2026-02-23T10:39:37+07:00"
  }
}

GET /v1/shipments List Shipments

List all shipments for your account with pagination and optional filters.

Query Parameters

Param	Type	Default	Description
page	integer	1	Page number
per_page	integer	20	Items per page (max: 100)
status	string	—	Filter by status: submitted, in_process, verified, completed, cancelled
country_code	string	—	Filter by destination country
from_date	string	—	Filter from date (YYYY-MM-DD)
to_date	string	—	Filter to date (YYYY-MM-DD)

Response

JSON Response
{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 47,
    "total_pages": 3
  }
}

GET /v1/tracking/{awb_number} Track Shipment

Get real-time tracking history for a shipment. This endpoint is public — no authentication required. Tracking data is fetched from ERGE ASIA's internal system and synced with the carrier network automatically.

🔓

Public Endpoint: This endpoint can be called without authentication. You can embed tracking directly into your customer-facing pages.

Path Parameters

Param	Type	Description
awb_number	string	AWB number from shipment creation

Response

JSON Response
{
  "success": true,
  "data": {
    "awb_number": "88826028HXDYD",
    "destination": "Taiwan",
    "receiver": "Chen Wei",
    "weight": "3 kg",
    "current_status": "IN_TRANSIT",
    "current_status_name": "Dalam Perjalanan ke Negara Tujuan",
    "history": [
      {
        "status_code": "DELIVERED",
        "status_name": "Kiriman Telah Diterima",
        "status_name_en": "Delivered",
        "location": "Taipei City, Taiwan",
        "description": "Signed by: Chen Wei",
        "timestamp": "2026-02-28T14:30:00+08:00"
      },
      {
        "status_code": "OUT_FOR_DELIVERY",
        "status_name": "Sedang Dikirim ke Alamat Penerima",
        "status_name_en": "Out for Delivery",
        "location": "Taipei City, Taiwan",
        "description": null,
        "timestamp": "2026-02-28T08:15:00+08:00"
      },
      {
        "status_code": "ARRIVED_DESTINATION",
        "status_name": "Kiriman Telah Sampai di Negara Tujuan",
        "status_name_en": "Arrived at Destination Country",
        "location": "Taiwan",
        "description": null,
        "timestamp": "2026-02-26T22:00:00+08:00"
      },
      // ... more history entries (newest first)
    ]
  }
}

Tracking Statuses

Complete list of tracking status codes your shipment may go through. Statuses appear in chronological order in the tracking history.

Status Code	Indonesian	English
AWB_CREATED	Airwaybill Berhasil Dibuat	AWB Created
PAYMENT_COMPLETED	Pembayaran Berhasil	Payment Confirmed
PICKED_UP	Kiriman Telah Dijemput	Picked Up
WAREHOUSE_RECEIVED	Diterima di Gudang Jakarta	Received at Jakarta Warehouse
STAFF_VERIFIED	Kiriman Berhasil Diverifikasi	Shipment Verified
PROCESSING	Sedang Diproses di Gudang	Processing at Warehouse
DEPARTED_ORIGIN	Berangkat dari Indonesia	Departed from Indonesia
IN_TRANSIT	Dalam Perjalanan ke Negara Tujuan	In Transit to Destination
ARRIVED_DESTINATION	Telah Sampai di Negara Tujuan	Arrived at Destination Country
CUSTOMS_CLEARANCE	Proses Bea Cukai	Customs Clearance
CUSTOMS_RELEASED	Lolos Bea Cukai	Customs Released
LOCAL_SORTING	Sorting di Fasilitas Lokal	Local Sorting Facility
OUT_FOR_DELIVERY	Sedang Dikirim ke Alamat Penerima	Out for Delivery
DELIVERY_ATTEMPT	Percobaan Pengiriman (Penerima Tidak Ada)	Delivery Attempted
DELIVERED	Kiriman Telah Diterima	Delivered
RETURNED	Kiriman Dikembalikan	Returned to Sender
ON_HOLD	Kiriman Ditahan	On Hold
CANCELLED	Kiriman Dibatalkan	Cancelled

Item Categories

Each item must be assigned a category. The category determines the shipping rate applied (higher categories may have higher rates).

Code	Label	Alias Inputs	Description
`general_cargo`	Barang Umum	`makanan`, `fashion`, `lainnya`	General items: food, clothing, accessories, books, souvenirs, household items
`sensitif_items`	Sensitif Items	`obat`, `boci`	Sensitive items: medicine, boci, ikan asin, kripik terbuat dari daging
`electronic`	Elektronik	`elektronik`	Electronic items: phones, laptops, batteries, electronic accessories

ℹ️

Category Priority: When items of different categories exist in a colly, the highest priority category is applied: electronic > sensitif_items > general_cargo. You may also use the alias inputs (e.g., "makanan") and the system will map them automatically.

Webhooks

Receive real-time notifications when tracking status changes occur. Configure your webhook URL in the partner dashboard.

Webhook Payload

POST to your webhook URL
{
  "event": "tracking.updated",
  "timestamp": "2026-02-28T14:30:00+07:00",
  "data": {
    "awb_number": "88826028HXDYD",
    "shipment_id": 12345,
    "status_code": "DELIVERED",
    "status_name": "Kiriman Telah Diterima",
    "location": "Taipei City, Taiwan",
    "description": "Signed by: Chen Wei"
  },
  "signature": "sha256=xxxxxxxxxxxxxxx"
}

Verifying Webhooks

Each webhook includes a signature field (HMAC-SHA256 of the payload body using your API secret). Always verify the signature before processing.

Supported Events

Event	Description
`tracking.updated`	New tracking status added to a shipment
`shipment.completed`	Shipment has been delivered
`shipment.cancelled`	Shipment was cancelled

Changelog

February 2026 — Initial Release

Create Shipment API with multi-colly support
Real-time tracking with 18-stage status system
Rate calculation with tier-based pricing
Country and courier listing endpoints
Webhook support for tracking updates
Sandbox environment for testing