# 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
```json
{
  "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
```json
{
  "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
```json
{
  "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
```json
{
  "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
```json
{
  "message_type": "config_push",
  "config_version": 3,
  "settings": {
    "volume": 80,
    "language": "id-ID",
    "heartbeat_interval_seconds": 60
  }
}
```

## 8. Command Payload
```json
{
  "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