[Muhamad Iqbal Nurmanditya Iqbal Rookie]

Up

0

::

Panduan Lengkap Integrasi API Mekari Menggunakan HMAC Authentication

Apakah Anda sedang mengembangkan aplikasi dan perlu mengintegrasikannya dengan layanan Mekari seperti Jurnal, Qontak, atau KlikPajak? Artikel ini adalah panduan lengkap Anda untuk memahami dan mengimplementasikan HMAC Authentication dari tahap persiapan hingga pengujian.

Panduan ini akan membahas langkah-langkah esensial mulai dari pengaturan URL Sandbox, Base URL, hingga tips penting agar terhindar dari error Unauthorized.

1. Mengenal Environment: Dasbor Developer & Sandbox

Sebelum melakukan pemanggilan API, Anda perlu memahami lingkungan (environment) pengembangan yang disediakan oleh Mekari. Terdapat dua lingkungan utama, yaitu Sandbox (untuk testing) dan Production (untuk aplikasi live).

• MDC Sandbox: Dasbor khusus developer untuk testing (Khusus untuk Jurnal & KlikPajak. Catatan: Qontak tidak memiliki dasbor sandbox).
• MDC Production: Dasbor developer utama untuk aplikasi live.

Ketentuan Khusus Sandbox:

• Jurnal Sandbox: Anda harus mendaftar secara terpisah di portal khusus Sandbox Jurnal. Akun ini berbeda dengan akun Jurnal Production Anda.
  • Jika Anda butuh perpanjangan masa trial, kirimkan email ke tim support Mekari (squadron at mekari) dengan subjek: “Request Extend Trial Sandbox Account – CID 12345 – DURATION”. (Pastikan Anda mencantumkan CID Sandbox, bukan CID Production).
  • Kuota Gratis: Jurnal memberikan kuota free sebesar 2.000 hit/bulan dengan rate limit 40 request/menit.
• KlikPajak Sandbox: Anda dapat mengakses portal Sandbox KlikPajak, namun disarankan untuk menghubungi tim Integration Specialist terlebih dahulu.

2. Memahami Base URL API Mekari

Base URL adalah alamat utama yang menjadi awalan sebelum Anda menambahkan endpoint spesifik (API path).

• Sandbox Base URL: Gunakan awalan sandbox-api dari domain utama Mekari.
• Production Base URL: Gunakan awalan api dari domain utama Mekari.

Contoh Penggunaan: Jika Anda ingin memanggil endpoint WhatsApp templates dari Qontak di environment Production, maka Anda tinggal menggabungkan Production Base URL dengan API Path spesifik untuk WhatsApp.

3. Catatan Penting Sebelum Membuat Aplikasi (IMPORTANT!)

Banyak developer mengalami kendala permission saat pertama kali membuat aplikasi. Perhatikan aturan Role berikut:

1. Hak Akses Tertinggi: Hanya pengguna dengan peran (role) tertinggi seperti Owner atau Admin yang diizinkan untuk membuat Application guna mendapatkan Client ID dan Client Secret.
2. Khusus Qontak Omnichannel: Anda WAJIB memiliki setidaknya 2 pengguna yang terdiri dari 1 Admin dan 1 SPV (Supervisor).
   • Admin bertugas untuk membuat aplikasi.
   • SPV bertugas untuk validasi.
   • Peringatan: Jika perusahaan Anda tidak memiliki pengguna dengan peran SPV, request API Anda akan ditolak dengan respons error 401: Invalid credentials.

4. Langkah-Langkah Membuat Aplikasi & Mendapatkan Kredensial

Setelah memahami environment dan base URL, ikuti langkah berikut untuk meng-generate HMAC Credentials:

1. Akses Dasbor Developer: Kunjungi portal developer Mekari (pilih Production atau Sandbox).
2. Pilih Dashboard: Pilih dasbor produk yang ingin Anda gunakan (Mekari Qontak, Jurnal, atau Klikpajak) dan sign in menggunakan akun Anda.
3. Buat Aplikasi Baru: Buat Application baru dengan memasukkan nama aplikasi (minimal 4 karakter).
4. Pilih Scopes: Tentukan scopes atau cakupan akses API sesuai dengan kebutuhan Anda. (Catatan: Saat memilih scopes, pastikan Anda menunggu hingga scroll bar mencapai bagian bawah dan berhenti bergerak agar semua opsi termuat dengan baik).

5. Masa Berlaku Kredensial (Expiration)

Berita baiknya, Client ID dan Client Secret tidak memiliki masa kedaluwarsa selama Anda tidak melakukan Regenerate Client Secret.

Namun, jika Anda mengklik tombol Regenerate, maka kunci lama akan otomatis dibatalkan dan digantikan dengan yang baru. Segera perbarui data di kode aplikasi Anda agar integrasi tidak terputus.

6. Pengujian (Testing) dengan API Tools

Setelah mendapatkan Client ID dan Client Secret, Anda siap melakukan pengujian. Mekari merekomendasikan penggunaan tools seperti Postman untuk mensimulasikan request sebelum menanamkannya ke dalam kode sumber (Python, PHP, Node.js, dsb.).

Tips Sukses Pengujian HMAC:

• Pastikan Date Header menggunakan format GMT yang valid.
• Signature HMAC harus di-generate ulang setiap kali Anda melakukan request baru. Jangan pernah menggunakan ulang signature yang sama untuk request yang berbeda, karena akan menghasilkan error 401 Unauthorized.

Panduan lengkap: HMAC Guideline

---

Dengan memahami panduan ini, Anda sudah berada di jalur yang tepat untuk membangun integrasi API yang solid, aman, dan efisien dengan ekosistem Mekari. Selamat mengembangkan aplikasi!

[AKHMAD SYAHREZA Rookie]

so helpful!