Dokumentasi Lengkap API POS Market Kita
Panduan integrasi autentikasi, API Key, mekanisme pembentukan kolom key, upload data JSON ke kolom value, dan katalog respon HTTP status code.
pos_secret_token_1234567890
1. Overview & Autentikasi API Key
Semua endpoint di bawah grup /v1/auth diproteksi oleh middleware API Key. Nilai API Key disimpan pada file konfigurasi lingkungan .env server:
Setiap request API wajib menyertakan API Key tersebut melalui salah satu metode berikut:
- Header HTTP (Paling Disarankan):
X-API-KEY: pos_secret_token_1234567890 - Authorization Header:
Authorization: Bearer pos_secret_token_1234567890 - Query Parameter:
?api_key=pos_secret_token_1234567890
2. Ringkasan Endpoint API
| Method | Endpoint Path | Header Wajib | Respon HTTP | Fungsi |
|---|---|---|---|---|
| POST | /v1/auth/register | X-API-KEY | 201 / 422 | Registrasi user baru (ID otomatis POS-XXXX, role: user, key: null) |
| POST | /v1/auth/login | X-API-KEY | 200 / 401 / 422 | Login, generate 12 acak + username, dihash ke kolom key |
| GET | /v1/auth/me | X-API-KEY, X-USER-ID | 200 / 400 / 404 | Ambil profil user berdasarkan ID Users |
| POST | /v1/auth/update-value | X-API-KEY | 200 / 422 | Upload/update JSON ke kolom 'value' |
| GET | /v1/auth/status-demo/{code} | X-API-KEY | 200, 201, 203... | Simulasi uji coba seluruh HTTP Status Code |
POST /v1/auth/register
Respon: 201 Created
Mendaftarkan pengguna baru ke tabel users.
Secara default:
• id_users dibuat otomatis dengan format POS-XXXXXXXX (huruf & angka acak lebih dari 5 karakter).
• role otomatis bernilai user.
• key bernilai null (karena hanya dibuat ketika user login).
Form Parameter yang Diisi:
| Field | Tipe | Wajib? | Keterangan |
|---|---|---|---|
| nama | string | Ya | Nama lengkap pengguna |
| username | string | Ya | Username unik (alpha_dash, min 3 char) |
| string | Ya | Email unik dan valid | |
| password | string | Ya | Password minimal 6 karakter |
| password_confirmation | string | Ya | Konfirmasi password sama dengan password |
| value | object/json | Opsional | Data JSON tambahan (telepon, alamat, preferensi, dsb.) |
{
"nama": "Andi Pratama",
"username": "andipratama",
"email": "andi@example.com",
"password": "password123",
"password_confirmation": "password123",
"value": {
"phone": "081234567890",
"address": "Jakarta Barat"
}
}
{
"status": "success",
"code": 201,
"message": "User successfully registered.",
"data": {
"user": {
"id": 5,
"id_users": "POS-M8K9A2P1",
"nama": "Andi Pratama",
"username": "andipratama",
"email": "andi@example.com",
"role": "user",
"key": null,
"value": {
"phone": "081234567890",
"address": "Jakarta Barat"
}
}
}
}
POST /v1/auth/login
Respon: 200 OKkey di tabel users.
{
"login": "budi",
"password": "password123"
}
{
"status": "success",
"code": 200,
"message": "Login successful.",
"data": {
"user": {
"id": 2,
"id_users": "POS-X8K1N9Q4",
"username": "budi",
"role": "user",
"key": "$2y$12$N9HwJc8K0pE9b1Y..."
},
"login_key_details": {
"random_12": "x9K2p0L1q8Wa",
"username": "budi",
"raw_key_combined": "x9K2p0L1q8Wabudi",
"hashed_key_stored": "$2y$12$N9HwJc8K0pE9b1Y..."
}
}
}
3. Panduan Upload & Update Data ke Kolom 'value' (JSON)
Kolom value dapat menyimpan struktur JSON fleksibel apa pun (objek bersarang, array, string, number, boolean). Untuk memperbarui atau mengunggah data ke kolom ini, gunakan endpoint POST /v1/auth/update-value.
| Field | Tipe | Wajib? | Keterangan |
|---|---|---|---|
| id_users | string | Ya | Identifier pengguna (misal: POS-X8K1N9Q4 atau username) |
| value | object / string | Ya | Objek JSON atau String JSON yang ingin diupload |
| mode | string | Opsional | replace (menimpa) atau merge (menggabungkan tanpa menghapus field lama) |
curl -X POST "https://pos.cloudsn.id/v1/auth/update-value" \
-H "X-API-KEY: pos_secret_token_1234567890" \
-H "Content-Type: application/json" \
-d '{
"id_users": "POS-X8K1N9Q4",
"mode": "merge",
"value": {
"whatsapp": "081234567890",
"alamat_toko": "Jl. Gatot Subroto No. 88, Jakarta",
"bank_account": {
"bank": "BCA",
"account_number": "1234567890",
"account_name": "Budi Santoso"
},
"saldo_tersedia": 2500000
}
}'
4. Katalog Lengkap Respon Status Code (200, 201, 203, 400, 401, ...)
Anda dapat menguji respon status kode apa pun secara langsung lewat endpoint simulasi: GET /v1/auth/status-demo/{kode}
Request berhasil diproses secara normal (misal saat login, melihat profil, atau update data).
{
"status": "success",
"code": 200,
"message": "Login successful.",
"data": { ... }
}
Resource baru berhasil dibuat di database (misal saat register akun baru).
{
"status": "success",
"code": 201,
"message": "User successfully registered.",
"data": { "user": { ... } }
}
Permintaan berhasil, namun metadata payload berasal dari proxy/cache termodifikasi.
{
"status": "success",
"code": 203,
"message": "Metadata berasal dari cache proxy sekunder.",
"meta": { "source": "cache-proxy" }
}
Sintaks request rusak atau parameter identitas wajib tidak disertakan.
{
"status": "error",
"code": 400,
"message": "Bad Request: Identifier pengguna wajib disertakan.",
"error": "MISSING_IDENTIFIER"
}
API Key hilang/salah, atau kombinasi username dan password salah.
{
"status": "error",
"code": 401,
"message": "Unauthorized: The provided API Key is invalid.",
"error": "INVALID_API_KEY"
}
Klien terautentikasi tetapi tidak memiliki hak akses/otoritas (role privilege).
{
"status": "error",
"code": 403,
"message": "Forbidden: Anda tidak memiliki akses ke fitur ini.",
"error": "FORBIDDEN"
}
Data user dengan ID Users tersebut atau endpoint tidak ditemukan.
{
"status": "error",
"code": 404,
"message": "Not Found: User with specified ID does not exist.",
"error": "USER_NOT_FOUND"
}
Data request gagal lolos validasi (email sudah dipakai, password kurang dari 6 digit, dsb).
{
"status": "error",
"code": 422,
"message": "Validation error.",
"errors": {
"email": ["Email ini sudah terdaftar."],
"password": ["Password minimal 6 karakter."]
}
}
Terjadi kendala pada database atau logika internal server.
{
"status": "error",
"code": 500,
"message": "Internal Server Error: Terjadi kegagalan server.",
"error": "SERVER_ERROR"
}