Cara Integrasi API Ongkir ke WooCommerce, Laravel & Node.js

Developer API · Integrasi

Untuk mengintegrasikan AgenWebsite Rate API, kirim POST ke https://api.agenwebsite.com/v1/rates dengan header x-api-key dan body JSON berisi asal, tujuan, serta berat paket (dalam gram) — lalu render array data.rates yang dikembalikan. Prinsipnya sama di semua platform; yang berbeda hanya HTTP client-nya: wp_remote_post() di WooCommerce/PHP, Http::post() di Laravel, dan fetch() di Node.js. Artikel ini memberi kode siap tempel untuk ketiganya.

Persiapan: API key & endpoint

Ambil API key gratis dari tab API di My Account WooCommerce Anda (verifikasi email satu kali → Generate Key). Simpan kunci awk_live_... sebagai secret di server — jangan pernah menaruhnya di kode front-end/browser. Gunakan sandbox https://api-sandbox.agenwebsite.com/v1 dengan kunci awk_test_... saat pengembangan.

Integrasi WooCommerce / PHP

Cara idiomatik di WordPress adalah wp_remote_post(). Simpan API key di opsi (atau konstanta) dan panggil dari sisi server — misalnya di dalam custom shipping method, shortcode kalkulator, atau endpoint AJAX. Contoh fungsi reusable:

<?php
/**
 * Cek ongkir via AgenWebsite Rate API.
 *
 * @param string $origin_pc  Kode pos asal.
 * @param string $dest_pc    Kode pos tujuan.
 * @param int    $weight     Berat dalam gram.
 * @return array|WP_Error    Array rates, atau WP_Error jika gagal.
 */
function toko_cek_ongkir( $origin_pc, $dest_pc, $weight ) {
    $api_key = get_option( 'agenwebsite_rate_api_key' );

    $response = wp_remote_post(
        'https://api.agenwebsite.com/v1/rates',
        array(
            'timeout' => 15,
            'headers' => array(
                'x-api-key'    => $api_key,
                'Content-Type' => 'application/json',
            ),
            'body' => wp_json_encode( array(
                'shipper'     => array( 'postal_code' => $origin_pc ),
                'destination' => array( 'postal_code' => $dest_pc ),
                'weight'      => (int) $weight,
                'couriers'    => array( 'jnt', 'lion', 'spx' ),
                'sort'        => 'cheapest',
            ) ),
        )
    );

    if ( is_wp_error( $response ) ) {
        return $response;
    }

    $code = wp_remote_retrieve_response_code( $response );
    $body = json_decode( wp_remote_retrieve_body( $response ), true );

    if ( 200 !== $code || empty( $body['success'] ) ) {
        return new WP_Error(
            'ongkir_error',
            isset( $body['error']['message'] ) ? $body['error']['message'] : 'Gagal mengambil tarif.',
            array( 'status' => $code )
        );
    }

    return $body['data']['rates'];
}

// Contoh pemakaian: tampilkan tarif termurah.
$rates = toko_cek_ongkir( '40135', '10110', 1000 );
if ( ! is_wp_error( $rates ) ) {
    foreach ( $rates as $rate ) {
        printf(
            '<li>%s — %s (%s)</li>',
            esc_html( $rate['courier_name'] ),
            esc_html( $rate['cost_formatted'] ),
            esc_html( $rate['etd_text'] )
        );
    }
}

Untuk menyuntikkan tarif ke halaman checkout WooCommerce, panggil fungsi ini di dalam metode calculate_shipping() pada custom WC_Shipping_Method, lalu daftarkan tiap rate via $this->add_rate().

Integrasi Laravel

Gunakan HTTP client bawaan Laravel. Simpan API key di .env (AGENWEBSITE_RATE_API_KEY) dan bungkus dalam service class:

<?php

namespace App\Services;

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Cache;

class RateApiService
{
    private string $baseUrl = 'https://api.agenwebsite.com/v1';

    public function rates(string $originPc, string $destPc, int $weight, array $couriers = ['jnt', 'lion', 'spx']): array
    {
        $cacheKey = "ongkir:{$originPc}:{$destPc}:{$weight}:" . implode(',', $couriers);

        return Cache::remember($cacheKey, now()->addMinutes(30), function () use ($originPc, $destPc, $weight, $couriers) {
            $response = Http::withHeaders([
                    'x-api-key'    => config('services.agenwebsite.key'),
                    'Content-Type' => 'application/json',
                ])
                ->timeout(15)
                ->post("{$this->baseUrl}/rates", [
                    'shipper'     => ['postal_code' => $originPc],
                    'destination' => ['postal_code' => $destPc],
                    'weight'      => $weight,
                    'couriers'    => $couriers,
                    'sort'        => 'cheapest',
                ]);

            $response->throw(); // lempar exception untuk 4xx/5xx

            return $response->json('data.rates', []);
        });
    }
}

Tambahkan konfigurasi di config/services.php:

'agenwebsite' => [
    'key' => env('AGENWEBSITE_RATE_API_KEY'),
],

Panggil dari controller:

public function ongkir(RateApiService $api)
{
    $rates = $api->rates('40135', '10110', 1000);
    return response()->json($rates);
}

Integrasi Node.js

Node 18+ punya fetch() bawaan — tidak perlu dependensi tambahan. Simpan key di variabel lingkungan AGENWEBSITE_RATE_API_KEY:

const BASE_URL = "https://api.agenwebsite.com/v1";

async function cekOngkir({ originPc, destPc, weight, couriers = ["jnt", "lion", "spx"] }) {
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), 15_000);

  try {
    const res = await fetch(`${BASE_URL}/rates`, {
      method: "POST",
      signal: controller.signal,
      headers: {
        "x-api-key": process.env.AGENWEBSITE_RATE_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        shipper: { postal_code: originPc },
        destination: { postal_code: destPc },
        weight,
        couriers,
        sort: "cheapest",
      }),
    });

    const body = await res.json();

    if (!res.ok || !body.success) {
      const msg = body?.error?.message ?? "Gagal mengambil tarif.";
      throw new Error(`${res.status} ${msg}`);
    }

    return body.data.rates;
  } finally {
    clearTimeout(timeout);
  }
}

// Contoh pemakaian
cekOngkir({ originPc: "40135", destPc: "10110", weight: 1000 })
  .then((rates) => {
    for (const r of rates) {
      console.log(`${r.courier_name} — ${r.cost_formatted} (${r.etd_text})`);
    }
  })
  .catch((err) => console.error(err.message));

Di Express, bungkus dalam route handler dan kembalikan JSON ke front-end Anda — jangan meneruskan API key ke browser.

Best practice: caching, timeout, error

Selengkapnya soal kuota per tier dan header rate limit ada di dokumentasi.

FAQ

Apakah bisa dipakai tanpa WooCommerce?

Bisa. AgenWebsite Rate API adalah REST API standar yang bisa dipanggil dari platform apa pun — Laravel, Node.js, Django, atau bahkan aplikasi mobile lewat backend Anda. WooCommerce hanya salah satu cara termudah untuk mendapatkan API key.

Di mana sebaiknya menyimpan API key?

Di server: gunakan get_option()/konstanta di WordPress, .env di Laravel, atau environment variable di Node.js. Jangan pernah menempatkan key di kode front-end karena dapat dicuri.

Bagaimana menampilkan tarif termurah di checkout WooCommerce?

Panggil toko_cek_ongkir() di dalam calculate_shipping() pada custom shipping method, urutkan dengan sort: "cheapest", lalu daftarkan tiap tarif via $this->add_rate(). Field data.cheapest memberi pintasan langsung ke opsi termurah.

Apakah request menghabiskan kuota per kurir?

Tidak. Kuota dihitung satu per request, berapa pun jumlah kurir yang Anda minta. Meminta 5 kurir sekaligus tetap terhitung 1 request.

Bagaimana menguji tanpa memengaruhi produksi?

Gunakan base URL sandbox https://api-sandbox.agenwebsite.com/v1 dengan key awk_test_.... Struktur request dan response identik dengan produksi.