Panduan Public API untuk Extension

Dokumen ini ditujukan untuk developer yang ingin membuat extension, dashboard eksternal, bot, middleware, atau layanan tambahan yang terhubung ke backend Hexaflate.

API ini adalah boundary resmi untuk integrasi. Jangan membaca database Otomax atau database Hexaflate langsung dari extension kecuali extension tersebut memang komponen internal yang dikelola oleh owner server.

---

Base URL

Gunakan URL backend yang sama dengan aplikasi mobile.

https://backend-domain-anda.com/v1

Contoh endpoint penuh:

https://backend-domain-anda.com/v1/products?limit=100&search_term=telkomsel

---

Header Umum

Semua endpoint REST publik saat ini berada di bawah /v1. Header legacy seperti X-Token, Session-Key, Auth-Seed tidak dipakai sebagai header publik di /v1. Gunakan satu header Authorization.

Untuk endpoint yang membutuhkan user session:

Authorization: <backend-x-token>:<identifier>:<key>

Format alternatif yang juga diterima adalah Base64 dari nilai di atas:

Authorization: Bearer <base64(backend-x-token-identifier-key)>

Extension mendapatkan identifier dan key dari WebView encrypted authorization yang dikirim oleh aplikasi saat membuka WebView extension (lihat bagian selanjutnya).

Endpoint monitoring seperti /health berada di root backend, bukan /v1, dan tidak membutuhkan header session.

Untuk extension third-party, pola yang disarankan adalah extension menerima identitas user dari WebView encrypted authorization, lalu backend extension memanggil API Hexaflate hanya jika memang diberi akses oleh owner server.

---

Extension Dibuka dari WebView Screen

Extension Hexaflate umumnya dibuka melalui menu dengan route WebView. Jadi extension tidak perlu membuat flow login sendiri. Data user, session, dan token bisa dikirim dari konfigurasi WebView screen arguments.

Di admin panel, buka konfigurasi menu WebView, lalu isi URL dan Custom Headers. Placeholder bisa dipasang di URL maupun header. Saat user membuka WebView, aplikasi mengganti placeholder tersebut dengan nilai session/user yang sedang aktif.

Peringatan: placeholder sensitif seperti {{identifier}}, {{key}}, dan {{x_token}} hanya boleh dikirim ke URL/domain yang dikenal dan dipercaya. Jangan memasang sensitive header atau query parameter pada URL acak, URL milik pihak yang tidak diverifikasi, atau halaman yang bisa diubah oleh pihak lain.

Placeholder penting untuk extension:

Placeholder	Isi
{{identifier}}	Identifier user aktif.
{{key}}	Key session user aktif.
{{x_token}}	Token backend untuk bagian pertama Authorization.
{{user_id}} atau {{kode}}	ID/kode user.
{{nama}}	Nama user/toko.
{{email}}	Email user jika tersedia.
{{saldo}}	Saldo user.
{{komisi}}	Komisi user.
{{poin}}	Poin user.
{{encrypted_authorization}}	Payload authorization terenkripsi untuk integrasi yang tidak ingin menerima session mentah.

Contoh mengirim credential lewat URL:

https://extension.example.com/start?user_id={{kode}}&identifier={{identifier}}&key={{key}}

Contoh mengirim credential lewat Custom Headers:

{
  "X-User-ID": "{{kode}}",
  "Authorization": "{{x_token}}:{{identifier}}:{{key}}"
}

Jika extension perlu memanggil API Hexaflate dari server extension, extension bisa menerima nilai tersebut dari WebView, lalu backend extension meneruskannya sebagai header Authorization API. Jangan expose token dan session ke halaman publik di luar konteks WebView aplikasi.

---

Response dan Error

Tidak semua endpoint memakai envelope response yang sama. Ada endpoint yang mengembalikan object, array, atau response pass-through dari Otomax/config.

Pola response sukses yang umum:

{
  "success": true,
  "message": "Operation completed"
}

Pola response gagal yang umum:

{
  "success": false,
  "message": "Not found"
}

HTTP status yang perlu ditangani extension:

Status	Arti
400	Body atau query tidak valid.
401	Token atau session tidak valid.
403	Akses ditolak.
404	Data tidak ditemukan.
429	Rate limit.
503	Service, database, cache, atau node leader tidak siap.

Untuk transaksi, jangan retry otomatis hanya karena timeout. Cek status transaksi terlebih dahulu dengan /history atau /details_trx.

---

ID Transaksi

Untuk membuat transaksi dari extension, endpoint transaksi dapat diakses melalui API internal server. Hubungi owner server untuk detail implementasi transaksi dari sisi extension.

trxid dipakai backend untuk mendeteksi transaksi berulang. Jika trxid yang sama dikirim lagi untuk kombinasi transaksi yang sama, misalnya produk dan nomor tujuan yang sama, backend akan menolak transaksi tersebut.

Simpan trxid di database extension sebelum memanggil API. Untuk transaksi baru, naikkan angka tersebut. Jika request timeout, gunakan trxid tersebut untuk rekonsiliasi, bukan membuat transaksi baru tanpa pengecekan.

---

User dan Profil

GET /infouser

Mengambil data user dari session yang sedang digunakan.

Headers:

Authorization: <backend-x-token>:<identifier>:<key>

Request:

GET /infouser HTTP/1.1

Response example:

{
  "kode": "OX17",
  "nama": "OX RELOAD",
  "nama_pemilik": null,
  "alamat": "Pdg",
  "email": null,
  "saldo": 2516,
  "kode_level": "MBK00"
}

Catatan: field dapat mengikuti struktur data reseller pada instalasi Otomax.

GET /senders

Mengambil nomor pengirim/sender yang terdaftar untuk user.

Headers:

Authorization: <backend-x-token>:<identifier>:<key>

Request:

GET /senders HTTP/1.1

Response example:

[
  {
    "pengirim": "+62852656356582",
    "tipe_pengirim": "S",
    "kode_reseller": "OX01"
  },
  {
    "pengirim": "+6285215258485",
    "tipe_pengirim": "W",
    "kode_reseller": "OX17"
  }
]

---

Produk dan Operator

GET /products

Mengambil daftar produk dan harga final untuk user session.

Headers:

Authorization: <backend-x-token>:<identifier>:<key>

Query parameters:

Parameter	Tipe	Wajib	Keterangan
operators	string	Tidak	Kode operator dipisah koma, contoh TELKOMSEL,INDOSAT.
limit	number	Tidak	Batas jumlah produk.
search_term	string	Tidak	Filter nama/kode produk.
operator_filter	string	Tidak	Filter operator tambahan.
ignore_free	boolean	Tidak	Jika true, produk gratis dapat diabaikan sesuai konfigurasi.

Request:

GET /products?operators=TELKOMSEL&limit=50&search_term=data&ignore_free=true HTTP/1.1

Response example:

[
  {
    "kode": "SCH10",
    "nama": "Telkomsel10",
    "harga_jual": 10120,
    "aktif": 1,
    "gangguan": 0,
    "kode_operator": "S",
    "kosong": 0,
    "harga_tetap": 1,
    "sms_end_user": 0,
    "postpaid": 0,
    "poin": 0,
    "rumus_harga": 0,
    "qty": null,
    "operator_nama": "Telkomsel"
  },
  {
    "kode": "DNF200",
    "nama": "DANA 200.000",
    "harga_jual": 200084,
    "aktif": 1,
    "gangguan": 0,
    "kode_operator": "DANA",
    "kosong": 0,
    "harga_tetap": 1,
    "sms_end_user": 0,
    "postpaid": 0,
    "poin": 0,
    "rumus_harga": 0,
    "qty": null,
    "operator_nama": "DANA"
  }
]

GET /operators

Mengambil data operator.

Headers:

Authorization: <backend-x-token>:<identifier>:<key>

Query parameters:

Parameter	Tipe	Wajib	Keterangan
operators	string	Tidak	Kode operator dipisah koma. Jika kosong, backend dapat mengembalikan semua operator yang tersedia.

Request:

GET /operators?operators=TELKOMSEL,INDOSAT HTTP/1.1

Response example:

[
  {
    "kode": "TELKOMSEL",
    "nama": "Telkomsel",
    "catatan": "TSEL,TELKOMSEL"
  }
]

GET /operator-list

Mengambil list operator yang dapat dipakai untuk filter produk.

Headers:

Authorization: <backend-x-token>:<identifier>:<key>

Request:

GET /operator-list HTTP/1.1

Response example:

[
  {
    "kode": "TELKOMSEL",
    "nama": "Telkomsel"
  },
  {
    "kode": "INDOSAT",
    "nama": "Indosat"
  }
]

---

Transaksi

GET /history

Mengambil riwayat transaksi user.

Headers:

Authorization: <backend-x-token>:<identifier>:<key>

Query parameters:

Parameter	Tipe	Wajib	Keterangan
cursor	string	Tidak	Cursor halaman berikutnya.
page_size	number	Tidak	Jumlah data per halaman, contoh 30.
tgl_start	string	Tidak	Tanggal awal filter.
tgl_end	string	Tidak	Tanggal akhir filter.
status	string	Tidak	Filter status transaksi.
dest	string	Tidak	Filter tujuan.

Request:

GET /history?page_size=30&status=&dest= HTTP/1.1

Response example:

{
  "data": [
    {
      "kode": "1234567890",
      "tanggal": "2026-06-27 10:00:00",
      "produk": "TSEL10",
      "tujuan": "628123456789",
      "status": "SUKSES",
      "harga": 10700,
      "sn": "SN123456"
    }
  ],
  "next_cursor": "cursor-value",
  "has_more": true
}

GET /details_trx

Mengambil detail transaksi.

Headers:

Authorization: <backend-x-token>:<identifier>:<key>

Query parameters:

Parameter	Tipe	Wajib	Keterangan
kode	string	Ya jika kode_inbox kosong	Kode transaksi.
kode_inbox	string	Tidak	Kode inbox jika detail dicari dari inbox.

Request:

GET /details_trx?kode=1234567890 HTTP/1.1

Response example:

{
  "kode": "1234567890",
  "status": "SUKSES",
  "produk": "TSEL10",
  "tujuan": "628123456789",
  "harga": 10700,
  "serial_number": "SN123456",
  "message": "Transaksi sukses"
}

GET /receipt

Mengambil receipt transaksi.

Headers:

Authorization: <backend-x-token>:<identifier>:<key>

Query parameters:

Parameter	Tipe	Wajib	Keterangan
kode	string	Ya	Kode transaksi.

Request:

GET /receipt?kode=1234567890 HTTP/1.1

Response example:

{
  "success": true,
  "data": {
    "title": "Struk Transaksi",
    "kode": "1234567890",
    "tanggal": "2026-06-27 10:00:00",
    "produk": "TSEL10",
    "tujuan": "628123456789",
    "status": "SUKSES",
    "sn": "SN123456",
    "total": 10700
  }
}

---

Tiket Deposit

GET /tiketstatus

Mengecek status tiket deposit.

Headers:

Authorization: <backend-x-token>:<identifier>:<key>

Query parameters:

Parameter	Tipe	Wajib	Keterangan
tikets	string	Ya	Satu atau beberapa kode tiket dipisah koma.

Request:

GET /tiketstatus?tikets=TKT12345,TKT12346 HTTP/1.1

Response example:

[
  {
    "kode_tiket": "TKT12345",
    "nominal": 100000,
    "status": "PENDING"
  }
]

---

Saldo, Mutasi, Poin, Komisi, Hadiah

GET /balanceid

Menampilkan saldo dan ID user.

Headers:

Authorization: <backend-x-token>:<identifier>:<key>

Request:

GET /balanceid HTTP/1.1

Response example:

{
  "balance": 1250000,
  "id": "RS001"
}

GET /estatement

Mengambil mutasi saldo user.

Headers:

Authorization: <backend-x-token>:<identifier>:<key>

Query parameters:

Parameter	Tipe	Wajib	Keterangan
cursor	string	Tidak	Cursor halaman berikutnya.
page_size	number	Tidak	Jumlah data per halaman.
tgl_start	string	Tidak	Tanggal awal.
tgl_end	string	Tidak	Tanggal akhir.
keterangan	string	Tidak	Filter keterangan.

Request:

GET /estatement?page_size=30&keterangan= HTTP/1.1

Response example:

{
  "data": [
    {
      "tanggal": "2026-06-27 10:00:00",
      "keterangan": "TRX TSEL10 628123456789",
      "debet": 10700,
      "kredit": 0,
      "saldo_akhir": 1250000
    }
  ],
  "next_cursor": "cursor-value",
  "has_more": true
}

GET /poinid

Mengambil jumlah poin user.

Headers:

Authorization: <backend-x-token>:<identifier>:<key>

Response example:

{
  "id": "RS001",
  "poin": 2500
}

GET /poininfo

Mengambil informasi aturan penukaran poin.

Headers:

Authorization: <backend-x-token>

Response example:

{
  "enabled": true,
  "rate": 1,
  "minimum_exchange": 1000,
  "description": "1000 poin dapat ditukar sesuai konfigurasi server"
}

GET /komisi

Mengambil jumlah komisi user.

Headers:

Authorization: <backend-x-token>:<identifier>:<key>

Response example:

{
  "success": true,
  "message": "Commission exchange submitted",
  "data": {
    "amount": 50000,
    "status": "PENDING"
  }
}

GET /list_hadiah

Mengambil daftar hadiah.

Headers:

Authorization: <backend-x-token>:<identifier>:<key>

Response example:

[
  {
    "id": 1,
    "nama": "Voucher Belanja",
    "poin": 1000,
    "aktif": true
  }
]

GET /check_exchanged_hadiah

Mengecek hadiah yang sudah ditukar user.

Headers:

Authorization: <backend-x-token>:<identifier>:<key>

Response example:

[
  {
    "hadiah_id": 1,
    "nama": "Voucher Belanja",
    "status": "PENDING",
    "created_at": "2026-06-27 10:00:00"
  }
]

---

Referral dan Downline

GET /referral

Mengambil daftar kode referral.

Headers:

Authorization: <backend-x-token>:<identifier>:<key>

Response example:

[
  {
    "id": "RS001",
    "referal": "REFCODE123",
    "markup": 5
  }
]

GET /listDownline

Mengambil daftar downline dari referral user.

Headers:

Authorization: <backend-x-token>:<identifier>:<key>

Response example:

[
  {
    "id": "RS010",
    "nama": "Downline 1",
    "referal": "REFCODE123",
    "markup": 5
  }
]

GET /revrefcheck

Mengecek pemilik atau status kode referral.

Headers:

Authorization: <backend-x-token>:<identifier>:<key>

Query parameters:

Parameter	Tipe	Wajib	Keterangan
referral	string	Ya	Kode referral yang dicek.

Request:

GET /revrefcheck?referral=REFCODE123 HTTP/1.1

Response example:

{
  "exists": true,
  "id": "RS001",
  "referral": "REFCODE123"
}

---

Feedback

POST /feedback

Mengirim feedback dari user atau extension.

Headers:

Content-Type: application/json

Body:

{
  "feedback": "Fitur berjalan baik",
  "name": "Budi",
  "user_id": "RS001"
}

Response example:

{
  "success": true,
  "message": "Feedback submitted successfully"
}

---

Health

Endpoint monitoring berada di root backend, bukan /v1, dan tidak membutuhkan header session.

GET /health

Basic health check.

Response example:

{
  "status": "healthy",
  "timestamp": "2026-06-27T10:00:00Z"
}

---

Minimal Client JavaScript

const baseUrl = "https://backend-domain-anda.com/v1";

function authorizationHeader() {
  const parts = [
    process.env.HEXAFLATE_X_TOKEN,
    process.env.HEXAFLATE_IDENTIFIER,
    process.env.HEXAFLATE_KEY,
  ];
  return parts.join(":");
}

async function api(path, options = {}) {
  const response = await fetch(baseUrl + path, {
    ...options,
    headers: {
      "Authorization": authorizationHeader(),
      "Content-Type": "application/json",
      ...options.headers,
    },
  });

  const text = await response.text();
  const body = text ? JSON.parse(text) : null;

  if (!response.ok) {
    throw new Error(body?.message || `Hexaflate API error ${response.status}`);
  }

  return body;
}

const user = await api("/infouser");
const products = await api("/products?limit=100&search_term=telkomsel");

---

Extension Security Checklist

• Jangan expose nilai Authorization, x_token, identifier, key, atau App Check token di frontend publik.
• Simpan credential hanya di backend extension atau secure storage yang disetujui owner server.
• Gunakan HTTPS untuk semua request.
• Catat semua transaksi extension dengan trxid, user id, IP, timestamp, dan response backend.
• Jangan retry endpoint mutasi tanpa idempotency atau pengecekan status.
• Validasi input user sebelum meneruskan request ke backend Hexaflate.
• Batasi endpoint yang dapat dipanggil extension sesuai kebutuhan bisnis.