API Documentation — Tokoku ERP

Tokoku ERP API

REST API untuk integrasi aplikasi mobile Tokokumo dan layanan pihak ketiga dengan platform Tokoku ERP.

Base URL

https://tokoku.kuroragidigital.my.id/api/v1

Autentikasi

Bearer Token (Sanctum)

Format

JSON

Authentication

Semua endpoint (kecuali POST /auth/login) memerlukan Bearer Token di header:

Authorization: Bearer <token_dari_login>

Token diperoleh melalui endpoint login. Setiap token memiliki abilities berdasarkan peran pengguna:

Role	Abilities
superadmin	`*` (semua akses)
pemilik	`dashboard:view`, `sales:*`, `stock:view`, `stock:opname`, `reports:view`, `units:switch`
karyawan	`dashboard:view`, `sales:view`, `sales:create`, `stock:view`

Format Response

Semua response menggunakan format JSON yang konsisten:

Success Response

{
    "success": true,
    "message": "OK",
    "data": { ... }
}

Paginated Response

{
    "success": true,
    "message": "OK",
    "data": [ ... ],
    "meta": {
        "current_page": 1,
        "last_page": 5,
        "per_page": 20,
        "total": 96
    }
}

Error Response

{
    "success": false,
    "message": "Deskripsi error",
    "errors": { ... }  // (opsional, untuk validasi)
}

Error Handling

Code	Deskripsi
`200`	OK — Request berhasil
`201`	Created — Data berhasil dibuat
`401`	Unauthorized — Token tidak valid atau expired
`403`	Forbidden — Tidak memiliki izin untuk aksi ini
`404`	Not Found — Resource tidak ditemukan
`422`	Unprocessable Entity — Data validasi gagal
`429`	Too Many Requests — Rate limit terlampaui
`500`	Internal Server Error — Kesalahan server

Auth Endpoints

POST /auth/login Public

Login dan mendapatkan access token. Mendukung login via email atau username.

Request Body

Parameter	Tipe	Wajib	Keterangan
`login`	string	✅	Email atau username
`password`	string	✅	Password akun
`device_name`	string	✅	Nama perangkat (contoh: "Samsung Galaxy S24")
`device_platform`	string	❌	`android` atau `ios`
`fcm_token`	string	❌	Firebase Cloud Messaging token untuk push notification

Response (200)

{
    "success": true,
    "message": "Login berhasil.",
    "data": {
        "user": {
            "id": 1,
            "name": "John Doe",
            "username": "johndoe",
            "email": "john@example.com",
            "roles": ["pemilik"],
            "business_unit_id": 1,
            "owned_units": [{ "id": 1, "name": "Toko Utama" }],
            "last_login_at": "2026-03-19T10:30:00+07:00"
        },
        "token": "1|abc123def456...",
        "abilities": ["dashboard:view", "sales:view", ...]
    }
}

POST /auth/logout 🔒 Auth

Logout dan mencabut token saat ini. Juga menghapus FCM token.

GET /auth/profile 🔒 Auth

Mendapatkan data profil pengguna yang sedang login.

PUT /auth/profile 🔒 Auth

Memperbarui data profil pengguna.

Request Body

Parameter	Tipe	Wajib	Keterangan
`name`	string	❌	Nama lengkap
`email`	string	❌	Alamat email (unik)
`fcm_token`	string	❌	Token FCM baru

PUT /auth/password 🔒 Auth

Mengubah password pengguna.

Request Body

Parameter	Tipe	Wajib	Keterangan
`current_password`	string	✅	Password saat ini
`password`	string	✅	Password baru (min: 8)
`password_confirmation`	string	✅	Konfirmasi password baru

POST /auth/switch-unit 🔒 Auth

Pindah unit usaha aktif.

Request Body

Parameter	Tipe	Wajib	Keterangan
`business_unit_id`	integer	✅	ID unit usaha tujuan

GET /auth/units 🔒 Auth

Mendapatkan daftar unit usaha yang dapat diakses pengguna.

Dashboard Endpoints

GET /dashboard 🔒 dashboard:view

Data dashboard lengkap: ringkasan, grafik penjualan, cashflow, produk terlaris, stok rendah, dll.

Query Parameters

Parameter	Tipe	Wajib	Keterangan
`business_unit_id`	integer	❌	ID unit usaha. Default: unit aktif pengguna

GET /dashboard/summary 🔒 dashboard:view

Ringkasan ringan untuk home screen mobile: kartu ringkasan + info stok rendah.

Response (200)

{
    "success": true,
    "data": {
        "summary_cards": { ... },
        "low_stock_count": 3,
        "low_stock_items": [ ... ]
    }
}

Sales Endpoints

GET /sales 🔒 sales:view

Daftar penjualan dengan pagination dan filter.

Query Parameters

Parameter	Tipe	Wajib	Keterangan
`per_page`	integer	❌	Jumlah per halaman (1-100, default: 20)
`status`	string	❌	`draft`, `confirmed`, `completed`, `cancelled`
`payment_status`	string	❌	`unpaid`, `partial`, `paid`
`start_date`	date	❌	Filter dari tanggal (YYYY-MM-DD)
`end_date`	date	❌	Filter sampai tanggal (YYYY-MM-DD)
`search`	string	❌	Cari berdasarkan nomor invoice atau nama pelanggan
`business_unit_id`	integer	❌	ID unit usaha

GET /sales/{id} 🔒 sales:view

Detail penjualan lengkap termasuk item, pembayaran, dan pelanggan.

POST /sales 🔒 sales:create

Membuat transaksi penjualan baru.

Request Body

Parameter	Tipe	Wajib	Keterangan
`customer_id`	integer	✅	ID pelanggan
`sale_type`	string	✅	`goods`, `saldo`, `service`, `mix`
`sale_date`	date	✅	Tanggal penjualan (YYYY-MM-DD)
`due_date`	date	❌	Tanggal jatuh tempo
`notes`	string	❌	Catatan (max: 500)
`discount`	numeric	❌	Diskon total
`tax`	numeric	❌	Pajak
`payment_type`	string	✅	`cash`, `credit`, `partial`, `down_payment`, `prepaid_deduction`
`payment_source`	string	❌	`kas_utama`, `kas_kecil`, `bank_utama`
`paid_amount`	numeric	❌	Jumlah yang dibayar
`items`	array	✅	Daftar item penjualan (min: 1)
`items.*.item_type`	string	✅	`goods`, `saldo`, `service`
`items.*.stock_id`	integer	❌	ID stok (wajib untuk goods)
`items.*.quantity`	numeric	✅	Jumlah (min: 0.01)
`items.*.unit_price`	numeric	✅	Harga satuan
`items.*.discount`	numeric	❌	Diskon per item

DELETE /sales/{id} 🔒 sales:delete

Menghapus penjualan. Tidak bisa menghapus penjualan berstatus completed.

GET /sales/customers 🔒 sales:view

Daftar pelanggan aktif untuk dropdown di form penjualan mobile.

Stock Endpoints

GET /stocks 🔒 stock:view

Daftar stok/produk dengan pagination dan filter.

Query Parameters

Parameter	Tipe	Wajib	Keterangan
`per_page`	integer	❌	Jumlah per halaman (1-100, default: 20)
`search`	string	❌	Cari berdasarkan kode, nama, atau barcode
`category_group_id`	integer	❌	Filter berdasarkan grup kategori
`is_active`	boolean	❌	Filter berdasarkan status aktif
`low_stock`	boolean	❌	Hanya tampilkan stok di bawah minimum
`business_unit_id`	integer	❌	ID unit usaha

GET /stocks/{id} 🔒 stock:view

Detail stok/produk termasuk kategori dan satuan.

GET /stocks/opnames 🔒 stock:view

Daftar stock opname dengan pagination.

Query Parameters

Parameter	Tipe	Wajib	Keterangan
`per_page`	integer	❌	Jumlah per halaman (default: 20)
`status`	string	❌	`draft`, `approved`, `cancelled`
`search`	string	❌	Cari berdasarkan nomor opname atau PIC

POST /stocks/opnames 🔒 stock:opname

Membuat stock opname baru.

Request Body

Parameter	Tipe	Wajib	Keterangan
`opname_date`	date	✅	Tanggal opname (YYYY-MM-DD)
`pic_name`	string	❌	Nama penanggung jawab (max: 100)
`notes`	string	❌	Catatan (max: 1000)
`details`	array	✅	Detail item opname (min: 1)
`details.*.stock_id`	integer	✅	ID stok
`details.*.actual_qty`	numeric	✅	Qty aktual (min: 0)
`details.*.notes`	string	❌	Catatan per item

Daftar Isi

Tokoku ERP API

Authentication

Format Response

Success Response

Paginated Response

Error Response

Error Handling

Auth Endpoints

Request Body

Response (200)

Request Body

Request Body

Request Body

Dashboard Endpoints

Query Parameters

Response (200)

Sales Endpoints

Query Parameters

Request Body

Stock Endpoints

Query Parameters

Query Parameters

Request Body

Catatan Umum