Panduan Integrasi Biteship: Mengapa Area ID Tidak Tampil pada Draft Order?

Saat menggunakan integrasi API Biteship untuk membuat Draft Order (pesanan draf), pengguna atau developer sering kali mendapati bahwa field origin_area_id maupun destination_area_id tidak muncul atau bernilai kosong/null dalam struktur data response.

Artikel ini disusun untuk memberikan pemahaman teknis dan operasional secara jelas mengenai penyebab hal tersebut terjadi serta langkah penanganan yang tepat.

Artikel ini akan membantu Anda memahami:

• Apa itu Draft Order pada integrasi Biteship
• Penyebab utama tidak munculnya Area ID pada Draft Order
• Perbedaan antara Address Text/Postal Code dengan Area ID
• Dampak teknis terhadap kalkulasi ongkir dan pembuatan order
• Solusi dan cara mengatasi masalah ini
• FAQ seputar pengisian data lokasi pada API Biteship

1. Apa Itu Draft Order pada Biteship?

Draft Order adalah status simpan sementara untuk pesanan yang belum terkonfirmasi atau belum diproses ke tahap penjemputan (pickup/courier booking). Fitur ini biasa digunakan untuk menampung data awal transaksi dari platform e-commerce, ERP, atau WooCommerce/Shopify sebelum pembeli melakukan pembayaran.

2. Mengapa Origin & Destination Area ID Tidak Menampilkan Data?

Ada beberapa faktor utama yang menyebabkan origin_area_id maupun destination_area_id tidak muncul atau berstatus null pada Draft Order:

• Pengiriman Parameter Hanya Berupa Alamat Teks (String): Pada pembuatan draft, data lokasi yang dikirimkan sering kali hanya berupa teks alamat umum atau kode pos tanpa menyertakan ID area resmi Biteship.
• Proses Geocoding Belum Selesai (Asynchronous): Biteship melakukan pencocokan alamat ke ID area secara otomatis di latar belakang. Saat response draft dibuat dengan cepat, proses resolusi ID area mungkin belum tuntas.
• Pencarian Area (Maps/Location API) Dilewati: Sistem integrasi pengirim tidak memanggil endpoint /v1/maps/areas terlebih dahulu untuk memvalidasi dan mengambil ID area spesifik sebelum pesanan dibuat.
• Format Kode Pos Tidak Valid / Kurang Lengkap: Data kode pos atau nama kecamatan yang dimasukkan pengirim tidak sesuai dengan database wilayah resmi Biteship.

3. Perbedaan Format Alamat dan Area ID

Sangat penting untuk membedakan kedua jenis data lokasi ini saat melakukan integrasi API:

Informasi Alamat Teks (Raw Address)

Merupakan string bebas seperti nama jalan, nomor rumah, RT/RW, dan kode pos. Informasi ini cukup untuk membuat draf awal, tetapi belum cukup spesifik untuk menentukan tarif presisi dari partner kurir.

Area ID Resmi Biteship (Biteship Area ID)

Merupakan identifier unik (contoh: IDNP3K101...) yang merepresentasikan tingkat kelurahan/kecamatan secara pasti. Area ID inilah yang menjadi acuan utama sistem Biteship untuk menentukan jangkauan kurir dan perhitungan ongkos kirim.

4. Dampak Tidak Adanya Area ID pada Draft Order

Jika Area ID asal maupun tujuan bernilai kosong pada draf pesanan, beberapa hal berikut dapat terjadi:

• Estimasi harga pengiriman (rates) mungkin tidak dapat dimuat secara presisi.
• Pesanan tidak dapat diubah statusnya menjadi confirmed atau diproses untuk courier pickup.
• Opsi kurir instan (seperti GoSend/GrabExpress) tidak dapat dideteksi karena membutuhkan koordinat dan area ID presisi.

5. Cara Mengatasi dan Solusi Integrasi

Langkah 1: Manfaatkan Endpoint Maps Area Biteship

Sebelum membuat order/draft order, lakukan pencarian area terlebih dahulu menggunakan API GET /v1/maps/areas?input={nama_kecamatan_atau_kodepos} untuk mendapatkan area_id yang tepat.

Langkah 2: Sertakan Area ID dalam Payload Request

Pastikan objek JSON request saat pembuatan order menyertakan parameter origin_area_id dan destination_area_id secara eksplisit.

Langkah 3: Sertakan Koordinat Latitude & Longitude

Untuk pengiriman instan/sameday, selain area_id, sertakan juga koordinat latitude dan longitude agar lokasi penjemputan dan tujuan teridentifikasi dengan akurat.

Langkah 4: Lakukan Update Draft Order

Jika pesanan sudah terlanjur tersimpan sebagai draf tanpa Area ID, Anda dapat melakukan pembaruan data (Update Order) menggunakan endpoint POST /v1/orders/{id} dengan menyertakan Area ID yang sesuai.

6. Tips Integrasi Agar Pesanan Bebas Kendala

• Gunakan fitur *auto-complete address* pada halaman checkout website/aplikasi Anda yang terhubung langsung ke API Maps Biteship.
• Selalu simpan area_id toko/gudang pengirim (origin) secara statis di pengaturan akun untuk menghindari pengisian berulang.
• Validasi kembali format kode pos pembeli sebelum mengirimkan data pembuatan pesanan ke API.

7. FAQ Seputar Area ID dan Draft Order

Apakah Draft Order bisa dibuat tanpa mengisikan Area ID?

Bisa. Namun pesanan tersebut hanya akan berstatus draf mentah dan tidak bisa diproses ke tahap pembuatan resi (*booking*) sebelum Area ID dilengkapi.

Bagaimana cara mengetahui origin area id untuk toko saya?

Anda dapat mengeceknya via Dashboard Biteship di menu Pengaturan Alamat, atau mencari lokasi alamat gudang Anda melalui endpoint API Maps Biteship.

Apakah kode pos saja cukup untuk menggantikan Area ID?

Tidak selalu. Satu kode pos bisa mencakup beberapa kelurahan/kecamatan. Biteship mewajibkan penggunaan Area ID agar penetapan tarif dan cakupan kurir tidak salah target.

8. Kesimpulan

Tidak tampilnya origin_area_id maupun destination_area_id pada draft order umumnya terjadi karena data awal yang dikirimkan hanya berupa alamat teks biasa tanpa melalui pencocokan ID wilayah Biteship.

Dengan menerapkan pencarian area_id terlebih dahulu sebelum pengiriman payload pesanan, integrasi API Anda akan berjalan lebih stabil dan akurat.

Jika Anda membutuhkan bantuan teknis lebih lanjut mengenai dokumentasi API atau kendala integrasi, silakan hubungi tim developer support Biteship melalui support@biteship.com.