API Documentation

REST API untuk integrasi eksternal. Base URL: /api/v1

Autentikasi

Semua endpoint (kecuali login) membutuhkan header Authorization: Bearer <token>. Token berlaku selama 24 jam.

POST/api/v1/auth/login

Request Body (JSON)

Field	Keterangan
`email`	string — wajib. Email akun.
`password`	string — wajib. Password akun.

Response 200 OK

Field	Keterangan
`token`	string — Bearer token (HS256 JWT).
`user`	{ id, name, email, role }
`expiresIn`	number — durasi token dalam detik (86400 = 24 jam).

Error Codes

400email atau password tidak disertakan

401email atau password salah, atau akun tidak aktif

Contoh

curl -X POST /api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"rahasia123"}'

{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "user": {
    "id": "clx...",
    "name": "Budi Santoso",
    "email": "[email protected]",
    "role": "STAFF"
  },
  "expiresIn": 86400
}

POST/api/v1/email/sendrequires token

Kirim email menggunakan konfigurasi SMTP central inbox. Pengirim disesuaikan dengan domainEmail user yang login.

Request Body (JSON)

Field	Keterangan
`to`	string — wajib. Alamat penerima (bisa multiple dipisah koma).
`subject`	string — wajib. Subjek email.
`body`	string — wajib. Isi email.
`cc`	string — opsional. Alamat CC.
`isHtml`	boolean — opsional. Jika true, body dikirim sebagai HTML (default: false).

Response 200 OK

Field	Keterangan
`ok`	boolean — true jika berhasil.
`message`	string — pesan konfirmasi.

Error Codes

400to, subject, atau body tidak disertakan

401token tidak ada, tidak valid, atau sudah kadaluarsa

503central inbox belum dikonfigurasi oleh admin

500gagal mengirim email (error SMTP)

Contoh

curl -X POST /api/v1/email/send \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "subject": "Penawaran Harga",
    "body": "<p>Halo, berikut penawaran kami...</p>",
    "isHtml": true
  }'

{
  "ok": true,
  "message": "Email berhasil dikirim"
}

Member Digital

Untuk sistem eksternal (POS/kasir/CRM) mengambil data member digital WhatsApp dan mencatat transaksi belanja beserta poinnya. Poin dihitung sepenuhnya oleh sistem Anda — API ini hanya menyimpan apa yang dikirim. Autentikasi pakai header X-API-Key: <key> (atau Authorization: Bearer <key>), bukan token login biasa — ambil/generate API key di aplikasi: Plugin → WhatsApp → Member Digital → Setup → Integrasi API.

GET/api/v1/member-digital/membersrequires X-API-Key

Ambil data member. Pakai memberId atau waId untuk 1 member, atau tanpa query untuk daftar semua member (paginasi).

Request Body (JSON)

Field	Keterangan
`memberId`	string — opsional. ID member (angka di kartu/barcode). Ambil 1 member.
`waId`	string — opsional. Nomor WhatsApp pendaftar (format 62xxxx). Ambil 1 member.
`page`	number — opsional. Dipakai saat tanpa memberId/waId (daftar semua member). Default 1.
`limit`	number — opsional. Maks 200, default 50.

Response 200 OK

Field	Keterangan
`member`	{ memberId, waId, name, birthDate, address, provinsi, kabupatenKota, points, totalSpend, status, cardImageUrl, createdAt, updatedAt } — jika query memberId/waId
`members`	array of member — jika tanpa query
`pagination`	{ page, limit, total, totalPages } — jika tanpa query

Error Codes

401API key kosong atau salah

404member dengan memberId/waId tersebut tidak ditemukan

Contoh

curl -H "X-API-Key: <api-key>" \
  "/api/v1/member-digital/members?memberId=12345678901234"

{
  "member": {
    "memberId": "12345678901234",
    "waId": "628123456789",
    "name": "IRWAN HERMAWAN",
    "birthDate": "1990-08-17",
    "address": "Jl. Contoh No. 1, RT 01/RW 02",
    "provinsi": { "kode": "31", "nama": "DKI Jakarta" },
    "kabupatenKota": { "kode": "3171", "nama": "Kota Jakarta Selatan" },
    "points": 120,
    "totalSpend": 1250000,
    "status": "active",
    "cardImageUrl": "https://.../cards/xxxx.png",
    "createdAt": "2026-01-10T03:12:00.000Z",
    "updatedAt": "2026-02-01T09:00:00.000Z"
  }
}

POST/api/v1/member-digital/transactionsrequires X-API-Key

Catat 1 transaksi belanja beserta poinnya untuk seorang member. Nominal & poin langsung ditambahkan ke saldo member.

Request Body (JSON)

Field	Keterangan
`memberId`	string — salah satu wajib (memberId atau waId). ID member tujuan.
`waId`	string — salah satu wajib. Nomor WA member tujuan (dipakai jika tidak kirim memberId).
`amount`	number — wajib. Nominal belanja (Rp), harus > 0.
`points`	number — wajib. Poin untuk transaksi ini (boleh negatif untuk koreksi/redeem).
`note`	string — opsional. Catatan bebas, mis. nomor invoice.

Response 200 OK

Field	Keterangan
`ok`	boolean — true jika berhasil.
`transaction`	{ id, amount, points, note, createdAt }
`member`	{ memberId, waId, name, points, totalSpend } — saldo terbaru setelah transaksi

Error Codes

400amount ≤ 0, points bukan angka, atau memberId & waId dua-duanya kosong

401API key kosong atau salah

404member dengan memberId/waId tersebut tidak ditemukan

Contoh

curl -X POST /api/v1/member-digital/transactions \
  -H "X-API-Key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "memberId": "12345678901234",
    "amount": 150000,
    "points": 15,
    "note": "Order #INV-2026-0001"
  }'

{
  "ok": true,
  "transaction": {
    "id": "cmxxxxxx",
    "amount": 150000,
    "points": 15,
    "note": "Order #INV-2026-0001",
    "createdAt": "2026-02-01T09:00:00.000Z"
  },
  "member": {
    "memberId": "12345678901234",
    "waId": "628123456789",
    "name": "IRWAN HERMAWAN",
    "points": 135,
    "totalSpend": 1400000
  }
}

Helix Tasks Internal API · 2026