Integrasi server API dengan marketplace

Cara kerja

Integrasi server API kamu dengan marketplace punya tiga arah, semuanya diautentikasi dengan satu secret milik organisasimu.

1. BuyerGateway marketplaceServer kamuWajib diverifikasi

   Panggilan API buyer, diteruskan dengan tanda tangan

2. MarketplaceServer kamuOpsional

   Webhook: entitlement baru, diperpanjang, dicabut

3. Server kamuMarketplaceOpsional

   Sinkronisasi: tarik entitlement yang berubah

Akses buyer ditegakkan gateway, bukan server kamu. Key buyer, masa berlaku, kuota, dan pencabutan semuanya diperiksa gateway sebelum request diteruskan. Request yang sampai ke server kamu sudah sah — tugasmu hanya memastikan request itu memang datang dari gateway, bukan dari orang yang menemukan base URL kamu dan memanggilnya langsung.

Kamu tidak pernah menerima API key buyer, lewat jalur mana pun. Buyer dikenali lewat entitlement_id dan buyer_id.

Mulai cepat

1. Daftar sebagai tenant dan buat produk. Base URL produk wajib https://.
2. Buka dashboard tenant → Integrasi, tampilkan secret (Owner, sekali saja), dan simpan di konfigurasi server kamu — mis. variabel lingkungan KAYYA_API_SECRET. Jangan menaruhnya di repositori kode.
3. Pasang verifikasi panggilan gateway di depan seluruh route API kamu — lewat SDK, atau contoh kode di halaman ini.
4. Uji implementasimu dengan test vector sebelum menyentuh server sungguhan.
5. Deploy, lalu tekan Uji integrasi di halaman produk dashboard tenant. Ketiga uji harus lolos — apa yang diuji.
6. Ajukan produk untuk review.

Pilih jalur integrasi

Kamu tidak wajib memakai SDK. Yang dinilai uji integrasi adalah perilaku server kamu — menolak tanda tangan palsu dengan 401 dan menerima tanda tangan yang sah — bukan cara kamu membuatnya. Ketiga jalur ini lolos uji yang sama:

Verifikasi panggilan gatewayWajib

Buyer memanggil alamat produkmu di marketplace dengan key-nya. Alamat itulah yang tercantum di dokumentasi produkmu untuk buyer — base URL aslimu tidak pernah ditampilkan. Gateway memeriksa key, masa berlaku, dan kuota, membuang kredensial buyer (Authorization, X-Api-Key, Cookie) serta seluruh header berawalan X-Marketplace- yang dikirim buyer, lalu meneruskan request ke {base_url_produk}{path} dengan header berikut:

Langkah 1 — tanda tangan

Yang ditandatangani hanya nilai header, digabung dengan baris baru (\n), tanpa baris baru di akhir:

payload = "v1:gateway"
        + "\n" + X-Marketplace-Timestamp
        + "\n" + X-Marketplace-Request-Id
        + "\n" + METHOD                        # huruf besar, mis. "GET"
        + "\n" + X-Marketplace-Target
        + "\n" + X-Marketplace-Buyer-Id
        + "\n" + X-Marketplace-Entitlement-Id
        + "\n" + X-Marketplace-Produk
        + "\n" + X-Marketplace-Expires-At
signature = "sha256=" + hex(HMAC_SHA256(key = secret, data = payload))

if header tidak lengkap:                                  tolak 401  (header_kurang)
if abs(sekarang - int(X-Marketplace-Timestamp)) > 300:   tolak 401  (timestamp)
if tidak satu pun bagian X-Marketplace-Signature.split(",")
       sama (constant-time) dengan signature:             tolak 401  (tanda_tangan)

Langkah 2 — path

Pastikan request yang kamu terima memang request yang ditandatangani:

diterima = path + query string request yang diterima server kamu
if percent_decode(X-Marketplace-Target)
       != percent_decode(prefix_yang_dibuang + diterima):  tolak 401  (path)

• Kedua sisi di-decode dulu sebelum dibandingkan — framework berbeda menyajikan path secara berbeda (sebagian sudah di-decode, sebagian mentah). Membandingkan byte mentah menghasilkan 401 palsu pada path berisi spasi atau huruf non-ASCII.
• prefix_yang_dibuang diisi kalau server kamu di belakang reverse proxy yang membuang awalan path (mis. proxy menerima /v1/cuaca lalu meneruskan /cuaca). Kosong untuk kebanyakan server.
• Kenapa path tidak langsung ditandatangani: tiap lapisan (gateway, proxy, framework) meng-encode path sedikit berbeda, sehingga tanda tangan atas path mentah gagal di sebagian framework saja. Menandatangani nilai header — yang tidak diubah siapa pun — lalu mencocokkan path setelah di-decode memberi perlindungan yang sama tanpa kegagalan acak itu.
• Body tidak ikut ditandatangani, dan itu disengaja: request buyer bisa berupa unggahan besar atau streaming. Integritas body dijaga TLS — karena itu base URL wajib https://.
• Awalan v1:gateway membedakan tanda tangan ini dari tanda tangan webhook, sehingga tanda tangan dari satu arah tidak bisa dipakai di arah lain.

Contoh kode

Hanya pustaka standar. Pasang di middleware, sebelum routing — bukan di tiap route. Uji integrasi mengetuk satu path acak dan menuntut 401; verifikasi yang hanya dipasang di sebagian route gagal di sana.

from __future__ import annotations

import hashlib
import hmac
import time
from urllib.parse import unquote

TOLERANSI_DETIK = 300


def _tanda_tangan(secret: str, pesan: bytes) -> str:
    # Secret dipakai apa adanya, termasuk awalan "whsec_".
    return "sha256=" + hmac.new(secret.encode(), pesan, hashlib.sha256).hexdigest()


def _salah_satu_cocok(dihitung: str, header_signature: str) -> bool:
    # Selama masa rotasi secret header berisi beberapa tanda tangan dipisah koma.
    # compare_digest, bukan ==, supaya waktunya tidak membocorkan isi signature.
    return any(hmac.compare_digest(dihitung, s.strip()) for s in header_signature.split(","))


def _timestamp_sah(nilai: str, sekarang: float | None) -> bool:
    try:
        dikirim = int(nilai)
    except ValueError:
        return False
    jam = time.time() if sekarang is None else sekarang
    return abs(jam - dikirim) <= TOLERANSI_DETIK

HEADER_GATEWAY = (
    "x-marketplace-timestamp",
    "x-marketplace-request-id",
    "x-marketplace-target",
    "x-marketplace-buyer-id",
    "x-marketplace-entitlement-id",
    "x-marketplace-produk",
    "x-marketplace-expires-at",
    "x-marketplace-signature",
)


def verifikasi_gateway(
    secret: str,
    method: str,
    path_diterima: str,
    header: dict[str, str],
    prefix_yang_dibuang: str = "",
    sekarang: float | None = None,
) -> tuple[bool, str | None]:
    """Apakah panggilan ini benar datang dari gateway Kayya API.

    ``path_diterima``: path + query string seperti diterima server kamu.
    Mengembalikan ``(sah, alasan)`` — alasan salah satu ``header_kurang``,
    ``timestamp``, ``tanda_tangan``, ``path``.
    """
    h = {nama.lower(): nilai for nama, nilai in header.items()}
    if not all(h.get(nama) for nama in HEADER_GATEWAY):
        return False, "header_kurang"
    ts = h["x-marketplace-timestamp"]
    if not _timestamp_sah(ts, sekarang):
        return False, "timestamp"  # kemungkinan besar jam server meleset (NTP)
    pesan = "\n".join([
        "v1:gateway",
        ts,
        h["x-marketplace-request-id"],
        method.upper(),
        h["x-marketplace-target"],
        h["x-marketplace-buyer-id"],
        h["x-marketplace-entitlement-id"],
        h["x-marketplace-produk"],
        h["x-marketplace-expires-at"],
    ]).encode()
    if not _salah_satu_cocok(_tanda_tangan(secret, pesan), h["x-marketplace-signature"]):
        return False, "tanda_tangan"
    # Kedua sisi di-decode: framework berbeda menyajikan path sebagian ter-decode.
    if unquote(h["x-marketplace-target"]) != unquote(prefix_yang_dibuang + path_diterima):
        return False, "path"
    return True, None

Isi argumen path yang diterima dengan path beserta query string seperti yang sampai ke server kamu:

Jawaban yang diharapkan

Kode alasan sama dengan kode di test vector: header_kurang, timestamp, tanda_tangan, path. Dashboard tenant membacanya untuk menampilkan penyebab yang spesifik saat uji integrasi gagal. Kodenya tidak membocorkan apa pun — penyerang tetap tidak bisa membuat tanda tangan yang sah.

Baris terakhir penting: marketplace memeriksa kesehatan base URL kamu secara berkala dengan memanggil akarnya tanpa header. Jawaban di bawah 500 dianggap sehat; 5xx berturut-turut membuat produkmu ditandai gagal dan bisa dihentikan sementara.

Jangan menolak berdasarkan X-Marketplace-Expires-At

Keputusan boleh-tidaknya buyer mengakses sepenuhnya milik gateway. Ada keadaan di mana akses tetap sah meski tanggalnya terlihat lewat (mis. masa tenggang pembayaran langganan), dan aturan itu bisa berubah. Server yang ikut menolak berdasarkan tanggal akan menolak buyer yang sedang dilayani gateway. Pakai header ini untuk ditampilkan, bukan untuk memutuskan.

Test vector

Kumpulan kasus uji resmi: masukan persis (secret, header, path, jam) dan jawaban yang wajib dihasilkan implementasimu. Vector dihasilkan dari kode marketplace yang benar-benar menandatangani, dan setiap contoh kode di halaman ini lolos seluruhnya. Implementasi yang benar lolos seluruh vector, tanpa pengecualian.

• Jam dari vector, bukan jam mesin. Pakai masukan.sekarang; tanpa itu kasus timestamp lolos atau gagal tergantung kapan test dijalankan.
• Nama header tidak peka huruf besar/kecil. Beberapa kasus memakai nama huruf kecil, seperti yang dikirim HTTP/2.
• Raw body. Kasus webhook "body di-serialize ulang" hanya gagal kalau tanda tangan dihitung dari byte mentah — seperti seharusnya.
• Secret di dalamnya (whsec_vektor-uji-…) dibuat khusus untuk uji dan tidak berlaku di mana pun.

WebhookOpsional

Marketplace mengirim POST ke URL webhook yang kamu isi di dashboard tenant → Integrasi. Tanpa webhook, produkmu tetap bisa dijual dan buyer tetap terlayani.

Webhook adalah pemberitahuan, bukan penjaga akses: entitlement yang dicabut sudah ditolak gateway detik itu juga, entah webhook-nya sampai ke kamu atau tidak. Pakai untuk hal-hal di sisimu sendiri — menyiapkan data pelanggan baru, mengirim email sambutan, memperbarui dashboard.

Event

Kedaluwarsa tidak dikirim sebagai event — ia terjadi karena waktu berlalu, bukan karena sesuatu terjadi. Hitung sendiri dari expires_at.

Payload entitlement.updated

{
  "event": "entitlement.updated",
  "entitlement_id": "3b7d5c11-8e2f-4a90-b1c2-d3e4f5a6b7c8",
  "buyer_id": "0f9c1e2a-7b3d-4c5e-9f10-2a3b4c5d6e7f",
  "product_id": "7c1a9e33-4d2b-4f6a-8c0d-9e1f2a3b4c5d",
  "tenant_id": "4f1c2b8e-9a7d-4e3f-8b21-6c5d0e9a1f37",
  "durasi_bulan": 6,
  "status": "active",
  "expires_at": "2027-03-21T15:33:20Z",
  "revoked_at": null,
  "limit_hit": 80000,
  "updated_at": "2026-09-21T15:33:18.123456Z"
}

Payload ini sama persis dengan satu baris di response sinkronisasi, ditambah event dan tenant_id — satu fungsi upsert melayani keduanya.

Verifikasi tanda tangan

payload   = X-Marketplace-Timestamp + "." + raw_request_body
signature = "sha256=" + hex(HMAC_SHA256(key = secret, data = payload))

def verifikasi_webhook(
    secret: str,
    raw_body: bytes,
    header: dict[str, str],
    sekarang: float | None = None,
) -> tuple[bool, str | None]:
    """Apakah kiriman webhook ini sah. ``raw_body``: byte persis seperti diterima."""
    h = {nama.lower(): nilai for nama, nilai in header.items()}
    ts = h.get("x-marketplace-timestamp", "")
    signature = h.get("x-marketplace-signature", "")
    if not ts or not signature:
        return False, "header_kurang"
    if not _timestamp_sah(ts, sekarang):
        return False, "timestamp"
    if not _salah_satu_cocok(_tanda_tangan(secret, ts.encode() + b"." + raw_body), signature):
        return False, "tanda_tangan"
    return True, None

Fungsi pembantunya — penanda tangan, pemeriksa timestamp, dan pembanding constant-time — sama dengan yang di contoh verifikasi gateway; satu berkas memuat ketiganya.

• Secret dipakai apa adanya, termasuk awalan whsec_ — bukan hasil decode base64/hex-nya.
• Hitung dari raw body, byte persis seperti diterima. Parse lalu serialize ulang mengubah spasi dan urutan key, dan tanda tangan tidak akan pernah cocok. Ambil raw body sebelum body-parser framework bekerja.
• Bandingkan constant-time, bukan == — == berhenti di byte pertama yang berbeda, dan selisih waktunya cukup untuk menebak tanda tangan byte demi byte.

Idempotensi & urutan

Marketplace bisa mengirim payload yang sama lebih dari sekali, dan retry percobaan lama bisa tiba setelah perubahan yang lebih baru — jadwal retry membentang sampai ±32 jam. Aturannya:

1. Cari entitlement_id di data lokal.
2. Belum ada → insert.
3. Sudah ada dan updated_at yang datang lebih baru → update seluruh field.
4. Sudah ada dan updated_at yang datang sama atau lebih lama → abaikan, tetap jawab 200.

Langkah 3 adalah jalur normal setiap perpanjangan, bukan kasus pinggiran. Langkah 4 mencegah retry lama menimpa data baru — misalnya pemberitahuan "aktif" yang tertunda menimpa pencabutan yang sudah kamu terima dari sinkronisasi.

Jawaban & retry

Jadwal retry: batas waktu 10 detik per percobaan, lalu 1 menit → 5 menit → 30 menit → 2 jam → 6 jam → 24 jam. Kalau seluruh percobaan habis, webhook kamu dinonaktifkan otomatis dan Owner/Admin diberi tahu di dashboard. Perubahan yang gagal terkirim tidak hilang — ikut tertarik lewat sinkronisasi. Balas secepatnya (di bawah 5 detik); kalau pemrosesanmu berat, simpan payload lalu proses asinkron.

SinkronisasiOpsional

Server kamu menarik daftar entitlement yang berubah. Ini jaring pengaman untuk webhook yang tidak sampai — server kamu mati, retry habis, atau webhook sedang nonaktif — dan cara memulihkan data lokal dari nol. Sinkronisasi tetap berjalan meski webhook tidak dipasang.

Endpoint & tanda tangan

GET https://marketplace-api.kayya.id/api/v1/provisioning/sync/?since={iso8601}   ← halaman pertama
GET https://marketplace-api.kayya.id/api/v1/provisioning/sync/?kursor={kursor}   ← halaman berikutnya

payload   = X-Tenant-Timestamp + "." + request_target
signature = "sha256=" + hex(HMAC_SHA256(key = secret, data = payload))

request_target = path + query string persis seperti yang dikirim, mis. /api/v1/provisioning/sync/?since=2026-08-01T00%3A00%3A00%2B00%3A00. Susun URL-nya sekali, tandatangani string itu, lalu kirim string yang sama — jangan biarkan library HTTP menyusun ulang query setelah kamu menandatanganinya. Tanda + wajib di-encode %2B.

def tanda_tangan_sync(secret: str, timestamp: str, request_target: str) -> str:
    """Nilai ``X-Tenant-Signature``. ``request_target``: path + query persis seperti dikirim."""
    return _tanda_tangan(secret, f"{timestamp}.{request_target}".encode())

Response

{
  "hasil": [
    {
      "entitlement_id": "3b7d5c11-8e2f-4a90-b1c2-d3e4f5a6b7c8",
      "buyer_id": "0f9c1e2a-7b3d-4c5e-9f10-2a3b4c5d6e7f",
      "product_id": "7c1a9e33-4d2b-4f6a-8c0d-9e1f2a3b4c5d",
      "durasi_bulan": 1,
      "status": "revoked",
      "expires_at": "2026-10-01T00:00:00Z",
      "revoked_at": "2026-09-12T03:14:00Z",
      "limit_hit": null,
      "updated_at": "2026-09-12T03:14:00.482913Z"
    }
  ],
  "sampai": "2026-09-23T04:00:00.000000+00:00",
  "kursor_berikutnya": "opaque-string"
}

Algoritma yang benar

res = GET sync(since = baca_penanda())      # penanda kosong pada sinkronisasi pertama
loop:
    terapkan(res.hasil)                     # aturan idempotensi webhook
    if res.kursor_berikutnya is null:
        simpan_penanda(res.sampai)          # HANYA setelah halaman terakhir
        break
    res = GET sync(kursor = res.kursor_berikutnya)

• Jangan memakai jam server kamu sebagai since berikutnya — pakai sampai. Jam server melewatkan perubahan di jendela 30 detik terakhir.
• Jangan menyimpan sampai sebelum halaman terakhir. Kalau putaran gagal di tengah, mulai lagi dari since lama — baris yang sudah diterapkan akan diabaikan aturan idempotensi.
• Interval: tiap 1 jam, plus sekali setiap service kamu start. Interval hanya menentukan seberapa cepat data lokalmu menyusul, bukan seberapa cepat pencabutan berlaku — itu urusan gateway.
• Kegagalan sinkronisasi tidak boleh menghentikan service kamu. Catat, coba lagi dengan jeda, dan tetap layani buyer — tanda tangan gateway cukup untuk melayani request tanpa data lokal sama sekali.

Uji integrasi & syarat tayang

Sebelum produk bisa diajukan review, base URL produk itu harus lolos uji integrasi. Uji berlaku per produk — produk dengan base URL berbeda diuji masing-masing. Jalankan kapan saja lewat tombol Uji integrasi di halaman produk dashboard tenant (paling banyak 20 kali per jam per produk); marketplace juga mengulangnya tiap 15 menit selama produk tayang.

Pemberitahuan hanya dikirim saat keadaannya berubah. Server yang tidak menjawab atau menjawab 5xx tidak dihitung di sini — itu urusan pemeriksaan kesehatan base URL.

Bentuk panggilan uji

Sama persis dengan panggilan buyer yang diteruskan gateway, dengan beberapa nilai tetap supaya kamu bisa mengenalinya:

• Tanda tangan palsu berbentuk sah (sha256= + 64 hex, dari secret acak) — server yang hanya memeriksa bentuk header tetap tertangkap.
• 3xx pada uji palsu dihitung gagal: verifikasi harus berjalan sebelum redirect.
• Jawaban 401 dengan body {"alasan": "<kode>"} membuat dashboard menampilkan penyebab yang spesifik untuk uji sah yang gagal.
• Uji hanya membuktikan path yang diketuknya. Lindungi seluruh route API kamu, bukan hanya akarnya.

Rotasi secret

Ganti secret di dashboard tenant → Integrasi → Ganti secret. Ada masa tenggang 24 jam:

Setelah 24 jam, secret lama berhenti berlaku. Tombol Akhiri masa tenggang sekarang tersedia kalau secret lama bocor dan harus dimatikan seketika.

Urutan yang aman: ganti secret di dashboard → pasang secret baru di konfigurasi server → deploy — semuanya dalam 24 jam. Server yang belum diperbarui tetap berjalan dengan secret lama selama masa tenggang, karena verifikasi menerima salah satu tanda tangan yang cocok.

Pemecahan masalah

Menghubungi dukungan? Sertakan nilai X-Marketplace-Request-Id dari request yang bermasalah — kami bisa menelusuri request yang sama di sisi kami.

Changelog kontrak

v2 — 23 September 2026. Menggantikan v1 seluruhnya.

• Panggilan buyer dari gateway kini ditandatangani, ditambah header X-Marketplace-Request-Id & X-Marketplace-Target. Server tenant memverifikasi tanda tangan, bukan key buyer.
• Webhook & sinkronisasi tidak lagi membawa API key buyer — diganti entitlement_id.
• Event entitlement.updated menggantikan key.provisioned: juga dikirim saat pencabutan, membawa status & updated_at.
• Syarat berjualan: uji integrasi per produk; webhook opsional.
• Secret dibuat otomatis untuk setiap organisasi; rotasi dengan masa tenggang 24 jam dan multi-signature.
• Sinkronisasi memakai kursor, bukan nomor halaman; since = sampai dari halaman terakhir.
• User-Agent webhook: KayyaAPI-Webhook/1.0.

Contoh kode di halaman ini dan SDK resmi mengikuti semantic versioning; setiap perubahan kontrak dicatat di sini lebih dulu.