Confirm the machine interface
Send the controller label, wiring photos, and the action the machine must perform.
Transport choice
HTTPS or MQTT?
Both can exist in one project. The choice depends on whether you need a response now or a stream of events.
| Use case | HTTPS API | MQTT |
|---|---|---|
| Backend sends a command | Request / response | Publish to command topic |
| Backend receives events | Webhook or polling | Subscribe to event topic |
| Best fit | Server-triggered actions | Real-time status and telemetry |
| Failure handling | HTTP status + retry | QoS + reconnect + idempotency |
The exact transport available on a machine depends on the controller, firmware, and network path.
项目适配
适用于接入自有后端的团队
买家信号
- Your backend or app needs to trigger a vend, relay, pulse, unlock, or timed session.
- Your platform uses HTTPS, webhooks, or MQTT and wants the machine-side contract in one place.
- You need event identity, retries, and offline behavior defined before a sample.
- You want to keep your own payment provider, schema, and dashboard.
首先需要提供
- 机器照片或现有主板照片
- 接口或接线说明
- 支付/API 后要触发的动作
- 是否需要数据上传
不适合的情况
- You need payment acquiring, settlement, or wallet balance.
- The machine has no controllable interface or usable event source.
- You need a fixed API contract before the controller and firmware are confirmed.
集成方式
一套接口，两种传输
HTTPS 用于命令和请求/响应，MQTT 用于实时事件。设备身份、主题前缀、认证和 QoS 按项目确认。
- API transport
- HTTPS REST; JSON request and response
- MQTT transport
- MQTT 3.1.1 over TLS 1.2; QoS 1; keepalive 60s
- Device identity
- Project-issued device_id
- Command reference
- reference_id is used for idempotency
- Event identity
- event_id, occurred_at, device_id, result
- Authentication
- HTTPS Bearer token; optional HMAC-SHA256
- Error model
- unauthorized, device_offline, timeout, invalid_command, machine_fault
控制流程
从机器接口到 API 控制的执行结果。
Define the command contract
Confirm command names, slot or channel mapping, timeout, and result fields.
Connect the transport
Issue device identity, token, topic prefix, TLS mode, and QoS for the project.
Test one machine
Validate command, machine action, event identity, retry, and reconnect on a sample.
API 示例
服务器命令或 webhook 示例。
命令字段取决于机器接口、固件配置，以及由支付还是你的应用触发。
POST /v1/devices/{device_id}/commands
Authorization: Bearer
Content-Type: application/json
{
"command": "vend",
"slot": "B04",
"reference_id": "ORDER-1001",
"timeout_ms": 15000
}
# MQTT topic map
devices/{device_id}/commands
devices/{device_id}/events
项目询盘
先发机器照片，我们帮你判断主板、接口和样品测试步骤。
发送机器型号、控制器接口、目标动作和数据字段，我们确认 API/MQTT 方案和样品测试。
一条有效的第一条消息
如果不确定机器接口，先发你手上的资料即可。照片往往比长文档更快判断方向。
- 机器类型和目标国家
- 机器照片、主板照片或线束照片
- 支付或 API 后要触发的动作
- 是否需要数据上传、预计数量
最快的第一步
- 发送机器照片
- 说明 API 或支付后要触发什么动作
- 告诉我们是否需要数据上传
常见问题
打样前通常会问的问题。
Do you support MQTT?
MQTT 3.1.1 over TLS 1.2 with QoS 1 is the baseline. Broker, topic prefix, and authentication are confirmed per firmware profile.
Can we use our own backend?
Yes. The controller can deliver commands and events to your own API, webhook, or broker. The exact flow is confirmed on a sample.
How do you prevent duplicate commands?
The contract uses reference_id and event_id. Retry and deduplication behavior is confirmed in the firmware profile and tested on one machine.
What happens when the network is offline?
Event buffering and retry are part of the integration plan. Capacity, power-cycle retention, and backfill behavior must be tested before making a persistent-cache claim.
相关页面