Panduan

Autentikasi

Setiap request membawa API key sebagai bearer token.

Header

Authorization: Bearer tcn_live_<8>_<40>

curl

curl "https://api.comnethub.app/v1/developer/token-info" \
  -H "Authorization: Bearer $THECOMNET_API_KEY"

Dua cara autentikasi

Metode	Dipakai saat	Token
API key	Sistem Anda sendiri mengakses tenant Anda sendiri.	`tcn_live_…`
Aplikasi OAuth	Produk Anda bertindak atas nama merchant lain, yang masing-masing menyetujuinya.	`tcn_at_…`

Keduanya dikirim sebagai Authorization: Bearer … dan memakai endpoint serta scope yang sama. Halaman ini membahas API key; untuk aplikasi, lihat Membuat aplikasi (OAuth 2.0).

API key

Format: tcn_live_ + 8 karakter alfanumerik + _ + 40 karakter alfanumerik. 17 karakter pertama (tcn_live_XXXXXXXX) adalah prefix publik yang ditampilkan di konsol untuk membedakan key.
Key lengkap hanya ditampilkan satu kali, saat dibuat. TheComNet hanya menyimpan hash SHA-256-nya, jadi key yang hilang tidak bisa dipulihkan: cabut, lalu buat yang baru.
Key dibuat oleh owner atau admin di Pengaturan → Integrasi dan dimiliki satu tenant. Setiap panggilan dibatasi pada data tenant tersebut.
Key bertindak sebagai pembuatnya. Key langsung berhenti berfungsi bila anggota tersebut dikeluarkan dari tenant, dinonaktifkan, atau diturunkan di bawah admin. Buat key integrasi dari akun yang akan tetap menjadi owner/admin.
Simpan key di sisi server. Jangan pernah menyertakannya di aplikasi browser atau mobile, dan jangan pernah meng-commit-nya.

Pencabutan dan kedaluwarsa

Key bisa dicabut kapan saja di konsol. Pencabutan berlaku pada request berikutnya.
Key bisa memiliki tanggal kedaluwarsa opsional yang diatur saat dibuat. Setelah waktu itu, key tidak lagi bisa dipakai.
Key yang dicabut, kedaluwarsa, salah format, atau tidak dikenal, serta key yang pembuatnya kehilangan akses, semuanya dijawab 401 API_KEY_INVALID. Response tidak menyebutkan penyebabnya; periksa key di konsol.

Scope

Key membawa satu atau beberapa scope yang dipilih saat dibuat. Setiap operasi mencantumkan scope yang membukanya; cukup memiliki salah satu. Scope :write tidak mencakup :read, jadi berikan keduanya bila integrasi membaca dan menulis.

Scope	Cakupan	Operasi
`orders:read`	Pesanan, detail pesanan, opsi dan label pengiriman, permintaan after-sales dan alasan penolakan, pick/pack list.	7
`orders:write`	Mengatur pengiriman (satuan dan massal), menyetujui atau menolak permintaan after-sales, pick/pack massal.	4
`products:read`	Produk tersinkron, item inventori, gudang, stok dan mutasinya, katalog marketplace (kategori, atribut, merek, gudang, draf produk).	13
`products:write`	Membuat dan mengubah item inventori, menyesuaikan dan push stok, menautkan varian, dokumen stok, harga/stok massal, gambar dan produk katalog.	10
`contacts:read`	Kontak, detail kontak, dan label kontak.	3
`contacts:write`	Mengganti nama, memberi label, atau menambah catatan pada kontak.	1
`chat:read`	Percakapan, pesan, label chat, dan quick reply.	4
`chat:write`	Mengirim balasan, menambah catatan internal, memperbarui percakapan, menandai sudah dibaca.	4

3 operasi menerima key apa pun tanpa melihat scope: GET /v1/stores, GET /v1/stores/{storeId}, GET /v1/developer/token-info. Operasi yang tidak ada di referensi API khusus konsol dan menolak API key.

Error autentikasi

Status	Kode	Arti
401	`UNAUTHENTICATED`	Tidak ada header Authorization.
401	`API_KEY_INVALID`	Key tidak dikenal, salah format, dicabut, atau kedaluwarsa, atau pembuatnya bukan lagi owner/admin aktif.
403	`API_KEY_NOT_ALLOWED`	Operasi ini khusus konsol dan tidak menerima API key.
403	`API_SCOPE_MISSING`	Key tidak memiliki satu pun scope yang dibutuhkan operasi.
403	`FEATURE_NOT_IN_PLAN`	Tenant tidak berada di paket dengan akses API (Pro). details.feature bernilai "api_access".

403 application/problem+json

{
  "type": "about:blank",
  "title": "API_SCOPE_MISSING",
  "status": 403,
  "code": "API_SCOPE_MISSING",
  "detail": "API key lacks the required scope",
  "instance": "/v1/orders",
  "details": {
    "required": [
      "orders:read"
    ]
  },
  "requestId": "6f1c2d3e-4b5a-4c6d-8e7f-90a1b2c3d4e5"
}