API OTW v1

Integrasikan pengiriman ke website, sistem kasir, atau aplikasi Anda.

1. Autentikasi

Buat API key di Portal Klien → tab Integrasi. Key hanya ditampilkan sekali — simpan baik-baik. Kirim di setiap request:

Authorization: Bearer pt_xxxxxxxxxxxxxxxx

Alternatif: header X-API-Key: pt_xxxx. Batas 600 request/menit per key. Semua data otomatis dibatasi ke akun Anda sendiri.

2. Endpoint

GET /api/v1/ping

Cek key valid.

POST /api/v1/orders

Buat order. Jika Anda punya jadwal pickup rutin hari itu, paket otomatis menempel ke pickup tersebut (attached: true).

{
  "packages": [
    { "recipient": "Siti Rahma", "area": "Kelapa Gading", "cod": 185000 },
    { "recipient": "Andi", "area": "Bekasi", "cod": 0 }
  ],
  "urgent": { "enabled": true, "date": "2026-08-11", "start": "14:00", "end": "16:00" }
}

Balasan berisi order_code, labels_url, dan tiap paket dengan awb + tracking_url. Bagian urgent opsional.

GET /api/v1/orders/{order_code}

Detail satu order beserta status tiap paket.

GET /api/v1/packages

Daftar paket. Filter: ?status=TERKIRIM, ?date=2026-08-10, ?limit=200.

GET /api/v1/packages/{awb}

Status lengkap satu resi + riwayat percobaan antar.

GET /api/v1/settlements

COD terkumpul yang belum cair + riwayat pencairan.

GET /api/v1/addressbook

Buku alamat penerima Anda. Filter ?q=nama.

3. Status paket

Status	Arti
`DIBUAT`	Order dibuat, menunggu kurir
`DIPICKUP`	Sudah diambil kurir, menuju hub
`DI_HUB`	Tiba di hub sortir
`DIKIRIM`	Sedang diantar ke penerima
`TERKIRIM`	Terkirim (ada nama penerima + foto bukti)
`GAGAL`	Gagal diantar, dijadwalkan ulang (`next_retry_date`)

4. Webhook

Daftarkan URL di Portal Klien → Integrasi. Kami kirim POST JSON setiap ada perubahan.

Event: order.created · package.picked_up · package.at_hub · package.out_for_delivery · package.delivered · package.failed · settlement.created

POST https://website-anda.com/webhook
X-PT-Event: package.delivered
X-PT-Signature: sha256=<hmac>

{
  "event": "package.delivered",
  "sent_at": "2026-08-10 15:04:05",
  "data": { "package": { "awb": "GL2608100001", "status": "TERKIRIM", ... } }
}

Verifikasi tanda tangan (wajib)

Hitung HMAC-SHA256 dari body mentah memakai webhook secret Anda, lalu bandingkan dengan header X-PT-Signature:

// Node.js
const sig = crypto.createHmac("sha256", SECRET).update(rawBody).digest("hex");
if ("sha256=" + sig !== req.headers["x-pt-signature"]) return res.status(401).end();

Balas 200 secepatnya. Jika gagal, kami ulang otomatis 5x dengan jeda 1, 5, 15, 60, lalu 360 menit.

5. Lacak publik

Setiap paket punya halaman lacak tanpa login: /track/{awb} — aman dibagikan ke pembeli Anda (tidak menampilkan nilai COD).