Mulai Cepat API Smart Retail Counter

Panduan mulai cepat ini membaca angka sebuah toko dari perangkat Smart Retail Counter. Anda memerlukan curl dan sekitar sepuluh menit. Angka pada jawaban di bawah adalah nilai contoh. Penghitungan bersifat anonim: API tidak memberikan identitas maupun gambar.

Sebelum Anda Mulai

Mintalah Admin perangkat membuat akun API di dasbor (halaman Akun API) dengan:

• peran Pemantau di lokasi toko;
• cakupan read (tambahkan export untuk mengunduh log sebagai file);
• tanggal berakhir.

Admin memberikan token (<API_KEY> di bawah), alamat perangkat (<BOX_HOST>) dan salinan sertifikat perangkat (box.pem, dari Unduh sertifikat perangkat di halaman Akun API) beserta sidik jari SHA-256-nya: periksa seperti yang ditunjukkan Sertifikat Perangkat. Autentikasi dan Cakupan menjelaskan masing-masing.

Cari Lokasi Anda

curl --cacert box.pem \
  -H "Authorization: Bearer <API_KEY>" \
  "https://<BOX_HOST>/api/v1/sites"

{
  "items": [
    {
      "id": 1,
      "name": "North Plant",
      "timezone": "Asia/Jakarta",
      "created": "2026-10-01T02:00:00Z",
      "version": 4,
      "my_role": "viewer",
      "location": { "lat": -6.2, "lon": 106.8 },
      "area": null,
      "zones": 3
    }
  ]
}

Simpan id lokasi (di sini 1).

Baca Ikhtisar Toko

Mintalah satu periode dengan from dan to (RFC 3339; %2B adalah tanda + dari selisih zona waktu):

curl --cacert box.pem \
  -H "Authorization: Bearer <API_KEY>" \
  "https://<BOX_HOST>/api/retail/v1/sites/1/overview?from=2026-11-01T00:00:00%2B07:00&to=2026-11-02T00:00:00%2B07:00"

{
  "entries": 1284,
  "exits": 1241,
  "passersby": 5310,
  "capture_rate": 19.5,
  "visits": 1190,
  "engaged_rate": 41.3,
  "checkout_rate": 28.7,
  "avg_dwell_min": 11.4,
  "conversion": { "value": 24.1, "source": "pos", "transactions": 309 },
  "in_store_now": 37,
  "queues_now": [
    { "zone": "Checkout", "length": 4, "est_wait_s": 95, "at": "2026-11-02T10:58:00Z", "long_queue_length": 6 }
  ],
  "repeat_share": null,
  "vip_visits": 0,
  "demographics": {
    "cells": [{ "age_band": "25-34", "gender": "female", "visits": 214, "share": 22.3 }],
    "unknown_visits": 231
  },
  "occupancy_limit": 120,
  "long_queue_length": 6,
  "store_hours": { "open": "10:00", "close": "22:00" }
}

Persentase bernilai 0 sampai 100 dan null bila tidak ada pembaginya. Untuk angka yang sama per jam atau hari, panggil GET /api/retail/v1/sites/1/trend; per zona, GET /api/retail/v1/sites/1/zones; antrean per jam, GET /api/retail/v1/sites/1/queues.

Baca Log Pengunjung

curl --cacert box.pem \
  -H "Authorization: Bearer <API_KEY>" \
  "https://<BOX_HOST>/api/retail/v1/sites/1/logs?from=2026-11-01T00:00:00%2B07:00&to=2026-11-02T00:00:00%2B07:00&limit=50"

{
  "items": [
    {
      "id": "31:7712",
      "entered": "2026-11-02T10:31:02Z",
      "exited": "2026-11-02T10:44:40Z",
      "dwell_s": 818,
      "engaged": true,
      "reached_checkout": true,
      "age_band": "25-34",
      "gender": "female",
      "repeat_visitor": null,
      "entry_line": "Main door",
      "cameras": [31, 32],
      "zones": [{ "zone": "Aisle 2", "kind": "display", "dwell_s": 240 }]
    }
  ],
  "next_before": "2026-11-02T10:31:02Z"
}

Setiap baris adalah satu kunjungan anonim. Untuk halaman berikutnya, kirim next_before sebagai before. Unduh periode itu sebagai file dengan GET /api/retail/v1/sites/1/logs/export?format=csv dan cakupan export.

Kirim Transaksi POS

Tingkat konversi memakai jumlah transaksi toko sendiri. Kasir (POS) Anda dapat mengirimnya per interval dengan dua cara:

• ditandatangani oleh POS sendiri: POST /api/retail/v1/pos/{site}, dengan kunci POS lokasi yang dibuat Admin lokasi di dasbor (lihat Menandatangani Permintaan ke Perangkat);
• sebagai unggahan CSV dengan token API yang menjadi Admin lokasi: POST /api/retail/v1/sites/1/pos/upload (start,end,transactions).

Langkah Berikutnya

• Kirim kunjungan, lintasan pintu, sampel antrean dan waktu singgah di lantai ke sistem Anda tanpa perlu menanyakan berulang kali: Webhook (jenis peristiwa retail.visit, retail.crossing, retail.queue, retail.floor dan, dengan personal_data, retail.vip, serta ringkasan berkala).
• Setiap operasi dan kolom: referensi API Smart Retail Counter dan referensi API platform.