Akses API

Lensiro POS punya API resmi yang hanya membaca. Dengan API ini, program lain bisa mengambil data toko Anda secara otomatis: spreadsheet akuntan yang menarik penjualan setiap pagi, toko online yang mencocokkan stok, atau dasbor buatan sendiri.

Halaman ini ditulis untuk dua pembaca. Pemilik toko cukup membaca Membuat kunci API. Sisanya untuk developer yang membuat programnya.

Hanya membaca. API tidak bisa membuat, mengubah, atau menghapus apa pun. Nota, pembayaran, dan stok hanya ditulis dari aplikasi Lensiro POS, supaya penomoran nota dan buku stok tetap utuh.

Apa yang bisa dibaca#

Tidak tersedia lewat API: resep dan data mata pelanggan, kas, pembelian, pesanan lab, dan ringkasan laporan.

Kalau Anda hanya ingin bertanya tentang toko lewat Claude atau ChatGPT, tidak perlu API. Pakai Koneksi AI.

Membuat kunci API#

Program lain masuk ke toko Anda dengan kunci API, bukan dengan email dan kata sandi.

1. Buka Pengaturan → API (di kelompok Akses).
2. Tekan Buat kunci API.
3. Isi Nama, misalnya Laporan akuntan atau Sinkron toko online, supaya nanti mudah dikenali.
4. Di Akses, centang data yang boleh dibaca: Penjualan, Barang & stok, Pelanggan, atau Harga modal (HPP). Centang seperlunya saja.
5. Tekan Buat.
6. Kunci tampil di layar Simpan kunci ini sekarang. Tekan Salin kunci, tempel di program yang memakainya atau simpan di tempat aman, lalu tekan Sudah saya simpan.

Kunci hanya ditampilkan sekali. Lensiro POS tidak menyimpan kuncinya, hanya sidik jarinya. Kalau kunci hilang, cabut lalu buat yang baru.

Halaman yang sama menampilkan Alamat API dan sebuah Contoh perintah, masing-masing dengan tombol Salin. Setiap kunci di Kunci aktif menunjukkan namanya, potongan kunci seperti lpos_Ab3x…9QzK, akses yang dicentang, siapa yang membuatnya, kapan terakhir dipakai, dan pemakaian hari ini, misalnya 312 / 2.000 hari ini.

Siapa yang boleh membuat kunci#

Membuat dan mencabut kunci butuh izin Kelola Kunci API. Secara bawaan hanya Pemilik yang memegangnya. Izin ini tidak termasuk di templat mana pun, termasuk Admin Toko. Pemilik bisa memberikannya ke peran lain di Pengaturan → Pengguna → Role & Izin. Siapa pun yang memegang izin ini melihat, membuat, dan mencabut semua kunci toko.

Kunci bekerja atas nama pembuatnya#

Kunci membaca atas nama orang yang membuatnya, dan tidak pernah lebih dari yang boleh dilihat perannya:

• Akses yang bisa dicentang hanya yang boleh dilihat peran Anda. Yang lain nonaktif dengan keterangan Peran Anda tidak bisa melihat ….
• Harga modal (HPP) hanya keluar kalau pembuat kunci punya izin Lihat Harga Modal & HPP dan kuncinya dicentang Harga modal. Kotak itu tidak pernah tercentang dengan sendirinya.
• Kalau izin peran pembuatnya dikurangi kemudian, kunci ikut menyempit pada panggilan berikutnya.
• Kunci langsung mati kalau pembuatnya dikeluarkan dari toko, dinonaktifkan, atau kehilangan izin Kelola Kunci API. Kalau seorang karyawan berhenti, kunci buatannya ikut berhenti bekerja.

Akses kunci tidak bisa diubah setelah dibuat. Untuk akses yang berbeda, buat kunci baru lalu cabut yang lama. Satu toko boleh punya paling banyak 5 kunci aktif.

Mencabut kunci#

Tekan Cabut pada kuncinya, lalu Cabut kunci. Program yang memakainya langsung ditolak. Pencabutan tidak bisa dibatalkan dan tidak menghapus data toko apa pun.

Mengelola kunci butuh internet. Tanpa internet, tombolnya tetap tampil tetapi nonaktif.

Untuk developer: dasar#

Alamat dasar

https://api.pos.lensiro.com/v1

Salin dari Alamat API di Pengaturan → API supaya pasti sama.

Autentikasi. Kirim kunci di header X-Api-Key pada setiap panggilan. Contoh di halaman ini menyimpan kunci di variabel LENSIRO_KEY lebih dulu:

export LENSIRO_KEY="lpos_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
curl -H "X-Api-Key: $LENSIRO_KEY" https://api.pos.lensiro.com/v1/toko

• Kunci selalu diawali lpos_ dan panjangnya tepat 48 karakter.
• Kunci hanya dibaca dari header X-Api-Key. Header Authorization dan parameter di URL tidak pernah dibaca, jadi jangan menaruh kunci di alamat.
• Panggil API dari server, skrip, atau otomasi seperti cron, Google Apps Script, atau Power Query. Peramban memblokir panggilan langsung dari halaman web, dan kunci di kode halaman web bisa dibaca siapa saja.
• Semua endpoint memakai metode GET. Metode lain dijawab 405.
• Setiap panggilan dibatasi 20 detik.

Format data

• Uang selalu bilangan bulat rupiah: 1400000 berarti Rp 1.400.000.
• Jumlah barang berupa angka dengan paling banyak 3 desimal, misalnya 0.5.
• Tanggal bisnis (tanggal nota, janji ambil, tanggal bayar) berformat YYYY-MM-DD menurut kalender toko (WIB).
• Waktu kejadian (occurredAt, updatedAt, canceledAt, …) berformat RFC 3339 dalam UTC, misalnya 2026-10-12T03:15:42Z.
• Nilai yang tidak ada ditulis null, tidak dihilangkan.

Bentuk jawaban. Daftar dijawab {"data": [...], "nextCursor": ...}. Satu catatan dijawab {"data": {...}}.

Halaman berikutnya. Selama nextCursor tidak null, kirim lagi dengan cursor=<nilai itu>. Halaman bisa lebih pendek dari limit, bahkan kosong (misalnya /v1/stock dengan filter status), tapi itu belum berarti habis. Daftar baru selesai ketika nextCursor bernilai null.

Endpoint#

GET /v1/toko#

Cocok untuk menguji kunci. Tidak butuh akses tertentu.

curl -H "X-Api-Key: $LENSIRO_KEY" https://api.pos.lensiro.com/v1/toko

{
  "data": {
    "toko": { "id": "0192c3a0-1b2c-7d3e-8f40-5a6b7c8d9e0f", "name": "Optik Contoh" },
    "key": {
      "id": "0192f2b1-4d5e-7f60-8a71-b2c3d4e5f607",
      "name": "Laporan akuntan",
      "hint": "lpos_Ab3x…9QzK",
      "scopes": ["sales", "items"]
    },
    "plan": "TIM",
    "historyFloor": null,
    "limits": { "keyPerMinute": 60, "keyPerDay": 2000, "tokoPerMinute": 120, "tokoPerDay": 5000 }
  }
}

scopes memakai kode akses: sales (Penjualan), items (Barang & stok), customers (Pelanggan), dan cost (Harga modal). historyFloor berisi tanggal tertua yang bisa dibaca di paket Gratis (juga saat toko tanpa langganan aktif), dan null kalau seluruh riwayat terbuka. Lihat Paket dan riwayat.

GET /v1/sales#

Daftar nota, terbaru dulu.

curl -H "X-Api-Key: $LENSIRO_KEY" \
  "https://api.pos.lensiro.com/v1/sales?from=2026-10-01&to=2026-10-14&limit=50"

{
  "data": [
    {
      "id": "0192f1a8-3c4e-7d21-8b6a-5e9f0c1d2a3b",
      "nota": "SR-1-00042",
      "status": "PESANAN",
      "customerId": "0192e0b7-2a3d-7c10-9e5f-4b6a7c8d9e01",
      "customerName": "Budi Santoso",
      "customerPhone": "081234567890",
      "cashierId": "0192a1b2-c3d4-7e5f-8a6b-7c8d9e0f1a2b",
      "cashierName": "Rina",
      "agentCustomerId": null,
      "agentName": null,
      "subtotal": 1450000,
      "discount": 50000,
      "ppnRate": 11,
      "ppnMode": "INKLUSIF",
      "ppn": 138739,
      "dpp": 1261261,
      "total": 1400000,
      "returned": 0,
      "netTotal": 1400000,
      "paid": 500000,
      "outstanding": 900000,
      "lineCount": 2,
      "itemCount": 2,
      "orderDate": "2026-10-12",
      "promiseDate": "2026-10-19",
      "pickedUpDate": null,
      "memo": null,
      "canceledAt": null,
      "canceledReason": null,
      "occurredAt": "2026-10-12T03:15:42Z",
      "updatedAt": "2026-10-12T03:15:44Z"
    }
  ],
  "nextCursor": "eyJlIjoic2FsZXMiLCJrIjpbIjIwMjYtMTAtMTJUMDM6MTU6NDIuMTgzWiIsIjAxOTJmMWE4LTNjNGUtN2QyMS04YjZhLTVlOWYwYzFkMmEzYiJdfQ",
  "window": { "from": "2026-10-01", "to": "2026-10-14" }
}

Cara membaca angkanya:

• total adalah total nota yang tertulis di struk, sudah termasuk PPN. ppn dan dpp memecahnya. ppnMode bernilai INKLUSIF atau EKSKLUSIF.
• returned adalah nilai barang yang diretur, dan netTotal = total − returned.
• paid adalah jumlah yang sudah dibayar, dan outstanding adalah sisa piutangnya.
• agentCustomerId dan agentName diisi kalau nota memakai referral.
• window menyebut rentang tanggal yang benar-benar dibaca. Di paket Gratis, from bisa dinaikkan ke batas 90 hari.

Rentang lebih dari 92 hari dijawab 400 dengan "param": "from". Bagi menjadi beberapa rentang, misalnya per bulan.

GET /v1/sales/{id atau nota}#

Satu nota lengkap. Isi {id atau nota} dengan id nota atau nomor notanya (huruf besar dan kecil tidak dibedakan).

curl -H "X-Api-Key: $LENSIRO_KEY" https://api.pos.lensiro.com/v1/sales/SR-1-00042

Jawabannya berisi semua kolom di atas, ditambah lines, payments, dan returns:

{
  "data": {
    "id": "0192f1a8-3c4e-7d21-8b6a-5e9f0c1d2a3b",
    "nota": "SR-1-00042",
    "status": "PESANAN",
    "total": 1400000,
    "paid": 500000,
    "outstanding": 900000,
    "lines": [
      {
        "id": "0192f1a8-3c50-7a11-9b2c-3d4e5f607182",
        "itemId": "0192d4c1-77a2-7b10-9f3e-2a4b6c8d0e1f",
        "code": "FR-TTN-52",
        "name": "Frame Titan 52-18 Hitam",
        "unitName": "pcs",
        "packSize": 1,
        "qty": 1,
        "price": 850000,
        "discount": 0,
        "options": [],
        "lineTotal": 850000,
        "memo": null
      },
      {
        "id": "0192f1a8-3c51-7b22-8c3d-4e5f60718293",
        "itemId": "0192d4c9-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
        "code": null,
        "name": "Lensa RX Progresif",
        "unitName": "pasang",
        "packSize": 1,
        "qty": 1,
        "price": 450000,
        "discount": 0,
        "options": [{ "group": "Indeks", "name": "1.67", "priceDelta": 150000 }],
        "lineTotal": 600000,
        "memo": null
      }
    ],
    "payments": [
      {
        "id": "0192f1a8-3c60-7c33-9d4e-5f6071829304",
        "kind": "PAYMENT",
        "method": "TRANSFER",
        "accountId": "0192b0c1-d2e3-7f40-8a51-b6c7d8e9f001",
        "amount": 500000,
        "date": "2026-10-12",
        "note": null,
        "userName": "Rina",
        "returnId": null,
        "occurredAt": "2026-10-12T03:15:42Z"
      }
    ],
    "returns": []
  }
}

Contoh di atas dipendekkan: jawaban asli memuat semua kolom nota seperti di /v1/sales.

• lineTotal = jumlah × (price + semua priceDelta pilihannya) − discount.
• kind bernilai PAYMENT atau REFUND. method salah satu dari CASH, TRANSFER, QRIS, EDC, atau LAINNYA.
• Setiap retur memuat lines dengan saleLineId, qty, condition (LAYAK atau RUSAK), dan amount.
• Resep tidak pernah ikut. Data mata pelanggan tidak keluar lewat API.
• Nota yang dicari dengan id atau nomornya selalu terbaca, walaupun lebih tua dari batas 90 hari.

GET /v1/items#

Katalog barang, urut nama.

curl -H "X-Api-Key: $LENSIRO_KEY" \
  "https://api.pos.lensiro.com/v1/items?category=FRAME&limit=100"

{
  "data": [
    {
      "id": "0192d4c1-77a2-7b10-9f3e-2a4b6c8d0e1f",
      "code": "FR-TTN-52",
      "name": "Frame Titan 52-18 Hitam",
      "category": "FRAME",
      "categoryLabel": "Frame",
      "brand": "Titan",
      "units": [{ "name": "pcs", "packSize": 1, "sellPrice": 850000, "barcode": "8991234567895" }],
      "costPrice": null,
      "reorderPoint": 2,
      "stock": 5,
      "stockStatus": "TERSEDIA"
    }
  ],
  "nextCursor": null
}

• category adalah kode tetap; categoryLabel adalah nama yang tampil di aplikasi (LENSA_KONTAK tampil sebagai Softlens).
• stock dan stockStatus bernilai null untuk JASA dan LENSA_RX, karena barang itu tidak punya stok di rak.
• costPrice hanya terisi untuk kunci dengan akses Harga modal. Lihat Kunci bekerja atas nama pembuatnya.

GET /v1/stock#

Stok setiap barang yang punya stok di rak (semua kategori kecuali Jasa dan Lensa RX), urut nama.

curl -H "X-Api-Key: $LENSIRO_KEY" \
  "https://api.pos.lensiro.com/v1/stock?status=MENIPIS"

{
  "data": [
    {
      "itemId": "0192d5e2-3f40-7a51-8b62-c7d8e9f0a1b2",
      "code": "LS-BB-0050",
      "name": "Lensa Blue Block 1.56 -0.50",
      "category": "LENSA_STOK",
      "categoryLabel": "Lensa Stok",
      "stock": 3,
      "reserved": 1,
      "status": "MENIPIS",
      "reorderPoint": 4,
      "costPrice": 95000,
      "inventoryValue": 285000,
      "lastMovementAt": "2026-10-13T08:02:11Z"
    }
  ],
  "nextCursor": null
}

• stock adalah stok di rak. reserved adalah jumlah yang sudah dipesan pelanggan tetapi belum diserahkan; angka ini tidak dikurangkan dari stock.
• costPrice dan inventoryValue (nilai stok) hanya terisi untuk kunci dengan akses Harga modal. costPrice juga null kalau barang itu tidak punya lapisan stok yang masih terbuka. Lihat Cara stok dihitung.

GET /v1/customers#

Buku pelanggan, urut nama.

curl -H "X-Api-Key: $LENSIRO_KEY" \
  "https://api.pos.lensiro.com/v1/customers?q=budi"

{
  "data": [
    {
      "id": "0192e0b7-2a3d-7c10-9e5f-4b6a7c8d9e01",
      "name": "Budi Santoso",
      "phone": "081234567890",
      "email": null,
      "address": "Jl. Melati 12, Solo",
      "memo": null,
      "active": true,
      "customerSince": "2025-03-08",
      "orderCount": 4,
      "totalSpend": 3250000,
      "firstVisit": "2025-03-08",
      "lastVisit": "2026-10-12",
      "outstanding": 900000
    }
  ],
  "nextCursor": null
}

Paginasi#

• limit menentukan jumlah baris per halaman: bawaannya 50, paling sedikit 1, paling banyak 100.
• Kalau masih ada halaman berikutnya, jawaban membawa nextCursor. Panggil lagi dengan parameter yang sama persis, ditambah cursor=<nextCursor>.
• nextCursor bernilai null di halaman terakhir.
• Kirim cursor apa adanya, tanpa dibaca atau diubah isinya. Cursor dari daftar lain, atau yang rusak, dijawab 400 bad_cursor. Mulai lagi dari halaman pertama.

# Ambil semua penjualan 1–14 Oktober, halaman demi halaman (butuh jq)
URL="https://api.pos.lensiro.com/v1/sales?from=2026-10-01&to=2026-10-14&limit=100"
CURSOR=""
while : ; do
  PAGE=$(curl -s -H "X-Api-Key: $LENSIRO_KEY" "$URL${CURSOR:+&cursor=$CURSOR}")
  echo "$PAGE" | jq -c '.data[]'
  CURSOR=$(echo "$PAGE" | jq -r '.nextCursor // empty')
  [ -z "$CURSOR" ] && break
  sleep 1
done

Tidak ada daftar "yang berubah sejak". Retur dan pembayaran bisa mengubah nota lama, jadi untuk menjaga salinan tetap benar, baca ulang rentang tanggal yang masih mungkin berubah, misalnya 30 hari terakhir, bukan hanya nota baru.

Galat#

Setiap galat dijawab dengan kode HTTP dan isi JSON seperti ini:

{ "error": "kunci ini tidak dibuat untuk membaca Pelanggan", "code": "scope_missing", "scope": "customers" }

error adalah kalimat untuk manusia dalam bahasa Indonesia dan bisa berubah. Program sebaiknya membaca code, yang tetap.

Batas panggilan (rate limit)#

Supaya layanan tetap cepat untuk semua toko, jumlah panggilan dibatasi. Batasnya sama di semua paket.

• Menit dihitung per menit jam (detik 00 sampai 59), bukan 60 detik bergulir.
• Hari dimulai pukul 00.00 WIB.
• Setiap panggilan dengan kunci yang dikenali dihitung, termasuk yang dijawab 400, 403, atau 404. Panggilan dengan kunci salah (401) tidak dihitung.
• Panggilan yang ditolak 429 tidak memakan kuota harian.
• Kalau seluruh layanan API sedang ramai, toko yang memanggil paling banyak 30 kali per menit tetap dilayani. Yang ditolak hanya toko yang memanggil lebih dari itu.

Header batas#

Setiap jawaban /v1 dengan kunci yang dikenali membawa header ini:

Dua header -Day tidak dikirim kalau panggilan ditolak karena batas menit atau karena layanan sedang ramai.

Saat dijawab 429#

Jawaban 429 menambah dua header, Retry-After (berapa detik harus menunggu, paling sedikit 1) dan X-RateLimit-Scope (batas mana yang tercapai: key-minute, toko-minute, key-day, toko-day, atau global):

HTTP/2 429
retry-after: 18
x-ratelimit-limit: 60
x-ratelimit-remaining: 0
x-ratelimit-reset: 1791947760
x-ratelimit-scope: key-minute
content-type: application/json

{"error":"Terlalu banyak panggilan API — coba lagi dalam 18 detik","code":"rate_limited","scope":"key","window":"minute","limit":60,"retryAfter":18}

Isi JSON-nya menyebut scope (key, toko, atau global), window (minute atau day), limit, dan retryAfter dalam detik.

Cara mundur yang benar#

1. Tunggu sesuai Retry-After, lalu coba lagi. Jangan langsung mengulang: panggilan yang ditolak tetap dihitung di menit itu.
2. Kalau window bernilai day, kuota hari ini habis. Berhenti sampai lewat 00.00 WIB.
3. Kalau scope bernilai global atau jawaban 500, tunggu dengan jeda yang makin panjang, misalnya 2, 4, lalu 8 detik ditambah sedikit acak, dan berhenti setelah beberapa kali gagal.
4. Pantau X-RateLimit-Remaining. Kalau mendekati 0, perlambat sebelum ditolak.
5. Ingat bahwa batas toko dibagi oleh semua kunci toko. Dua program yang sama-sama sibuk bisa saling menghabiskan kuota.

Ambil data paling sering 5 menit sekali, dan jangan sepanjang hari. Untuk laporan, sekali sehari atau sekali per jam sudah cukup. Simpan hasilnya di sisi Anda, dan baca ulang hanya rentang tanggal yang masih bisa berubah.

Paket dan riwayat#

API tersedia di semua paket, termasuk Gratis. Di paket Gratis, juga saat toko tanpa langganan aktif, /v1/sales hanya membaca 90 hari terakhir, sama seperti aplikasi: from yang lebih tua dinaikkan otomatis, dan window.from serta historyFloor di /v1/toko menyebut batasnya. Rentang lebih tua tidak ditolak, hanya dipotong. Satu nota yang dicari dengan id atau nomornya selalu terbaca. Lihat Harga & langganan.

Keamanan#

• Perlakukan kunci seperti kata sandi. Simpan di pengaturan rahasia program Anda, jangan di kode yang dibagikan, di spreadsheet yang dibuka banyak orang, atau di halaman web.
• Beri setiap program kuncinya sendiri, dengan akses seperlunya. Kunci yang bocor cukup dicabut tanpa mengganggu program lain.
• Lensiro POS hanya menyimpan sidik jari kunci, bukan kuncinya.
• Cabut kunci yang tidak dipakai lagi. Kunci yang dicabut dihapus permanen setelah 90 hari.

Yang belum ada#

• Menulis lewat API: membuat nota, mengubah stok, atau menambah pelanggan.
• Kas, pembelian, resep, pesanan lab, dan ringkasan laporan.
• Daftar "yang berubah sejak" dan webhook.
• Kedaluwarsa otomatis dan mengganti nama kunci.

Kalau toko Anda butuh salah satunya, ceritakan kepada kami apa yang ingin dikerjakan dengan API.