Integrasi API Seller Shopee dan Tokopedia

Hampir semua seller UKM Indonesia yang saya tangani menjual produk yang sama di Shopee dan Tokopedia, ditambah mungkin toko web mereka sendiri. Begitu dua pesanan untuk unit terakhir masuk berselang detik di marketplace berbeda, terjadi oversell, pembatalan, dan penurunan rating toko. Satu-satunya solusi nyata adalah backend yang memperlakukan database Anda sendiri sebagai kebenaran dan terus merekonsiliasi stok ke tiap channel.

Pada sebuah proyek baru-baru ini saya membangun middleware omnichannel semacam ini. Di bawah adalah bentuk praktis kedua API, bagian yang sering menjebak, dan cara saya menyusun sinkronisasi agar stok tidak pernah melenceng.

Dua platform, dua model autentikasi

Hal terpenting yang harus dipahami sebelum menulis kode: Shopee dan Tokopedia melakukan autentikasi dengan cara yang benar-benar berbeda, dan Tokopedia bukan lagi API tersendiri. Setelah merger, seller Tokopedia dikelola melalui TikTok Shop Open API dan Tokopedia Partner Center. Anda mendaftar satu aplikasi, tetapi kedua integrasi hampir tidak berbagi kode di luar logika bisnis Anda.

• Shopee Open Platform (API v2): daftar di open.shopee.com untuk mendapat partner_id dan partner_key. Setiap request membawa signature HMAC-SHA256 dan timestamp. Access token berumur sekitar 4 jam; refresh token sekitar 30 hari.
• Tokopedia via TikTok Shop Partner Center: daftar aplikasi untuk mendapat app_key dan app_secret, tandatangani request dengan parameter sign, dan pakai Open API yang sama untuk aplikasi Tokopedia maupun Shop. Access token berumur sekitar 24 jam; refresh token hingga 365 hari.

Autentikasi OAuth: mendapat dan menjaga token

Kedua platform memakai pola OAuth yang serupa: Anda mengarahkan seller ke halaman otorisasi, mereka menyetujui akses ke toko mereka, dan marketplace mengarahkan balik dengan code berumur pendek. Server Anda menukar code itu menjadi access token dan refresh token. Detailnya berbeda pada cara request ditandatangani.

Untuk Shopee, signature untuk panggilan level toko adalah HMAC-SHA256 dari gabungan partner_id, path API, timestamp, access_token, dan shop_id, dengan kunci partner_key Anda. Salah urutan field dan semua panggilan mengembalikan error signature, jadi saya membungkusnya dalam satu helper dan tidak pernah menyusunnya inline.

// Shopee Open Platform v2 — shop-level request signature
import { createHmac } from "crypto";

function shopeeSign(params: {
  partnerId: number;
  partnerKey: string;
  apiPath: string;      // e.g. "/api/v2/product/update_stock"
  accessToken: string;
  shopId: number;
}): { sign: string; timestamp: number } {
  const timestamp = Math.floor(Date.now() / 1000);
  const base =
    `${params.partnerId}${params.apiPath}${timestamp}` +
    `${params.accessToken}${params.shopId}`;
  const sign = createHmac("sha256", params.partnerKey)
    .update(base)
    .digest("hex");
  return { sign, timestamp };
}

// Token refresh runs on a schedule, NOT lazily on 401.
// Shopee access_token ~4h, refresh_token ~30d — refresh early,
// persist BOTH returned values, they can rotate.

Sinkronisasi pesanan dan stok

Ada dua arah sinkronisasi. Masuk: pesanan baru mengalir dari tiap marketplace ke sistem Anda, idealnya lewat push notification atau webhook agar bereaksi dalam hitungan detik, dengan polling terjadwal sebagai jaring pengaman untuk event yang terlewat. Keluar: kapan pun stok berubah karena alasan apa pun, Anda mendorong kuantitas baru ke setiap channel yang mencantumkan SKU itu.

1. Terima webhook pesanan dari Shopee atau TikTok Shop dan segera acknowledge — anggap pengiriman event bersifat at-least-once dan lakukan dedupe berdasarkan ID pesanan.
2. Ambil detail pesanan lengkap lewat order API, lalu kurangi stok master di database Anda sendiri dalam satu transaksi.
3. Antrikan job update stok untuk setiap channel lain yang menjual SKU sama agar kuantitas baru menyebar keluar.
4. Jalankan rekonsiliasi berkala yang menarik stok yang dilaporkan tiap channel dan mengoreksi selisih terhadap master.

Tabel pemetaan antara SKU internal Anda dan identifier item serta model tiap marketplace adalah jantung sistem. Shopee memisahkan item_id dari model_id (variasinya), dan TikTok Shop memisahkan product_id dari sku_id. Jika pemetaan itu salah, Anda memperbarui varian yang keliru dan diam-diam oversell ukuran populer sementara ukuran kurang laku menampilkan stok hantu.

Unggah produk, rate limit, dan paginasi

Pembuatan produk adalah bagian paling berat skema di kedua API. Tiap marketplace menerapkan pohon kategori sendiri, atribut wajib per kategori, aturan gambar, dan opsi logistik. Saya tidak mencoba membangun model produk lowest-common-denominator. Sebaliknya saya menyimpan produk internal yang kaya dan menulis adapter per channel yang memetakannya ke persyaratan kategori dan atribut persis tiap marketplace.

Rate limit adalah tempat integrasi naif tumbang. Shopee membatasi panggilan per partner dalam jendela waktu; TikTok Shop mengalokasikan kuota secara dinamis per toko per aplikasi dan mengembalikan HTTP 429 saat Anda melampauinya. Keduanya jauh lebih toleran jika Anda melakukan batch, backoff, dan paginasi dengan benar ketimbang menggempur. Salurkan tiap panggilan keluar lewat antrean dengan token-bucket limiter per toko, dan hormati 429 dengan exponential backoff.

Merancang satu sumber kebenaran

Arsitektur yang tidak pernah mengecewakan saya sengaja dibuat membosankan: satu layanan inventory memegang kuantitas master, dan marketplace adalah konsumen hilir, bukan penulis, dari angka itu. Setiap perubahan stok, entah dari penjualan, retur, edit manual, atau stock opname gudang, memperbarui master lebih dulu lalu disebar ke channel lewat antrean.

Dengan itu terpasang, menambah channel ketiga nanti — Lazada, TikTok Shop mandiri, toko Anda sendiri — hanyalah adapter lain dan baris lain di tabel pemetaan SKU. Logika inti inventory tidak pernah berubah, dan itulah persis yang Anda inginkan ketika marketplace-nya sendiri terus berubah di bawah Anda.