Tarif

Header

Body permintaan application/json

Contoh permintaan

curl -X POST "https://api.ongkirhub.com/v1/rates" \
  -H "Authorization: Bearer ohk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a9e-4b7d-4c1e-9a52-3e8d0b7f1a24" \
  -d '{
  "sender": {
    "name": "Toko Contoh Jaya",
    "phone": "081200000001",
    "email": "gudang@contoh.test",
    "address": "Jl. Contoh Raya No. 1, RT 01/RW 02, Setiabudi",
    "location": {
      "province": "DKI Jakarta",
      "city": "Jakarta Selatan",
      "district": "Setia Budi",
      "subdistrict": "Setiabudi",
      "zipcode": "12910"
    }
  },
  "receiver": {
    "name": "Dimas Pratama",
    "phone": "081300000102",
    "address": "Jl. Penerima No. 2, dekat masjid, Lebak Gede",
    "location": {
      "province": "Jawa Barat",
      "city": "Bandung",
      "district": "Coblong",
      "subdistrict": "Lebak Gede",
      "zipcode": "40132"
    }
  },
  "items": [
    {
      "name": "Kaos katun",
      "sku": "KAOS-HITAM-L",
      "qty": 2,
      "weightKg": 0.5,
      "value": 85000,
      "dimensions": {
        "lengthCm": 25,
        "widthCm": 20,
        "heightCm": 5
      }
    }
  ],
  "pickupType": "DROP",
  "insured": false
}'

Respons

• 200 Penawaran.

  X-Request-Id

  ID permintaan untuk dukungan.

  RateLimit-Limit

  Batas permintaan per jendela waktu.

  RateLimit-Remaining

  Sisa permintaan di jendela waktu ini.

  RateLimit-Reset

  Detik sampai jendela waktu berikutnya.

  Idempotent-Replayed

  true jika respons ini adalah ulangan respons yang tersimpan untuk Idempotency-Key yang sama.

  Field respons 200

  Field	Keterangan
  id string, wajib	ID penawaran (quoteId). Berlaku 30 menit.
  livemode boolean, wajib	False untuk kunci test.
  pickupType string, wajib	- Nilai: PICKUPDROP
  insured boolean, wajib	Penawaran dengan asuransi.
  expiresAt string (date-time), wajib	Batas penawaran bisa dipakai.
  rates array<Rate>, wajib	Layanan yang tersedia, termurah dulu.

  {
    "id": "6709f1c2a1b2c3d4e5f60718",
    "livemode": false,
    "pickupType": "DROP",
    "insured": false,
    "expiresAt": "2026-10-11T03:30:00.000Z",
    "rates": [
      {
        "rateCode": "JAGOPACK",
        "courierCode": "lion",
        "courierName": "Lion Parcel",
        "serviceName": "JAGOPACK",
        "etd": {
          "min": 2,
          "max": 5,
          "unit": "DAY"
        },
        "price": {
          "courierPrice": 9500,
          "insurancePrice": 0,
          "serviceFee": 0,
          "total": 9500
        },
        "chargeableWeightKg": 1,
        "pickupToday": false,
        "pickupSlots": null
      },
      {
        "rateCode": "REG23",
        "courierCode": "jne",
        "courierName": "JNE",
        "serviceName": "Reguler",
        "etd": {
          "min": 1,
          "max": 2,
          "unit": "DAY"
        },
        "price": {
          "courierPrice": 12000,
          "insurancePrice": 0,
          "serviceFee": 0,
          "total": 12000
        },
        "chargeableWeightKg": 1,
        "pickupToday": false,
        "pickupSlots": null
      },
      {
        "rateCode": "EZ",
        "courierCode": "jnt",
        "courierName": "J&T Express",
        "serviceName": "Reguler",
        "etd": {
          "min": 2,
          "max": 3,
          "unit": "DAY"
        },
        "price": {
          "courierPrice": 15000,
          "insurancePrice": 0,
          "serviceFee": 0,
          "total": 15000
        },
        "chargeableWeightKg": 1,
        "pickupToday": false,
        "pickupSlots": null
      }
    ]
  }

• 400 Permintaan tidak bisa dibaca: JSON rusak, cursor atau Idempotency-Key tidak valid.

  X-Request-Id

  ID permintaan untuk dukungan.

  RateLimit-Limit

  Batas permintaan per jendela waktu.

  RateLimit-Remaining

  Sisa permintaan di jendela waktu ini.

  RateLimit-Reset

  Detik sampai jendela waktu berikutnya.

  {
    "error": {
      "code": "invalid_request",
      "message": "Body bukan JSON yang valid.",
      "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12"
    }
  }

• 401 Kunci API tidak dikirim, tidak valid, atau sudah dicabut.

  X-Request-Id

  ID permintaan untuk dukungan.

  {
    "error": {
      "code": "unauthenticated",
      "message": "Kunci API tidak valid, sudah dicabut, atau tidak dikirim. Kirim header Authorization: Bearer <kunci API>.",
      "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12"
    }
  }

• 403 Kunci API tidak punya akses (scope) untuk endpoint ini.

  X-Request-Id

  ID permintaan untuk dukungan.

  RateLimit-Limit

  Batas permintaan per jendela waktu.

  RateLimit-Remaining

  Sisa permintaan di jendela waktu ini.

  RateLimit-Reset

  Detik sampai jendela waktu berikutnya.

  {
    "error": {
      "code": "forbidden",
      "message": "Kunci API ini tidak punya akses ke endpoint ini. Tambahkan akses yang dibutuhkan di menu Developer.",
      "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12",
      "details": {
        "requiredScope": "shipments:write"
      }
    }
  }

• 409 Permintaan dengan Idempotency-Key yang sama masih diproses.

  X-Request-Id

  ID permintaan untuk dukungan.

  RateLimit-Limit

  Batas permintaan per jendela waktu.

  RateLimit-Remaining

  Sisa permintaan di jendela waktu ini.

  RateLimit-Reset

  Detik sampai jendela waktu berikutnya.

  {
    "error": {
      "code": "idempotency_conflict",
      "message": "Permintaan dengan Idempotency-Key yang sama masih diproses. Tunggu sebentar, lalu kirim ulang.",
      "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12"
    }
  }

• 413 Body lebih dari 64 KB.

  X-Request-Id

  ID permintaan untuk dukungan.

  RateLimit-Limit

  Batas permintaan per jendela waktu.

  RateLimit-Remaining

  Sisa permintaan di jendela waktu ini.

  RateLimit-Reset

  Detik sampai jendela waktu berikutnya.

  {
    "error": {
      "code": "payload_too_large",
      "message": "Body permintaan terlalu besar. Maksimal 64 KB.",
      "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12",
      "details": {
        "maxBytes": 65536
      }
    }
  }

• 415 Body bukan application/json.

  X-Request-Id

  ID permintaan untuk dukungan.

  RateLimit-Limit

  Batas permintaan per jendela waktu.

  RateLimit-Remaining

  Sisa permintaan di jendela waktu ini.

  RateLimit-Reset

  Detik sampai jendela waktu berikutnya.

  {
    "error": {
      "code": "unsupported_media_type",
      "message": "Kirim body sebagai JSON dengan header Content-Type: application/json.",
      "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12"
    }
  }

• 422 Isi belum valid, tidak ada layanan untuk rute ini, atau Idempotency-Key dipakai untuk isi lain.

  X-Request-Id

  ID permintaan untuk dukungan.

  RateLimit-Limit

  Batas permintaan per jendela waktu.

  RateLimit-Remaining

  Sisa permintaan di jendela waktu ini.

  RateLimit-Reset

  Detik sampai jendela waktu berikutnya.

  Isian belum valid

  {
    "error": {
      "code": "validation_error",
      "message": "Ada data yang belum lengkap atau belum sesuai. Periksa lagi isianmu.",
      "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12",
      "details": {
        "fields": [
          {
            "path": "items.0.weightKg",
            "message": "Berat harus lebih dari 0 kg"
          }
        ]
      }
    }
  }

  Tidak ada layanan

  {
    "error": {
      "code": "no_rates_available",
      "message": "Belum ada layanan kurir untuk rute dan paket ini. Coba ubah alamat atau berat paket.",
      "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12"
    }
  }

  Idempotency-Key untuk isi lain

  {
    "error": {
      "code": "idempotency_key_reused",
      "message": "Idempotency-Key ini sudah dipakai untuk permintaan lain. Pakai kunci baru untuk permintaan yang berbeda.",
      "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12"
    }
  }

• 429 Batas permintaan terlampaui.

  X-Request-Id

  ID permintaan untuk dukungan.

  RateLimit-Limit

  Batas permintaan per jendela waktu.

  RateLimit-Remaining

  Sisa permintaan di jendela waktu ini.

  RateLimit-Reset

  Detik sampai jendela waktu berikutnya.

  Retry-After

  Detik sampai boleh mencoba lagi.

  {
    "error": {
      "code": "rate_limited",
      "message": "Terlalu banyak permintaan. Tunggu sebentar, lalu coba lagi.",
      "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12",
      "details": {
        "retryAfterSec": 21
      }
    }
  }

• 500 Kesalahan di sistem OngkirHub. Aman dicoba ulang dengan Idempotency-Key yang sama.

  X-Request-Id

  ID permintaan untuk dukungan.

  RateLimit-Limit

  Batas permintaan per jendela waktu.

  RateLimit-Remaining

  Sisa permintaan di jendela waktu ini.

  RateLimit-Reset

  Detik sampai jendela waktu berikutnya.

  {
    "error": {
      "code": "internal_error",
      "message": "Terjadi kesalahan di sistem kami. Coba lagi sebentar lagi.",
      "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12"
    }
  }

• 503 Layanan pengiriman sedang gangguan atau pembuatan resi sedang dijeda. Coba lagi nanti.

  X-Request-Id

  ID permintaan untuk dukungan.

  RateLimit-Limit

  Batas permintaan per jendela waktu.

  RateLimit-Remaining

  Sisa permintaan di jendela waktu ini.

  RateLimit-Reset

  Detik sampai jendela waktu berikutnya.

  Layanan pengiriman gangguan

  {
    "error": {
      "code": "service_unavailable",
      "message": "Layanan pengiriman sedang gangguan. Coba lagi beberapa saat lagi.",
      "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12"
    }
  }

  Pembuatan resi dijeda

  {
    "error": {
      "code": "booking_disabled",
      "message": "Pembuatan resi sedang dijeda sementara. Cek ongkir dan cek resi tetap bisa dipakai.",
      "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12"
    }
  }

• 504 Layanan pengiriman lambat merespons. Coba lagi.

  X-Request-Id

  ID permintaan untuk dukungan.

  RateLimit-Limit

  Batas permintaan per jendela waktu.

  RateLimit-Remaining

  Sisa permintaan di jendela waktu ini.

  RateLimit-Reset

  Detik sampai jendela waktu berikutnya.

  {
    "error": {
      "code": "service_timeout",
      "message": "Layanan pengiriman sedang lambat. Coba lagi sebentar lagi.",
      "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12"
    }
  }