Kuota & Minting

Minting adalah operasi yang memberikan tier Token Plan kepada salah satu pelanggan Anda dan mendebit kuota Anda. Karena memindahkan uang, API ini idempoten: Anda dapat melakukan retry dengan aman tanpa pernah mendebit kuota dua kali. Halaman ini menjelaskan persis cara kerjanya dan cara membangun klien yang andal di atasnya.

Setiap mint memuat operation_id yang Anda buat. Ini adalah key idempotensi Anda: string non-kosong maksimal 128 karakter yang mengidentifikasi satu *intent* mint. zrouter menghitung fingerprint idempotensi di sisi server dari operation_id, customer_email, dan plan_tier_id — Anda tidak perlu mengirim hash terpisah.

Jika Anda mengulang mint dengan operation_id yang sama dan payload yang sama (email dan tier sama), API memperlakukannya sebagai replay. Ia mengembalikan 200 dengan already_applied: true dan tidak melakukan debit tambahan — grant awal dan satu debit itu tetap tidak berubah. Mengulang request yang sebenarnya sudah diterapkan karenanya tidak akan pernah menagih Anda dua kali.

Jika Anda memakai ulang operation_id dengan payload berbeda — misalnya customer_email atau plan_tier_id yang berbeda — request gagal dengan 409 idempotency_conflict. Pemeriksaan di sisi server ini membuat pemakaian ulang id lama secara tidak sengaja tidak mungkin disalahartikan sebagai mint baru.

• Buat operation_id sekali per intent, sebelum ada panggilan jaringan. UUID atau token acak sudah cukup baik.
• Nonaktifkan tombol submit saat mint sedang berjalan agar klik ganda tidak memicu dua request dengan id berbeda.
• Retry dengan operation_id yang sama pada kegagalan sementara (429, 5xx, timeout). Jangan pernah membuat id baru saat retry.
• Simpan operation_id sampai Anda mendapat hasil yang pasti. Jika respons hilang, ulangi request yang persis sama untuk mengetahui apakah ia sudah diterapkan.

Sebuah mint diterapkan sebagai satu unit atomik: debit kuota Anda dan grant Token Plan kepada pelanggan sama-sama terjadi, atau tidak terjadi keduanya. Tidak ada jendela di mana kuota Anda telah terdebit tetapi pelanggan tidak menerima apa pun, atau pelanggan menerima grant yang tidak dibayar kuota Anda. Dikombinasikan dengan idempotensi, ini berarti hasil terburuk dari badai retry mana pun adalah satu grant dan satu debit.

Dua request di bawah adalah request yang sama. Yang pertama menerapkan mint; yang kedua — misalnya setelah respons hilang — me-replay-nya dengan operation_id yang sama dan mengembalikan already_applied: true tanpa debit kedua.

curl -X POST "https://api.zrouter.dev/api/reseller/mint" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation_id": "op_1234567890abcdef",
    "customer_email": "[email protected]",
    "plan_tier_id": "<tier-id>"
  }'