KiriminAja Integration Guide
Panduan lengkap untuk mengintegrasikan KiriminAja Mitra API ke dalam aplikasi Amoura Skin
KiriminAja Integration Guide
Panduan lengkap untuk mengintegrasikan KiriminAja Mitra API ke dalam aplikasi Amoura Skin.
KiriminAja adalah aggregator logistik yang mendukung berbagai ekspedisi seperti JNE, J&T, SiCepat, AnterAja, dan lainnya dengan fitur COD dan Non-COD.
Quick Links
Daftar Isi
- Mendapatkan API Key
- Konfigurasi Environment
- Existing Service Implementation
- API Endpoints
- Flow Integrasi
- Webhook Setup
- Next Steps
1. Mendapatkan API Key
Register Sandbox Account
Kunjungi https://developer.kiriminaja.com/register dan lengkapi proses registrasi.
Login ke Dashboard
Login di https://developer.kiriminaja.com/simulation dan tunggu proses approval.
Copy API Key
Buka menu Integrasi dan copy API Key Anda.
Base URLs
| Environment | Base URL |
|---|---|
| Sandbox/UAT | https://lokal-api-uat.kiriminaja.com |
| Production | https://lokal-api.kiriminaja.com |
2. Konfigurasi Environment
File .env
KIRIMINAJA_API_KEY=your_api_key_here
KIRIMINAJA_MODE=staging # atau 'production' untuk liveFile config/services.php
'kiriminaja' => [
'api_key' => env('KIRIMINAJA_API_KEY'),
'mode' => env('KIRIMINAJA_MODE', 'staging'),
],3. Existing Service Implementation
Project ini sudah memiliki service dasar di KiriminAjaService.php:
<?php
namespace App\Services;
use Illuminate\Support\Facades\Http;
class KiriminAjaService
{
protected $baseUrl;
protected $apiKey;
protected $mode;
public function __construct()
{
$this->mode = config('services.kiriminaja.mode', 'staging');
$this->baseUrl = $this->mode === 'production'
? 'https://lokal-api.kiriminaja.com'
: 'https://lokal-api-uat.kiriminaja.com';
$this->apiKey = config('services.kiriminaja.api_key');
}
// Methods: getProvinces(), getCities(), getDistricts(), checkRates()
}Methods yang Tersedia
| Method | Endpoint | Deskripsi |
|---|---|---|
getProvinces() | /api/mitra/v2/provinces | Daftar provinsi |
getCities($provinceId) | /api/mitra/v2/cities | Daftar kota/kabupaten |
getDistricts($cityId) | /api/mitra/v2/districts | Daftar kecamatan |
checkRates(...) | /api/mitra/v2/shipping_price | Cek ongkos kirim |
4. API Endpoints
4.1 Coverage Area
GET /api/mitra/v2/provinces
Authorization: Bearer {api_key}Response:
{
"status": true,
"method": "provinsis",
"text": "Berhasil",
"datas": [
{ "id": 1, "provinsi_name": "Bali" },
{ "id": 2, "provinsi_name": "Bangka Belitung" }
]
}GET /api/mitra/v2/cities?province_id={id}
Authorization: Bearer {api_key}GET /api/mitra/v2/districts?city_id={id}
Authorization: Bearer {api_key}4.2 Check Shipping Rate
POST /api/mitra/v2/shipping_price
Authorization: Bearer {api_key}
Content-Type: application/jsonRequest Body:
{
"origin": "district_id_origin",
"destination": "district_id_destination",
"weight": 1000,
"items": [
{
"name": "Product Name",
"qty": 1,
"price": 100000
}
]
}4.3 Create Order
POST /api/mitra/v2/order
Authorization: Bearer {api_key}
Content-Type: application/jsonRequest Body:
{
"courier": "jne",
"service": "REG",
"origin": 123,
"destination": 456,
"weight": 1000,
"sender_name": "Amoura Skin",
"sender_phone": "08123456789",
"sender_address": "Jl. Contoh No. 1",
"receiver_name": "Customer Name",
"receiver_phone": "08198765432",
"receiver_address": "Jl. Tujuan No. 2",
"item_name": "Skincare Product",
"item_value": 150000,
"item_qty": 1,
"is_cod": false,
"cod_value": 0
}4.4 Tracking
GET /api/mitra/v2/tracking?awb={no_resi}
Authorization: Bearer {api_key}4.5 Request Pickup
POST /api/mitra/v2/pickup/schedule
Authorization: Bearer {api_key}
Content-Type: application/json5. Flow Integrasi
6. Webhook Setup
KiriminAja akan mengirim update status pengiriman ke callback URL Anda.
Register Callback
POST /api/mitra/v2/callback
Authorization: Bearer {api_key}
Content-Type: application/jsonRequest Body:
{
"url": "https://yourdomain.com/api/webhook/kiriminaja"
}Response:
{
"status": true,
"method": "set_callback",
"text": "Callback di set ke https://yourdomain.com/api/webhook/kiriminaja"
}Webhook Controller (Laravel)
<?php
namespace App\Http\Controllers\Api;
use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
class KiriminAjaWebhookController extends Controller
{
public function handle(Request $request)
{
$payload = $request->all();
// Log for debugging
\Log::info('KiriminAja Webhook', $payload);
// Update order status based on payload
// Example: $order->update(['shipping_status' => $payload['status']]);
return response()->json(['status' => 'ok']);
}
}Webhook Events
| Event | Status | Deskripsi |
|---|---|---|
| PICKED | picked | Paket sudah dipickup |
| IN_TRANSIT | on_progress | Dalam perjalanan |
| DELIVERED | delivered | Terkirim |
| RETURNED | returned | Dikembalikan |
7. Next Steps
✅ Yang Sudah Ada
-
KiriminAjaService.phpdengan method dasar - Config di
services.php
📝 Yang Perlu Ditambahkan
Extend KiriminAjaService dengan method:
-
createOrder()– Buat pesanan pengiriman -
getTracking()– Cek status pengiriman -
requestPickup()– Request pickup kurir -
registerCallback()– Set webhook URL
Create Webhook Controller:
- Handle status update dari KiriminAja
- Update order status di database
Frontend Integration:
- Dropdown provinsi/kota/kecamatan di checkout
- Pilihan kurir dengan harga
- Tracking page untuk customer
Database:
- Tambah kolom
awb_numberdi orders table - Tambah kolom
shipping_status - Simpan shipping cost
Sebelum go-live, pastikan:
- Ganti mode dari
stagingkeproduction - Update API key dengan production key
- Register production callback URL
- Test semua flow dengan transaksi real