API cek ongkir untuk Next.js yang paling sederhana dipasang di toko headless adalah AgenWebsite Rate API: satu Route Handler di server memanggil POST /v1/rates dengan header x-api-key, dan komponen checkout Anda cukup memanggil route internal itu. Kuncinya tidak pernah menyentuh browser, dan paket Free 150 request per hari cukup untuk menyelesaikan prototipe sampai bisa dipakai.

Skenario yang mendasari artikel ini: toko WooCommerce yang sudah tiga tahun jalan dengan plugin AgenWebsite Shipping, lalu timnya memutuskan membangun storefront baru di Next.js dengan WooCommerce tetap jadi backend. Hari pertama semuanya lancar sampai tim sampai di halaman checkout dan sadar: ongkir yang tadinya “tinggal muncul” di WooCommerce sekarang harus mereka ambil sendiri lewat API. Dari sini pertanyaan berikutnya muncul berurutan, dan urutan itu yang saya ikuti di bawah.

💡 Jawaban Singkat: Untuk toko headless Next.js, cek ongkir dilakukan lewat AgenWebsite Rate API: buat Route Handler di app/api/ongkir/route.ts yang membaca key dari process.env.AGENWEBSITE_RATE_API_KEY (bukan NEXT_PUBLIC_), kirim POST https://api.agenwebsite.com/v1/rates dengan shipper, destination, dan weight dalam gram, lalu kembalikan data.rates ke komponen client. Tarif dan pencarian kecamatan tersedia; pembuatan resi dan COD belum ada di v1.

Apa yang berubah saat toko pindah ke Next.js atau headless?

Yang berubah adalah siapa yang memanggil API ongkir. Di WooCommerce biasa, plugin yang melakukannya dari PHP di server Anda, tanpa Anda sadari. Di Next.js, tidak ada plugin; Anda yang menulis pemanggilan itu, dan Anda yang memutuskan dari mana ia dipanggil.

Keputusan itu penting karena ada dua tempat kode bisa berjalan di Next.js: di browser pengunjung (Client Component) dan di server (Server Component, Route Handler, Server Action). API key awk_live_ hanya boleh ada di tempat kedua. Kalau Anda menaruhnya di variabel NEXT_PUBLIC_, Next.js akan menyisipkannya ke bundle JavaScript yang diunduh semua orang, dan kuota harian Anda tinggal menunggu dipakai orang lain.

Di hosting seperti Vercel atau Netlify, variabel tanpa prefix itu diisi lewat dashboard Environment Variables proyek, bukan di-commit ke repo. Satu jebakan yang sering terlewat: kalau Route Handler Anda memakai runtime = "edge", pastikan platform Anda meneruskan variabel lingkungan ke runtime itu juga. Kalau ragu, biarkan di runtime Node.js default; pemanggilan ke Rate API hanya satu request HTTP biasa dan tidak butuh edge.

Perubahan kedua lebih halus: WooCommerce menyimpan alamat pelanggan dalam field standar (kota, provinsi, kode pos), sedangkan Rate API meminta satu penanda lokasi per pihak, postal_code atau subdistrict_id. Form checkout headless Anda harus menghasilkan salah satunya. Bagian autocomplete di bawah membahas caranya.

Fitur plugin mana yang tersedia di Rate API, dan mana yang belum?

Rate API v1 membawa dua hal dari plugin ke dunia headless: tarif ongkir ternormalisasi (dengan diskon dan cashback) dan pencarian kecamatan/kode pos. Pembuatan resi, COD, dan tracking tidak ikut; untuk v1, itu tetap urusan plugin di WooCommerce atau sistem lain.

Yang biasa dilakukan plugin di WooCommerce Di Rate API v1 Catatan untuk toko headless
Menampilkan tarif beberapa kurir di checkout Ada: POST /v1/rates 5 kurir: J&T Express, SPX Express, Lion Parcel, SAP Express, J&T Cargo. Satu array data.rates[] yang sudah seragam.
Harga setelah diskon kurir Ada: discounted_cost, discount, cashback Berlaku juga di paket Free.
Dropdown kecamatan / kode pos Ada: GET /v1/locations/search Mengembalikan subdistrict_id, postal_code, dan label siap tampil.
Daftar kurir aktif Ada: GET /v1/couriers Berguna untuk membangun filter kurir di UI.
Cek sisa kuota Ada: GET /v1/usage Plan, limit, terpakai, sisa, waktu reset.
Membuat resi (AWB) dan cetak label Belum Ada di roadmap. Hari ini tetap lewat plugin di WooCommerce.
COD Belum v1 hanya tarif pengiriman reguler non-COD.
Tracking status paket Belum Tidak ada endpoint tracking di v1.
Kurir JNE, POS, TIKI, SiCepat Belum Kalau wajib, headless-nya tetap jalan, tapi untuk kurir ini Anda butuh sumber lain.

Satu konsekuensi praktis dari tabel ini: migrasi headless yang berjalan baik hampir selalu memakai dua lapis. Storefront Next.js memakai Rate API untuk menampilkan ongkir dan menerima order, lalu WooCommerce di belakang tetap menjadi tempat admin memproses order dan membuat resi dengan plugin. Itu bukan kompromi yang memalukan; itu memang pembagian kerja yang masuk akal selama v1.

Contoh route handler Next.js untuk cek ongkir

Buat satu file app/api/ongkir/route.ts yang menerima body dari komponen checkout, memvalidasi seperlunya, lalu meneruskan ke POST /v1/rates dengan key dari process.env. Pola ini mengikuti konvensi Route Handler di dokumentasi Next.js, jadi tidak ada library tambahan.

1. Variabel lingkungan

# .env.local (server). Tanpa prefix NEXT_PUBLIC_.
AGENWEBSITE_RATE_API_KEY=awk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
AGENWEBSITE_RATE_API_URL=https://api.agenwebsite.com/v1

Untuk pengembangan, ganti dengan key awk_test_ dan base URL https://api-sandbox.agenwebsite.com/v1. Dua variabel ini saja yang perlu berbeda antara staging dan produksi.

2. Route Handler

// app/api/ongkir/route.ts
import { NextRequest } from "next/server";

const BASE_URL = process.env.AGENWEBSITE_RATE_API_URL ?? "https://api.agenwebsite.com/v1";
const API_KEY = process.env.AGENWEBSITE_RATE_API_KEY;

// Ganti dengan kode pos gudang Anda, atau ambil dari konfigurasi toko.
const SHIPPER_POSTAL_CODE = "40135";

type OngkirBody = {
  destinationPostalCode?: string;
  destinationSubdistrictId?: string;
  weightGram: number;
  couriers?: string[];
};

export async function POST(request: NextRequest) {
  if (!API_KEY) {
    return Response.json({ error: "API key belum dikonfigurasi di server." }, { status: 500 });
  }

  const body = (await request.json()) as OngkirBody;

  // Rate API menerima tepat satu dari postal_code atau subdistrict_id per pihak.
  const destination = body.destinationSubdistrictId
    ? { subdistrict_id: body.destinationSubdistrictId }
    : { postal_code: body.destinationPostalCode };

  if (!destination.postal_code && !destination.subdistrict_id) {
    return Response.json({ error: "Tujuan belum dipilih." }, { status: 400 });
  }

  const weight = Math.max(1, Math.ceil(Number(body.weightGram) || 0)); // integer, gram

  const upstream = await fetch(`${BASE_URL}/rates`, {
    method: "POST",
    headers: {
      "x-api-key": API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      shipper: { postal_code: SHIPPER_POSTAL_CODE },
      destination,
      weight,
      couriers: body.couriers?.length ? body.couriers : undefined,
      sort: "cheapest",
    }),
    // Tarif untuk kombinasi yang sama jarang berubah; cache 30 menit di sisi Next.js.
    next: { revalidate: 1800 },
  });

  const json = await upstream.json();

  if (!upstream.ok || !json.success) {
    const code = json?.error?.code ?? `http_${upstream.status}`;
    const status = upstream.status === 429 ? 429 : 502;
    return Response.json(
      { error: code, request_id: json?.error?.request_id ?? null },
      { status }
    );
  }

  // Kirim hanya yang dibutuhkan UI; jangan teruskan header atau key apa pun.
  const rates = json.data.rates.map((r: any) => ({
    courier_code: r.courier_code,
    courier_name: r.courier_name,
    service_code: r.service_code,
    service_name: r.service_name,
    cost: r.discounted_cost ?? r.cost,
    etd_text: r.etd_text,
    cheapest: r.cheapest,
    fastest: r.fastest,
  }));

  return Response.json({ rates });
}

Dua hal yang sengaja saya masukkan. Pertama, status 429 dari Rate API diteruskan sebagai 429 ke client, supaya UI bisa menampilkan “coba lagi sebentar” alih-alih error umum. Kedua, respons dipangkas sebelum dikirim ke browser; rate_limit dan request_id adalah informasi operasional yang sebaiknya tinggal di log server Anda.

Soal next: { revalidate: 1800 }: ini memakai Data Cache bawaan Next.js untuk request fetch dengan body yang identik, jadi dua pembeli yang mengecek ongkir ke kecamatan dan berat yang sama dalam 30 menit hanya memakai satu kuota. Perilaku cache fetch berubah antar versi Next.js (sejak v15 default-nya tidak lagi di-cache), maka periksa dokumentasi versi yang Anda pakai. Kalau Anda tidak ingin bergantung pada itu, cache manual di Redis dengan kunci asal + tujuan + berat + kurir memberi hasil yang sama dan lebih mudah diamati.

Satu lagi yang layak ditangani eksplisit: 404 dengan error.code destination_not_found. Di toko headless, ini hampir selalu berarti form checkout meloloskan kode pos yang salah ketik. Daripada menampilkan “ongkir tidak tersedia”, lebih berguna mengembalikan pesan yang meminta pembeli memilih ulang kecamatan dari autocomplete. Kode di atas memasukkannya ke cabang error umum; di produksi, pisahkan cabangnya.

3. Pemanggilan dari komponen checkout

// components/OngkirPicker.tsx (Client Component)
"use client";

import { useState } from "react";

type Rate = {
  courier_code: string;
  courier_name: string;
  service_name: string;
  cost: number;
  etd_text: string;
  cheapest: boolean;
};

export function OngkirPicker({ postalCode, weightGram }: { postalCode: string; weightGram: number }) {
  const [rates, setRates] = useState<Rate[]>([]);
  const [loading, setLoading] = useState(false);

  async function load() {
    setLoading(true);
    try {
      const res = await fetch("/api/ongkir", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ destinationPostalCode: postalCode, weightGram }),
      });
      const json = await res.json();
      setRates(res.ok ? json.rates : []);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={load} disabled={loading || !postalCode}>Cek ongkir</button>
      <ul>
        {rates.map((r) => (
          <li key={`${r.courier_code}-${r.service_name}`}>
            {r.courier_name} {r.service_name}: Rp{r.cost.toLocaleString("id-ID")} ({r.etd_text})
            {r.cheapest ? " termurah" : ""}
          </li>
        ))}
      </ul>
    </div>
  );
}

Komponen ini tidak tahu base URL Rate API, tidak tahu header apa pun, dan tidak punya akses ke key. Itu persis yang kita mau.

Kalau Anda lebih suka Server Action daripada Route Handler, logikanya identik: fungsi dengan "use server" yang menerima tujuan dan berat, memanggil Rate API, dan mengembalikan array tarif ke komponen. Route Handler saya pilih di contoh karena lebih mudah diuji dari terminal dengan curl dan bisa dipakai juga oleh aplikasi mobile Anda nanti. Mana pun yang dipilih, syaratnya satu: pemanggilan ke api.agenwebsite.com terjadi di server.

Berat yang dikirim komponen sebaiknya dihitung di server juga, dari isi keranjang yang tersimpan, bukan dari angka yang dikirim browser. Pembeli yang iseng mengubah weightGram menjadi 1 di DevTools akan mendapat ongkir termurah, dan Anda yang menombok selisihnya. Di contoh ini saya terima dari body supaya alurnya terlihat; di produksi, ambil dari sesi keranjang atau dari WooCommerce lewat Store API.

Contoh respons disederhanakan yang akan diterima komponen di atas:

{
  "rates": [
    { "courier_code": "spx", "courier_name": "SPX Express", "service_code": "STD",
      "service_name": "Standard", "cost": 9500, "etd_text": "2-4 hari",
      "cheapest": true, "fastest": false }
  ]
}

Nilai dan kode layanan di contoh ini hanya ilustrasi; nama field-nya mengikuti dokumentasi. Versi lengkap pola server-side untuk Laravel dan Node.js biasa ada di artikel cara integrasi API ongkir di WooCommerce, Laravel, dan Node.js.

Autocomplete kecamatan dengan /v1/locations/search

Form checkout headless perlu menghasilkan postal_code atau subdistrict_id untuk tujuan, dan cara paling ramah pembeli adalah autocomplete: pembeli mengetik “dago”, Anda memanggil GET /v1/locations/search?q=dago&limit=5 lewat Route Handler, lalu menampilkan field label dari tiap hasil. Minimal 3 karakter untuk q, limit default 10 dan maksimal 50.

Yang perlu diingat sebelum menulis kodenya: setiap panggilan ke endpoint lokasi menghitung 1 kuota, sama seperti /v1/rates. Tanpa debounce, satu pembeli yang mengetik “Kecamatan Coblong” bisa menghabiskan 17 request dalam dua detik. Dokumentasi kami menyarankan debounce 300 ms, dan di paket Free itu bukan saran, itu syarat hidup.

// app/api/lokasi/route.ts
import { NextRequest } from "next/server";

const BASE_URL = process.env.AGENWEBSITE_RATE_API_URL ?? "https://api.agenwebsite.com/v1";

export async function GET(request: NextRequest) {
  const q = request.nextUrl.searchParams.get("q")?.trim() ?? "";
  if (q.length < 3) return Response.json({ locations: [] });

  const url = new URL(`${BASE_URL}/locations/search`);
  url.searchParams.set("q", q);
  url.searchParams.set("limit", "8");

  const upstream = await fetch(url, {
    headers: { "x-api-key": process.env.AGENWEBSITE_RATE_API_KEY! },
    next: { revalidate: 86400 }, // nama kecamatan dan kode pos hampir tidak berubah
  });
  const json = await upstream.json();
  if (!upstream.ok || !json.success) return Response.json({ locations: [] }, { status: 502 });

  return Response.json({
    locations: json.data.locations.map((l: any) => ({
      subdistrict_id: l.subdistrict_id,
      postal_code: l.postal_code,
      label: l.label,
    })),
  });
}
// Di Client Component: debounce 300 ms sebelum memanggil /api/lokasi
useEffect(() => {
  if (query.length < 3) return;
  const t = setTimeout(async () => {
    const res = await fetch(`/api/lokasi?q=${encodeURIComponent(query)}`);
    const json = await res.json();
    setOptions(json.locations);
  }, 300);
  return () => clearTimeout(t);
}, [query]);

Nilai revalidate: 86400 di route lokasi lebih agresif daripada di route ongkir, dan itu sengaja. Hasil pencarian “dago” hari ini dan minggu depan sama; tidak ada alasan membayar kuota dua kali. Kalau toko Anda melayani pembeli yang terkonsentrasi di beberapa kota, setelah hari pertama sebagian besar pencarian lokasi akan dilayani dari cache.

Setelah pembeli memilih satu opsi, simpan subdistrict_id-nya dan kirim itu ke /api/ongkir sebagai destinationSubdistrictId. Lebih presisi daripada kode pos, karena satu kode pos bisa mencakup beberapa kecamatan. Detail parameter dan contoh respons lengkap ada di dokumentasi GET /v1/locations/search.

Pertanyaan yang Sering Diajukan

Apakah Rate API selengkap plugin AgenWebsite Shipping?

Belum. Rate API v1 menyediakan tarif ongkir lima kurir (J&T Express, SPX, Lion Parcel, SAP, J&T Cargo) dan pencarian kecamatan/kode pos; plugin Shipping untuk WooCommerce punya cakupan dan fitur yang berbeda, termasuk pembuatan resi. Untuk toko headless, pembagian yang umum adalah Rate API di storefront dan plugin tetap di WooCommerce untuk proses order.

Bisakah membuat resi lewat API?

Belum di v1. Pembuatan order dan AWB ada di roadmap Rate API, tapi hari ini endpoint yang tersedia hanya rates, couriers, locations/search, dan usage. Kalau alur Anda butuh resi dari Next.js langsung, itu belum bisa.

Di mana menyimpan API key?

Di variabel lingkungan server, misalnya AGENWEBSITE_RATE_API_KEY di .env.local atau di secret manager hosting Anda, dan hanya dibaca dari Route Handler, Server Component, atau Server Action. Jangan pakai prefix NEXT_PUBLIC_, karena Next.js akan menyertakannya di bundle browser. Kalau key sempat bocor, gunakan Rotate di My Account → API.

Berapa kuota gratisnya?

Paket Free memberi 150 request per hari dengan batas 20 request per menit, direset pukul 00:00 WIB, dan maksimal 2 key aktif. Semua endpoint, termasuk pencarian lokasi, menghitung kuota yang sama. Untuk toko yang sudah ramai, Pro Rp129.000/bulan memberi 30.000 request/hari dan Max Rp229.000/bulan memberi 60.000 request/hari.

Dari mana sebaiknya mulai?

Mulai dari Route Handler /api/ongkir dengan key sandbox, kode pos gudang Anda yang asli, dan satu kode pos tujuan yang Anda tahu tarifnya dari plugin. Kalau angkanya cocok, baru bangun autocomplete lokasi dan sambungkan ke form. Urutan ini membuat Anda tahu lebih cepat apakah lima kurir di v1 cukup untuk toko Anda, sebelum menghabiskan waktu di UI.

👉 Key Free dan dokumentasi lengkapnya ada di halaman AgenWebsite Rate API; untuk 150 request per hari, prototipe checkout headless Anda tidak perlu menunggu persetujuan anggaran siapa pun.