API STOWAGE.ID

Mulai cepat

1. 1

   Buat kunci di dashboard → API & webhook (paket Business atau Enterprise) dan pilih scope yang dibutuhkan.

2. 2

   Kirim permintaan ke base URL dengan header Authorization: Bearer stw_live_…

3. 3

   Daftarkan endpoint webhook untuk plan.completed dan quote.received, lalu verifikasi tanda tangannya.

Base URL

https://api.stowage.id/v1/ext

Autentikasi

Setiap permintaan memakai kunci API organisasi di header Authorization. Kunci hanya tampil sekali dan kami menyimpannya sebagai hash SHA-256 — simpan di server, jangan di kode front-end atau aplikasi mobile.

Authorization: Bearer stw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Scope

Batas laju & kuota

Batas laju dihitung per kunci dengan jendela geser 1 menit; kuota panggilan per organisasi per bulan kalender. Melebihi batas laju → 429 dengan header Retry-After; kuota habis atau paket tanpa API → 402.

Solve sinkron dibatasi 500 unit per permintaan; muatan yang lebih besar memakai Optimasi Lanjutan di Studio (respons 413).

Format error

Semua error memakai bentuk yang sama; kode HTTP: 400 input tidak valid, 401 kunci salah, 402 paket/kuota, 403 scope, 404 tidak ditemukan, 413 terlalu besar, 429 batas laju.

{
  "error": {
    "code": "paywall",
    "message": "Monthly API call quota exhausted",
    "paywall": { "moment": "feature", "quota": "api_calls", "limit": 10000, "used": 10000, "suggestedPlan": "enterprise" }
  }
}

Contoh

curl

curl -X POST https://api.stowage.id/v1/ext/plans/solve \
  -H "Authorization: Bearer $STOWAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "PO 4711",
    "space": { "code": "40HC" },
    "items": [
      { "sku": "CARTON-A", "l": 600, "w": 400, "h": 400, "kg": 12, "qty": 40 },
      { "sku": "CRATE-B", "l": 1200, "w": 800, "h": 1000, "kg": 300, "qty": 6, "stackable": false }
    ],
    "save": true
  }'

curl "https://api.stowage.id/v1/ext/ports?q=Tanjung%20Priok" \
  -H "Authorization: Bearer $STOWAGE_API_KEY"

TypeScript SDK

Klien TypeScript tanpa dependensi (fetch + WebCrypto) untuk Node 18+, Deno, Bun, dan Cloudflare Workers. stowage-ext.ts

import { createExtClient } from './stowage-ext'; // /developers/stowage-ext.ts

const stowage = createExtClient({ apiKey: process.env.STOWAGE_API_KEY! });

const { result, plan } = await stowage.solve({
  space: { code: '40HC' },
  items: [{ sku: 'CARTON-A', l: 600, w: 400, h: 400, kg: 12, qty: 40 }],
  save: true,
});
console.log(result.utilizationPct, plan?.appUrl);

const { rfq } = await stowage.createRfq({
  title: 'Kopi ke Singapura', originLocode: 'IDTPP', destLocode: 'SGSIN', mode: 'LCL', incoterm: 'FOB',
  readyDate: '2026-12-01', planId: plan?.id, contact: { name: 'Ops', email: 'ops@example.com' },
});

Simulasi perencanaan muatan. Bukan pengganti penimbangan resmi, VGM, loading computer kapal, atau persetujuan operator.

Referensi endpoint

Dibuat otomatis dari spesifikasi OpenAPI 3.1. openapi.json

Webhook

Kami mengirim POST JSON ke endpoint Anda. Balas 2xx dalam 10 detik; selain itu kami mencoba ulang hingga 7 kali dalam ±9 jam (30 dtk, 2 mnt, 10 mnt, 30 mnt, 2 jam, 6 jam). Log setiap pengiriman ada di dashboard.

Event

Verifikasi tanda tangan

Header Stowage-Signature berisi t=<unix detik>,v1=<hex>. Hitung HMAC-SHA256 dengan secret endpoint atas string "<t>.<body mentah>", bandingkan dengan v1 secara constant-time, dan tolak bila t berselisih lebih dari 5 menit.

Stowage-Signature: t=1767225600,v1=5f2b…c9e1

import { verifyWebhookSignature } from './stowage-ext';

// Express: app.post('/webhooks/stowage', express.raw({ type: 'application/json' }), handler)
const ok = await verifyWebhookSignature({
  secret: process.env.STOWAGE_WEBHOOK_SECRET!, // whsec_…
  body: req.body.toString('utf8'),             // RAW body, before JSON.parse
  header: req.header('Stowage-Signature'),
});
if (!ok) return res.status(400).end();
const event = JSON.parse(req.body.toString('utf8')); // { id, type, createdAt, orgId, data }

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

function verify(secret: string, rawBody: string, header: string, toleranceSec = 300): boolean {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=') as [string, string]));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return parts.v1?.length === expected.length && timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

Integrasi Kontainer.id & Logistikku.id

Mitra mengirim plan ke organisasi yang sudah memberi izin (persetujuan + scope) memakai header Stowage-Integration dan Stowage-Signature atas body mentah — tanpa kunci API. Identitas bersama hanya dengan scope profile:read. Saat ini mode sandbox.

BODY='{"title":"Booking KTR-991","space":{"code":"20GP"},"items":[{"sku":"BOX","l":1000,"w":1000,"h":1000,"kg":100,"qty":4}]}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$INTEGRATION_SECRET" -hex | sed 's/^.* //')
curl -X POST https://api.stowage.id/v1/ext/integrations/kontainer_id/plans \
  -H "Content-Type: application/json" \
  -H "Stowage-Integration: $INTEGRATION_ID" \
  -H "Stowage-Signature: t=$T,v1=$SIG" \
  -d "$BODY"

Widget embed

Pasang kalkulator CBM, mini planner, dan tombol "Minta penawaran" di situs vendor Anda. Gratis dengan tautan "Powered by Stowage.id"; white-label di Vendor Premium. Lead masuk ke inbox vendor; domain dibatasi allowlist.

<script src="https://embed.stowage.id/v1.js" data-vendor="wdg_…" data-locale="id" async></script>

Atribut opsional: data-locale="id|en" dan data-target="#selector". Untuk SPA: window.StowageWidget.mount(el, { widget }).

Stowage.id mempertemukan pengguna dan vendor; kontrak layanan antara pengguna dan vendor.

Untuk Vendor