Official PHP SDK for the KiriminAja logistics API.
- PHP 8.1+
- ext-json
composer require kiriminaja/kiriminaja-phpCall KiriminAjaConfig once at app startup, then call any service method on the KiriminAja facade.
use KiriminAja\Base\Config\KiriminAjaConfig;
use KiriminAja\Base\Config\Cache\Mode;
use KiriminAja\Services\KiriminAja;
KiriminAjaConfig::setMode(Mode::Staging)::setApiTokenKey('YOUR_API_KEY');
// Use any service
$provinces = KiriminAja::getProvince();| Method | Description |
|---|---|
KiriminAjaConfig::setMode($mode) |
Mode::Staging or Mode::Production |
KiriminAjaConfig::setApiTokenKey($key) |
Your KiriminAja API key |
KiriminAjaConfig::setBaseUrl($url) |
Custom base URL (useful for proxy or self-hosted) |
KiriminAjaConfig::setCacheDirectory($path) |
Custom cache directory (useful if /tmp is not writable) |
KiriminAjaConfig::disableCache() |
Disable file-based caching entirely |
// Custom cache directory
KiriminAjaConfig::setCacheDirectory(__DIR__ . '/kiriminaja-cache');
// Or disable caching entirely
KiriminAjaConfig::disableCache();
KiriminAjaConfig::setMode(Mode::Production)::setApiTokenKey('YOUR_API_KEY');If you need to route requests through a proxy or custom endpoint, set a custom base URL. This overrides the default URL resolved from the mode.
KiriminAjaConfig::setMode(Mode::Production)
::setApiTokenKey('YOUR_API_KEY')
::setBaseUrl('https://proxy.example.com');The SDK auto-registers via Laravel package discovery — no manual provider registration needed.
'kiriminaja' => [
'mode' => env('KIRIMINAJA_MODE', 'staging'),
'api_key' => env('KIRIMINAJA_API_KEY', ''),
'base_url' => env('KIRIMINAJA_BASE_URL'),
'cache_store' => env('KIRIMINAJA_CACHE_STORE', 'laravel'),
'cache_prefix' => env('KIRIMINAJA_CACHE_PREFIX', 'kiriminaja:'),
],KIRIMINAJA_MODE=staging
KIRIMINAJA_API_KEY=your-api-key-hereuse KiriminAja\Services\KiriminAja;
$provinces = KiriminAja::getProvince();| Key | Env Variable | Default | Description |
|---|---|---|---|
mode |
KIRIMINAJA_MODE |
staging |
staging or production |
api_key |
KIRIMINAJA_API_KEY |
"" |
Your KiriminAja API key |
base_url |
KIRIMINAJA_BASE_URL |
null |
Custom base URL (overrides mode-based URL) |
cache_store |
KIRIMINAJA_CACHE_STORE |
laravel |
laravel (uses Laravel Cache) or file (file-based) |
cache_prefix |
KIRIMINAJA_CACHE_PREFIX |
kiriminaja: |
Cache key prefix (Laravel store only) |
CodeIgniter 4 doesn't auto-discover Composer packages, so you wire the SDK up once during boot.
Create app/Config/KiriminAja.php:
<?php
namespace Config;
use CodeIgniter\Config\BaseConfig;
use KiriminAja\Base\Config\Cache\Mode;
class KiriminAja extends BaseConfig
{
public string $mode = Mode::Staging; // or Mode::Production
public string $apiKey = '';
public ?string $baseUrl = null;
public string $cacheStore = 'codeigniter'; // or 'file'
public string $cachePrefix = 'kiriminaja:';
}use CodeIgniter\Events\Events;
use KiriminAja\CodeIgniter\KiriminAjaBootstrap;
use Config\Services;
Events::on('pre_system', static function () {
KiriminAjaBootstrap::boot(config('KiriminAja'), Services::cache());
});use KiriminAja\Services\KiriminAja;
$provinces = KiriminAja::getProvince();| Property | Default | Description |
|---|---|---|
mode |
staging |
staging or production |
apiKey |
"" |
Your KiriminAja API key |
baseUrl |
null |
Custom base URL (overrides mode-based URL) |
cacheStore |
codeigniter |
codeigniter (uses CI4 cache service) or file (file-based) |
cachePrefix |
kiriminaja: |
Cache key prefix (codeigniter store only) |
The bootstrap helper also accepts a plain associative array — handy for tests or non-conventional setups:
KiriminAjaBootstrap::boot(['mode' => 'staging', 'api_key' => '...'], $cache);
// List all provinces
KiriminAja::getProvince();
// Cities in a province (province_id)
KiriminAja::getCity(5);
// Districts in a city (city_id)
KiriminAja::getDistrict(12);
// Sub-districts in a district (kecamatan_id)
KiriminAja::getSubDistrict(77);
// Search districts by name
KiriminAja::getDistrictByName("jakarta");use KiriminAja\Models\ShippingPriceData;
use KiriminAja\Models\ShippingPriceInstantData;
use KiriminAja\Models\ShippingFullPriceData;
// Express shipping rates
$data = new ShippingPriceData();
$data->origin = 1;
$data->destination = 2;
$data->weight = 1000; // grams
$data->item_value = 50000;
$data->insurance = 0;
$data->courier = ['jne', 'jnt'];
KiriminAja::getPrice($data);
// Instant (same-day) rates
$data = new ShippingPriceInstantData();
$data->service = ['grab_express', 'gosend'];
$data->item_price = 10000;
$data->origin = ['lat' => -6.2, 'long' => 106.8, 'address' => 'Jl. Sudirman No.1'];
$data->destination = ['lat' => -6.21, 'long' => 106.81, 'address' => 'Jl. Thamrin No.5'];
$data->weight = 1000;
$data->vehicle = 'motor'; // 'motor' or 'mobil'
$data->timezone = 'Asia/Jakarta';
KiriminAja::getPriceInstant($data);
// Full shipping price (all available couriers)
$data = new ShippingFullPriceData();
$data->origin = 1;
$data->destination = 2;
$data->weight = 1000;
KiriminAja::fullShippingPrice($data);use KiriminAja\Models\RequestPickupData;
use KiriminAja\Models\PackageData;
use KiriminAja\Models\PackageItemData;
use KiriminAja\Models\PackageItemMetadata;
// Track by order ID
KiriminAja::getTracking("ORDER123");
// Cancel shipment
KiriminAja::cancelShipment("AWB123456", "Customer request");
// Request pickup
$pickup = new RequestPickupData();
$pickup->address = "Jl. Jodipati No.29";
$pickup->phone = "08133345678";
$pickup->name = "Tokotries";
$pickup->kecamatan_id = 548;
$pickup->schedule = "2024-01-15 17:00:00";
$pickup->platform_name = "mitra";
$package = new PackageData();
$package->order_id = "YGL-000000019";
$package->destination_name = "Flag Test";
$package->destination_phone = "082223323333";
$package->destination_address = "Jl. Magelang KM 11";
$package->destination_kecamatan_id = 548;
$package->weight = 520;
$package->width = 8;
$package->height = 8;
$package->length = 8;
$package->item_value = 275000;
$package->shipping_cost = 65000;
$package->service = "jne";
$package->service_type = "REG";
$package->item_name = "Test item";
$package->package_type_id = 1;
$package->cod = 0;
// `items` is optional. When provided, it lists the individual items
// contained in the package. `item_value` is still required.
$item = new PackageItemData();
$item->name = "Kaos Polos";
$item->price = 125000;
$item->qty = 2;
$item->weight = 260;
$item->width = 4;
$item->length = 4;
$item->height = 4;
$item->metadata = new PackageItemMetadata();
$item->metadata->sku = "KP-001";
$item->metadata->variant_label = "Merah / L";
$package->items = [$item];
$pickup->packages->add($package);
KiriminAja::requestPickup($pickup);
// Pickup schedules
KiriminAja::getSchedules();use KiriminAja\Models\RequestPickupInstantData;
use KiriminAja\Models\PackageInstantData;
// Request instant pickup
$pickup = new RequestPickupInstantData();
$pickup->service = "gosend";
$pickup->service_type = "instant";
$pickup->vehicle = "motor";
$pickup->order_prefix = "BDI";
$package = new PackageInstantData();
$package->origin_name = "Rizky";
$package->origin_phone = "081280045616";
$package->origin_lat = -7.854584;
$package->origin_long = 110.331154;
$package->origin_address = "Wirobrajan, Yogyakarta";
$package->origin_address_note = "Dekat Kantor";
$package->destination_name = "Okka";
$package->destination_phone = "081280045616";
$package->destination_lat = -7.776192;
$package->destination_long = 110.325053;
$package->destination_address = "Godean, Sleman";
$package->destination_address_note = "Dekat Pasar";
$package->shipping_price = 34000;
$package->item_name = "Barang 1";
$package->item_description = "Barang 1 Description";
$package->item_price = 20000;
$package->item_weight = 1000; // grams
KiriminAja::requestPickupInstant($pickup, $package);
// Track instant order
KiriminAja::getTrackingInstant("ORDER123");
// Find a new driver for an existing order
KiriminAja::findNewDriver("ORDER123");
// Cancel instant order
KiriminAja::cancelShipment("ORDER123", "", isInstant: true);// List available couriers
KiriminAja::getCouriers();
// Courier groups
KiriminAja::getCourierGroups();
// Courier detail by code
KiriminAja::getCourierDetail("jne");
// Set whitelist expeditions
KiriminAja::setWhiteListExpedition(["jne_reg", "jne_yes"]);// Get the current KiriminAja credit balance
$result = KiriminAja::getCreditBalance();
// $result->data['balance'] => int// Print shipping label / waybill by AWB number(s)
$result = KiriminAja::printAWB(['awb' => ['AWB123', 'AWB456']]);
// $result->data['data']['url'] => PDF download URL// Calculate COD (Cash on Delivery) fee
$result = KiriminAja::calculateCOD([
'item_price' => 100000,
'data' => [
[
'courier_code' => 'jne',
'courier_service_code' => 'reg',
'shipping_cost' => 10000,
],
],
]);
// $result->data => array of fee breakdown per courier/service// Get member profile and metadata
$result = KiriminAja::getProfile();
// $result->data['id'], $result->data['email'], $result->data['name'], etc.Estimate the smallest bounding box (length / width / height) for a multi-item package by trying three stacking strategies and returning the arrangement with the smallest volume.
use KiriminAja\Utils\Volumetric;
$dim = Volumetric::calculate([
['qty' => 2, 'length' => 10, 'width' => 10, 'height' => 2],
['qty' => 1, 'length' => 5, 'width' => 5, 'height' => 5],
]);
// $dim['length'], $dim['width'], $dim['height']// Set callback URL
KiriminAja::setCallback("https://example.com/webhook");KiriminAja::getSchedules();// Get payment details (express)
KiriminAja::getPayment("PAY123");
// Get payment details (instant)
KiriminAja::getPayment("PAY123", isInstant: true);For any requests, bugs, or comments, please open an issue or submit a pull request.
composer install # install committed dependencies (PHP 8.5)
vendor/bin/paratest --configuration=phpunit.xml # run tests in parallel
# or `make test`ParaTest is the test runner. It uses PHPUnit internally, so PHPUnit remains a
transitive development dependency and the tests continue to use PHPUnit assertions
and phpunit.xml. The ParaTest constraint allows Composer to resolve dependencies
for PHP 8.1 and newer without upgrading beyond PHPUnit 11.
composer.lock is committed for reproducible development installs. CI installs
and tests that exact lockfile on PHP 8.5 and checks that it remains unchanged.
Separate PHP 8.1–8.4 compatibility jobs use composer update to resolve packages
for each PHP version instead of attempting to install the newer locked packages.
When developing on an older PHP version, run composer update to resolve
compatible development dependencies locally. Do not commit those compatibility-only
lockfile changes; intentional dependency updates should regenerate the canonical
lockfile on PHP 8.5.
Use --processes=2 to limit the number of parallel workers, or --processes=1
when debugging. File-cache tests use process-specific temporary directories to
avoid interference between workers. Process isolation is enabled in phpunit.xml
because the existing Mockery class-overload mocks must not leak between tests.
From a clean working tree with the committed dependencies installed on PHP 8.5:
make release # next patch version
make release-minor # next minor version
make release-major # next major versionEach command validates Composer metadata, runs ParaTest, bumps the version,
refreshes composer.lock without upgrading locked dependencies, and regenerates
CHANGELOG.md. It then creates a release commit and an annotated version tag
(for example, 2.1.7) and pushes both atomically to origin on the current branch.
Use REMOTE=other-remote to override the destination. Releases stop on errors,
uncommitted changes, detached HEAD, or an existing release tag.
The push requires permission to update the branch and create tags. If it fails, the release commit and tag remain local; resolve the cause and push those existing refs rather than running another version bump.
Pushing a version tag triggers .github/workflows/release.yml. It verifies the
tag matches composer.json, installs the committed lockfile on PHP 8.5, and runs
ParaTest before publishing a GitHub Release with automatically generated release
notes. Existing releases are left unchanged on reruns.
To publish or retry an existing tag manually, select Release → Run workflow
in GitHub Actions and enter the tag (for example, 2.1.7). The workflow only
publishes existing tags; it does not bump versions or create commits or tags.