Confirm the machine interface
Send the controller label, wiring photos, and the action the machine must perform.
Guides
MQTT & API integration
MQTT and API integration for machine-side control.
Use this guide to plan the path between your backend, a QuLink controller, and a vending or self-service machine. The examples show the integration shape; endpoint names, topic prefixes, authentication, and payload fields are confirmed per firmware profile.
HTTPS APIMQTT topicsIdempotent commandsEvent callbacks
Part of Machine Data Upload IoT Board for Self-Service Equipment
Project fit
For teams connecting a machine to their own backend
Buyer signals
- 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.
What to send first
- Machine photo or existing board photo
- Interface or wiring note if available
- Target action after API command or payment
- Whether telemetry or data upload is required
Not the right fit if
- 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.
Integration model
One contract, two transports
Use HTTPS for request/response commands and MQTT for real-time events or command delivery. The device identity, topic prefix, authentication, QoS, and TLS mode are issued per project.
- 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
Workflow
From machine interface to API-controlled result.
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 example
A clear server command or webhook for the machine-side action.
The exact command fields depend on machine interface, firmware profile, and whether payment or your own app triggers the action.
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
Project RFQ
Send a machine photo. We help identify the board, interface, and next test step.
Send the machine model, controller interface, target action, and data fields you need. We will confirm the API/MQTT contract and the next sample test.
A good first message
If you are unsure about the exact interface, send what you have. Photos often answer more than a long spec.
- Machine type and target country
- Machine photo, board photo, or wiring photo
- Action after payment or API command
- Need data upload? expected quantity?
Fastest first step
- Send a machine photo
- Describe the action after API or payment
- Tell us if data upload is needed
FAQ
Questions buyers usually ask before a sample test.
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.
Related use cases