Qris-Soundbox/06-mqtt-contract-draft.md

MQTT Contract Draft - QRIS Soundbox Platform v1

1. Prinsip MQTT

• topic harus namespaced per device atau tenant
• device hanya boleh publish/subscribe ke topic yang diizinkan
• semua pesan request harus punya request_id
• semua pesan response harus punya correlation_id
• notifikasi harus punya event_id untuk dedup

2. Topic Convention

Uplink dari device

• devices/{deviceId}/uplink/heartbeat
• devices/{deviceId}/uplink/dynamic-qr/request
• devices/{deviceId}/uplink/config/ack
• devices/{deviceId}/uplink/command/ack

Downlink ke device

• devices/{deviceId}/downlink/dynamic-qr/response
• devices/{deviceId}/downlink/payment/success
• devices/{deviceId}/downlink/config/push
• devices/{deviceId}/downlink/command

3. Heartbeat Payload

{
  "message_type": "heartbeat",
  "device_id": "sbx_001",
  "timestamp": "2026-05-23T10:00:00Z",
  "firmware_version": "1.0.3",
  "state": "idle",
  "network_strength": 78,
  "battery_level": 92
}

4. Dynamic QR Request Payload

{
  "message_type": "dynamic_qr_request",
  "request_id": "req_123",
  "device_id": "sbx_001",
  "terminal_id": "term_001",
  "amount": 50000,
  "currency": "IDR",
  "created_at": "2026-05-23T10:00:00Z"
}

5. Dynamic QR Response Payload

{
  "message_type": "dynamic_qr_response",
  "correlation_id": "req_123",
  "transaction_id": "tx_123",
  "status": "success",
  "qr_payload": "000201010212...",
  "expires_at": "2026-05-23T10:05:00Z"
}

6. Payment Success Notification Payload

{
  "message_type": "payment_success",
  "event_id": "evt_123",
  "transaction_id": "tx_123",
  "merchant_name": "Toko Berkah",
  "amount": 50000,
  "currency": "IDR",
  "paid_at": "2026-05-23T10:02:10Z",
  "audio_text": "Pembayaran diterima lima puluh ribu rupiah",
  "display_text": "Pembayaran diterima Rp50.000"
}

7. Config Push Payload

{
  "message_type": "config_push",
  "config_version": 3,
  "settings": {
    "volume": 80,
    "language": "id-ID",
    "heartbeat_interval_seconds": 60
  }
}

8. Command Payload

{
  "message_type": "command",
  "command_id": "cmd_123",
  "command_name": "test_speaker",
  "parameters": {}
}

9. QoS dan Delivery

• heartbeat dapat memakai QoS rendah sesuai kebutuhan
• payment success sebaiknya QoS lebih tinggi
• retained message jangan dipakai untuk notifikasi sukses transaksi
• ack command dan ack config harus dicatat