Panduan Integrator Public API

Halaman ini adalah panduan teknis yang dirender untuk developer atau vendor yang perlu mengintegrasikan public API KartuStok.

Gunakan bersama:

• OpenAPI Specification
• Postman Collection

Kapan Panduan Ini Dipakai

Gunakan panduan ini saat tim integrasi perlu:

• mengetes konektivitas token
• mengatur base URL API company yang benar
• memahami kebutuhan scope
• membaca data warehouse, item, kategori, atau stok
• menangani public ID yang opaque dan pagination dengan aman

Base URL dan Authentication

Selalu gunakan domain frontend company, bukan domain member.

Benar:

https://your-subdomain.kartustok.com/public/v1

Salah:

https://member.kartustok.com/public/v1

Semua request wajib mengirim:

Authorization: Bearer <your_api_token>
Accept: application/json

Jika host salah, API bisa mengembalikan:

{
  "status": "error",
  "message": "Invalid URL"
}

Matriks Scope

Scope	Fungsi	Endpoint
meta.read	Konektivitas dan metadata perusahaan	/health, /meta/company
item.read	Daftar item dan detail item	/items, /items/{id}
category.read	Daftar kategori barang	/item-categories
locator.read	Daftar warehouse	/locators
stock.read	Report stok	/stock/summary, /stock/detail

Catatan Kompatibilitas Warehouse

UI produk sekarang memakai istilah Warehouse, tetapi kontrak teknis API masih memakai:

• /locators
• locator.read
• locator_id

Anggap nama-nama itu sebagai kontrak API warehouse untuk saat ini.

Alur Integrasi yang Disarankan

1. Panggil GET /health
2. Panggil GET /meta/company
3. Sinkronkan /item-categories
4. Sinkronkan /locators
5. Sinkronkan /items
6. Gunakan /stock/summary untuk saldo
7. Gunakan /stock/detail untuk audit pergerakan

Ringkasan Endpoint

Health

GET /public/v1/health

Scope: meta.read

Company Metadata

GET /public/v1/meta/company

Scope: meta.read

Items

GET /public/v1/items
GET /public/v1/items/{id}

Scope: item.read

Filter list yang didukung:

• page
• per_page
• q
• is_active
• category_id

Item Categories

GET /public/v1/item-categories

Scope: category.read

Warehouses

GET /public/v1/locators

Scope: locator.read

Stock Summary

GET /public/v1/stock/summary

Scope: stock.read

Filter umum:

• date_from
• date_to
• locator_id
• item_id
• category_id
• page
• per_page

Stock Detail

GET /public/v1/stock/detail

Scope: stock.read

Filter wajib:

• locator_id

Filter opsional:

• item_id
• transaction_type
• date_from
• date_to
• page
• per_page

Pagination

Endpoint yang memakai pagination:

• /items
• /stock/summary
• /stock/detail

Aturan:

• page mulai dari 1
• per_page maksimum 100
• default /items untuk per_page adalah 20
• default /stock/summary untuk per_page adalah 50
• default /stock/detail untuk per_page adalah 50

Penanganan Error

401 Unauthorized

Penyebab:

• bearer token tidak ada
• token tidak valid
• token inactive
• token expired
• token revoked

403 Forbidden

Penyebab:

• scope yang dibutuhkan tidak ada
• IP client tidak termasuk Allowed IPs

404

Kemungkinan penyebab:

• host company salah
• public ID tidak valid
• resource tidak ditemukan

429 Too Many Requests

Rate limit saat ini:

• 120 request
• per 60 detik
• per token dan client IP

Best Practice

• simpan token di secret server-side
• gunakan satu token untuk satu integrasi
• gunakan scope sekecil mungkin
• gunakan Allowed IPs untuk infrastruktur server yang stabil
• jangan menganggap opaque ID adalah integer database
• jangan hardcode token di kode browser
• rotasi atau revoke token saat kepemilikan berubah