API & Webhooks

Overview

LancarTech menyediakan REST API yang lengkap untuk memungkinkan integrasi dengan sistem eksternal seperti CRM, aplikasi akuntansi, portal custom, atau sistem monitoring pihak ketiga. Seluruh data yang tersedia di dashboard admin dapat diakses secara programmatic melalui API ini.

Selain API untuk mengambil dan memanipulasi data, LancarTech juga menyediakan sistem Webhook yang mengirimkan notifikasi otomatis ke endpoint Anda setiap kali terjadi event penting — seperti subscriber baru terdaftar, invoice dibayar, atau layanan diaktifkan. Kombinasi API + Webhook memungkinkan Anda membangun integrasi dua arah yang powerful.

Autentikasi API

Semua request ke API memerlukan autentikasi menggunakan API key. API key berfungsi sebagai identitas dan otorisasi aplikasi Anda. Setiap tenant dapat membuat beberapa API key dengan scope yang berbeda-beda.

Membuat API Key

Penggunaan Bearer Token

Sertakan API key sebagai Bearer token di header Authorization pada setiap request:

Base URL & Format

Semua endpoint API LancarTech berada di bawah base URL berikut:

Format Response (JSON Envelope)

Semua response API menggunakan format envelope JSON yang konsisten. Baik success maupun error, struktur response-nya selalu sama:

{
  "data": {
    "id": "01HWXYZ123456",
    "name": "John Doe",
    "email": "john@example.com"
  },
  "meta": {
    "total": 150,
    "next_cursor": "eyJpZCI6IjAxSFdY..."
  },
  "error": null
}

Format Error Response

{
  "data": null,
  "meta": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'email' is required.",
    "details": [
      { "field": "email", "message": "must not be empty" }
    ]
  }
}

Endpoint Utama

Berikut adalah daftar kelompok endpoint utama yang tersedia di API LancarTech. Setiap kelompok endpoint mendukung operasi CRUD standar (Create, Read, Update, Delete) kecuali disebutkan lain.

Contoh Request

Berikut adalah contoh-contoh request API menggunakan curl. Anda dapat menggunakan tools seperti Postman, Insomnia, atau library HTTP di bahasa pemrograman pilihan Anda.

List Subscribers

Mengambil daftar subscriber dengan pagination dan filter pencarian.

curl -X GET "https://api.lancartech.com/api/v1/subscribers?limit=25&search=john" \
  -H "Authorization: Bearer ltk_live_a1b2c3d4..." \
  -H "Content-Type: application/json"

Response berisi array subscriber di field data beserta meta.total dan meta.next_cursor untuk pagination.

Detail Subscriber

Mengambil detail lengkap satu subscriber berdasarkan ID.

curl -X GET "https://api.lancartech.com/api/v1/subscribers/01HWXYZ123456" \
  -H "Authorization: Bearer ltk_live_a1b2c3d4..."

Buat Invoice Manual

Membuat invoice secara manual untuk service tertentu. Berguna untuk tagihan tambahan di luar siklus billing otomatis.

curl -X POST "https://api.lancartech.com/api/v1/invoices" \
  -H "Authorization: Bearer ltk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "01HWXYZ789012",
    "amount": 150000,
    "due_date": "2026-05-01",
    "description": "Tagihan Internet Mei 2026",
    "items": [
      {
        "description": "Paket Internet 20 Mbps",
        "quantity": 1,
        "unit_price": 150000
      }
    ]
  }'

Record Pembayaran Manual

Mencatat pembayaran cash atau transfer manual yang diterima oleh admin. Invoice akan otomatis ter-update menjadi Paid dan service di-reactivate jika suspended.

curl -X POST "https://api.lancartech.com/api/v1/payments" \
  -H "Authorization: Bearer ltk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_id": "01HWXYZ345678",
    "amount": 150000,
    "method": "cash",
    "note": "Bayar di kantor"
  }'

List Invoice dengan Filter

Mengambil daftar invoice dengan filter status dan range tanggal.

curl -X GET "https://api.lancartech.com/api/v1/invoices?status=overdue&from=2026-04-01&to=2026-04-30&limit=50" \
  -H "Authorization: Bearer ltk_live_a1b2c3d4..."

Webhook System

Webhook memungkinkan aplikasi Anda menerima notifikasi secara real-time setiap kali terjadi event penting di sistem LancarTech. Alih-alih melakukan polling ke API secara berkala, webhook akan otomatis mengirim HTTP POST ke URL endpoint yang Anda tentukan.

Webhook sangat berguna untuk skenario seperti: sinkronisasi data subscriber ke CRM, notifikasi pembayaran ke Slack/Telegram, update dashboard real-time, trigger workflow otomatis di sistem internal, atau audit trail di sistem eksternal.

Setup Webhook

Konfigurasi webhook dilakukan melalui dashboard admin. Anda dapat membuat beberapa webhook endpoint dengan event yang berbeda-beda.

Event Types

Berikut adalah daftar lengkap event yang dapat dikirim melalui webhook. Setiap event memiliki nama unik dan payload yang spesifik.

Webhook Payload

Setiap webhook dikirim sebagai HTTP POST request dengan body JSON. Berikut adalah struktur payload webhook dan contoh lengkapnya.

Struktur Payload

{
  "id": "evt_01HWXYZ987654",
  "event": "invoice.paid",
  "created_at": "2026-04-05T10:30:00Z",
  "data": {
    "invoice_id": "01HWXYZ345678",
    "invoice_number": "INV-2026-0042",
    "subscriber_id": "01HWXYZ123456",
    "subscriber_name": "John Doe",
    "service_id": "01HWXYZ789012",
    "amount": 150000,
    "paid_at": "2026-04-05T10:29:55Z",
    "payment_method": "bank_transfer",
    "payment_channel": "BCA Virtual Account"
  }
}

Header Webhook

Setiap webhook request menyertakan header berikut untuk verifikasi dan identifikasi:

Verifikasi Signature

Selalu verifikasi signature webhook sebelum memproses payload. Berikut contoh verifikasi menggunakan Node.js:

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Pada handler webhook Anda:
app.post('/webhooks/lancartech', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const isValid = verifyWebhook(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Proses event...
  const { event, data } = req.body;
  console.log('Event diterima:', event, data);

  res.status(200).json({ received: true });
});

Retry & Delivery

LancarTech memastikan webhook terkirim dengan mekanisme retry otomatis. Jika endpoint Anda tidak merespons atau mengembalikan error, sistem akan mencoba mengirim ulang webhook secara bertahap.

Jadwal Retry (Exponential Backoff)

Status Delivery

Manual Retry

Webhook yang berstatus Failed dapat dikirim ulang secara manual dari dashboard admin. Buka Pengaturan > Webhooks > Delivery Log untuk melihat riwayat pengiriman dan status setiap event. Klik tombol "Retry" pada event yang gagal untuk mengirim ulang. Anda juga dapat mengirim test event dari halaman konfigurasi webhook untuk memvalidasi endpoint.

Rate Limiting

Untuk menjaga stabilitas dan performa sistem, API LancarTech menerapkan rate limiting berdasarkan plan SaaS yang Anda gunakan. Limit dihitung per API key per menit.

* Plan Custom memiliki limit yang disesuaikan berdasarkan kesepakatan. Hubungi tim sales untuk informasi lebih lanjut.

Header Rate Limit

Setiap response API menyertakan header rate limit agar aplikasi Anda dapat mengatur tempo request secara proaktif:

Best Practices

Ikuti panduan best practices berikut untuk memastikan integrasi API dan Webhook Anda berjalan dengan optimal, aman, dan handal.