Pengiriman untuk
website Anda.

Mulai dari sandbox

1. Login ke dashboard, buka API & Webhook, lalu buat key TEST. Isi password saat ini dan kode MFA jika aktif.
2. Simpan key sebagai environment variable di backend website. Key hanya ditampilkan sekali.
3. Panggil sandbox: https://sb.antarpaket.id/v1. Gunakan kurir SANDBOX dan layanan REG.
4. Setelah integrasi teruji, buat key LIVE dan ganti base URL menjadi https://kecapi.antarpaket.id/v1.

Sandbox memakai tarif dan resi simulasi. Tidak ada panggilan kurir, pemotongan saldo, atau pickup sungguhan. Kode wilayah contoh 123/456 hanya untuk simulasi; cari kode sebenarnya melalui GET /areas?q=… saat produksi.

Permintaan pertama — cURL

curl --request POST 'https://sb.antarpaket.id/v1/rates'   --header "Authorization: Bearer $ANTARPAKET_API_KEY"   --header 'Content-Type: application/json'   --data '{"originDistrictCode":"123","destDistrictCode":"456","weightGram":1000}'

JavaScript / Next.js — jalankan di server

const response = await fetch('https://sb.antarpaket.id/v1/rates', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.ANTARPAKET_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    originDistrictCode: '123', destDistrictCode: '456', weightGram: 1000,
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(result.error.code);
console.log(result.data.rates);

PHP / Laravel

// config/services.php
'antarpaket' => ['key' => env('ANTARPAKET_API_KEY')],

// Di controller/service backend Laravel
$response = Http::withToken(config('services.antarpaket.key'))
    ->acceptJson()->timeout(30)
    ->post('https://sb.antarpaket.id/v1/rates', [
        'originDistrictCode' => '123',
        'destDistrictCode' => '456',
        'weightGram' => 1000,
    ]);
$response->throw();
$rates = $response->json('data.rates');

Alur membuat pengiriman

1. GET /areas untuk kode kecamatan pengirim dan penerima.
2. POST /rates untuk melihat pilihan tarif. Berat dalam gram; dimensi dalam cm; nilai barang dalam rupiah.
3. POST /quotes dengan parameter tarif, courierCode, serviceCode, dan itemDescription. Simpan data.quoteId dan perhatikan expiresAt.
4. POST /shipments dengan quoteId, alamat pengirim/penerima, itemDescription, quantity, dan codAmount. Kirim header Idempotency-Key unik untuk pesanan website Anda. Quote harus berasal dari key yang sama.
5. Simpan ID pengiriman di website Anda. Pantau melalui tracking atau webhook.

Rute kecamatan, deskripsi barang, dan nilai COD harus sesuai quote. Untuk LIVE, pembayaran hanya melalui saldo AntarPaket. Aturan pickup dan persyaratan kurir tetap berlaku; sebagian kurir memerlukan kode pos dan koordinat pengirim.

Saat request timeout, ulangi dengan Idempotency-Key dan body yang sama. Jangan membuat key baru. HTTP 202 berarti pengiriman yang sudah ada ditemukan; periksa statusnya. Jika booking gagal atau perlu rekonsiliasi, cek dashboard sebelum membuat pesanan lain.

Response berhasil: {"data":{…},"request_id":"…"}. Error: {"error":{"code":"…","message":"…"},"request_id":"…"}. Simpan request_id untuk dukungan. Nominal pada response berupa string rupiah.

Kurir & layanan yang diizinkan

Atur pilihan pada dashboard API & Webhook, bagian Kurir & layanan API. Pengaturan berlaku untuk semua API key akun, terpisah antara LIVE dan TEST. Mode semua mengizinkan layanan yang tersedia, termasuk layanan baru. Mode pilihan hanya mengizinkan pasangan kurir dan layanan yang dipilih; tanpa pilihan, daftar ongkir kosong dan pemesanan ditolak.

Pembatasan diperiksa pada cek ongkir, quote, dan pembuatan pengiriman. Quote lama dengan layanan yang kemudian dinonaktifkan ditolak dengan HTTP 403 SERVICE_DISABLED. Request booking yang sudah diproses tidak dibatalkan; replay idempotent dan tracking pengiriman yang sudah ada tetap tersedia. Pilihan akun tidak dapat mengaktifkan layanan yang dinonaktifkan AntarPaket.

Aktif atau nonaktif COD API

Di dashboard API & Webhook, bagian Kurir & layanan API, atur Aktifkan COD API. Pengaturan berlaku untuk semua API key akun, terpisah untuk LIVE dan TEST. Default aktif untuk menjaga integrasi yang sudah ada.

Jika nonaktif, cek ongkir dan quote dengan cod: true serta pemesanan dengan quote COD lama ditolak: HTTP 403 COD_DISABLED. Request non-COD tetap tersedia dan response ongkir menyatakan codSupported: false. Mengaktifkan COD tetap memerlukan kurir, layanan, dan rute yang mendukung COD. Pengiriman COD yang sudah diproses tetap dapat dilacak dan menerima webhook; request yang sudah diproses tidak dibatalkan.

Harga sebelum atau sesudah diskon

Di dashboard API & Webhook, pilih Harga yang ditampilkan: Sudah termasuk diskon akun (default) atau Belum termasuk diskon akun. Pengaturan terpisah untuk LIVE dan TEST, berlaku bagi semua API key akun. Pada cek ongkir dan quote, finalPrice dan grandTotal mengikuti pilihan tampilan.

Response juga memuat priceDisplayMode, priceBeforeDiscount, priceAfterDiscount, discountAmount, dan payableGrandTotal. Pembayaran pengiriman selalu memakai harga setelah diskon akun; gunakan payableGrandTotal untuk total pembayaran AntarPaket. Biaya COD/asuransi tetap mengikuti aturan layanan. Mode harga tersimpan pada quote dan perubahan pengaturan tidak mengubah quote yang sudah dibuat. Response pengiriman dan webhook menyatakan nominal transaksi sebenarnya.

Contoh: ongkir sebelum diskon Rp20.000, diskon Rp3.000, asuransi Rp1.000. Mode sebelum diskon menampilkan total Rp21.000; mode sesudah diskon Rp18.000. Pembayaran AntarPaket tetap Rp18.000 pada kedua mode. Sandbox belum memberikan diskon sehingga kedua harga simulasi sama.

Izin & batas penggunaan

• 120 request/menit per key; 180 request/menit dan 10.000 request per jendela 24 jam per akun/environment.
• Cek ongkir + quote: gabungan 30 request/menit per akun/environment.
• Pembuatan pengiriman: 10 request/menit dan 100 request per jendela 24 jam per akun/environment.
• Batas pengaman alamat IP: 300 request/menit. Semua batas dihitung sebagai jendela sejak request pertama; request gagal dapat ikut dihitung.
• HTTP 429: gunakan Retry-After dan backoff. Batas harian dapat membutuhkan waktu lebih lama. Saat kontrol kuota tidak tersedia, API menolak request dengan 503.
• Key berlaku 1–365 hari, default 90 hari. IP allowlist mendukung alamat IP persis, bukan CIDR. Untuk rotasi, buat key baru, perbarui backend, lalu cabut key lama.

Webhook yang dapat diverifikasi

Daftarkan URL HTTPS publik melalui dashboard dan pilih TEST atau LIVE. Event mencakup seluruh pengiriman akun setelah pendaftaran, termasuk pengiriman dari web. URL tidak boleh memakai query, fragment, kredensial, port selain 443, atau mengarah ke jaringan internal.

• shipment.created: pengiriman tercatat; status awal bisa BOOKING_PENDING.
• shipment.updated: status atau nomor resi berubah.
• webhook.test: event uji dari tombol dashboard.

{
  "id": "evt_contoh",
  "type": "shipment.updated",
  "createdAt": "2026-10-09T07:00:00.000Z",
  "environment": "live",
  "data": {
    "id": "id_pengiriman", "number": "AP-2026-contoh",
    "status": "DELIVERED", "awb": "RESI_CONTOH",
    "courierCode": "KURIR", "serviceCode": "REG",
    "shippingPrice": "15000", "insuranceFee": "0"
  }
}

Verifikasi signature — Node.js

import { createHmac, timingSafeEqual } from 'node:crypto';

// Gunakan body mentah, sebelum JSON.parse atau middleware JSON.
const rawBody = await request.text();
const id = request.headers.get('x-antarpaket-event-id') ?? '';
const timestamp = request.headers.get('x-antarpaket-timestamp') ?? '';
const signature = request.headers.get('x-antarpaket-signature') ?? '';
const now = Math.floor(Date.now() / 1000);
if (!/^\d{10}$/.test(timestamp) || Math.abs(now - Number(timestamp)) > 300)
  return new Response('Timestamp tidak valid', { status: 401 });
const expected = 'v1=' + createHmac('sha256', process.env.ANTARPAKET_WEBHOOK_SECRET)
  .update(id + '.' + timestamp + '.' + rawBody).digest('hex');
const actualBuffer = Buffer.from(signature);
const expectedBuffer = Buffer.from(expected);
if (actualBuffer.length !== expectedBuffer.length ||
    !timingSafeEqual(actualBuffer, expectedBuffer))
  return new Response('Signature tidak valid', { status: 401 });
const event = JSON.parse(rawBody);
if (event.id !== id) return new Response('Event tidak valid', { status: 400 });
// Simpan event di database/queue dengan UNIQUE(event.id), baru balas HTTP 2xx.
// Event duplikat yang sudah tersimpan juga dibalas 2xx.

Signing secret berbeda dari API key. Maksimal 6 percobaan: pertama segera, lalu jeda 1 menit, 5 menit, 15 menit, 1 jam, dan 6 jam. Timeout 10 detik; redirect tidak diikuti. Riwayat dapat dilihat di dashboard.

Event dapat datang berulang atau tidak berurutan. Deduplikasi berdasarkan event ID dan gunakan endpoint detail untuk mengetahui status terbaru. Sinkronkan jam server untuk verifikasi timestamp. Rotasi secret berlaku segera; pengiriman yang masih antre menggunakan secret terbaru.

Menjaga integrasi Anda

• Gunakan key hanya di backend. Jangan memasukkannya ke JavaScript browser, aplikasi mobile, URL, repository, atau log.
• Pilih izin minimal dan IP allowlist bila backend memiliki IP tetap. Gunakan key terpisah untuk setiap integrasi.
• Playground di dokumentasi hanya untuk sandbox. Request browser ke produksi ditolak; panggil dari backend.
• Akun harus aktif dan email terverifikasi. Key kehilangan akses bila pembuatnya tidak lagi memiliki peran yang diizinkan.
• Tracking memakai hasil sinkronisasi internal. Timeline API menampilkan kode status dan waktu, tanpa payload mentah kurir.

Error yang perlu ditangani

Versi & berkas integrasi

API saat ini memakai /v1. Integrasi sebaiknya menerima penambahan field response dan status baru. Perubahan yang tidak kompatibel akan memakai versi API baru.

Unduh OpenAPI JSON · Referensi interaktif

Changelog · 9 Oktober 2026

Versi 1.0: wilayah, cek ongkir, quote, pengiriman melalui saldo, tracking, sandbox, API key, dan webhook bertanda tangan.