Menu Docs Versi API: v1 (/v1/auth)

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.

API Key (.env): 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:

# Konfigurasi di file .env
API_KEY=pos_secret_token_1234567890

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
namastringYaNama lengkap pengguna
usernamestringYaUsername unik (alpha_dash, min 3 char)
emailstringYaEmail unik dan valid
passwordstringYaPassword minimal 6 karakter
password_confirmationstringYaKonfirmasi password sama dengan password
valueobject/jsonOpsionalData JSON tambahan (telepon, alamat, preferensi, dsb.)
Contoh Request Body (JSON):
{
  "nama": "Andi Pratama",
  "username": "andipratama",
  "email": "andi@example.com",
  "password": "password123",
  "password_confirmation": "password123",
  "value": {
    "phone": "081234567890",
    "address": "Jakarta Barat"
  }
}
Contoh Respon (201 Created):
{
  "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 OK
Mekanisme Pembentukan Kolom 'key': Saat login berhasil, sistem secara otomatis membangkitkan tepat 12 huruf + angka acak, disambung dengan username user, lalu di-hash dengan Bcrypt dan disimpan ke kolom key di tabel users.
Request Body:
{
  "login": "budi",
  "password": "password123"
}
Contoh Respon (200 OK):
{
  "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_usersstringYaIdentifier pengguna (misal: POS-X8K1N9Q4 atau username)
valueobject / stringYaObjek JSON atau String JSON yang ingin diupload
modestringOpsionalreplace (menimpa) atau merge (menggabungkan tanpa menghapus field lama)
Contoh Request cURL Upload ke Kolom 'value':
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}

200 OK Success

Request berhasil diproses secara normal (misal saat login, melihat profil, atau update data).

{
  "status": "success",
  "code": 200,
  "message": "Login successful.",
  "data": { ... }
}
201 Created Created

Resource baru berhasil dibuat di database (misal saat register akun baru).

{
  "status": "success",
  "code": 201,
  "message": "User successfully registered.",
  "data": { "user": { ... } }
}
203 Non-Authoritative Information Transformed

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" }
}
400 Bad Request Client Error

Sintaks request rusak atau parameter identitas wajib tidak disertakan.

{
  "status": "error",
  "code": 400,
  "message": "Bad Request: Identifier pengguna wajib disertakan.",
  "error": "MISSING_IDENTIFIER"
}
401 Unauthorized Unauthorized

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"
}
403 Forbidden Forbidden

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"
}
404 Not Found Not Found

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"
}
422 Unprocessable Content Validation

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."]
  }
}
500 Internal Server Error Server Error

Terjadi kendala pada database atau logika internal server.

{
  "status": "error",
  "code": 500,
  "message": "Internal Server Error: Terjadi kegagalan server.",
  "error": "SERVER_ERROR"
}