QFM API Guide

QuickFreeze QFM API

Read live status and control your QFM units from your WMS or building-automation system — set cycle times, record what is on the pallet, pause and resume fans.

Your software addresses each unit by its QFM serial number (printed on the unit) plus the rack location you have on file for it. Everything runs through one secured endpoint, scoped to your facility’s own units. The serial is permanent — when a control box is replaced, the API resolves the serial to whichever box is installed at that moment, so a swap needs no change on your side.

Connection

Endpoint
https://qfreeze.com/wp-json/qf/v1/qfm
the same address for every customer — your key scopes it to your units
Auth header
X-QF-API-Key: {your-api-key} — issued per facility; TLS 1.2+ required
Methods
HTTP GET (query parameters) or POST (JSON body)
Responses
Reads return 200 with the unit’s live state; commands return 202 accepted. Every failure is JSON with a stable error code — a missing or wrong key returns 401.
User-Agent
Please send an identifying agent, e.g. YourCompany-WMS/1.0. Our edge blocks a few known automated-client signatures; if you ever receive an HTML 403 instead of JSON, tell us and we will allow your client.

1. Identifying a unit

Every request carries two identifiers, and both must match our records:

ParameterExampleNotes
QFM_SERIALQFM-12107Printed on the unit. Permanent — survives control-box swaps.
RACK_LOCATION2X-001BThe rack position we have recorded for that QFM.
WAREHOUSE_IDDC-EASTOptional. Your own site or warehouse code, echoed back unchanged — a label for multi-site systems, not a permission.

If the serial exists but the rack does not match, the request is refused and the reply tells you which rack we have on file (409 rack_mismatch). A stale or mis-keyed mapping in the WMS can never make us act on the wrong unit. A serial belonging to another customer returns 403, even with a correct rack.

2. Poll a unit (read latest)

COMMAND=poll is the default and may be omitted. Polling is read-only and cannot affect equipment.

curl -H "X-QF-API-Key: {your-api-key}" -H "User-Agent: YourCompany-WMS/1.0" \
  "https://qfreeze.com/wp-json/qf/v1/qfm?QFM_SERIAL=QFM-12107&RACK_LOCATION=2X-001B&COMMAND=poll"

→ 200 {"ok":true,"QFM_SERIAL":"QFM-12107","RACK_LOCATION":"2X-001B",
       "controlBox":"F8B3B74E6E7C","ts":1786143610000,"state":"READY",
       "airtF":3.4,"airtC":-15.89,"deltap":0.01,
       "remaining":172800,"active":true,"SKU":"I1-123456"}
FieldMeaning
oktrue on success. Always present.
RACK_LOCATIONThe rack we have on file for the unit.
controlBoxThe control box installed right now. Opaque to you — quote it when reporting an issue.
tsTime of the reading, epoch milliseconds UTC. Always check it: an offline unit returns its last known values with an older timestamp.
stateCurrent unit state, e.g. READY, RUNNING, COMPLETE, PAUSE, BAD SEAL.
airtF / airtCAir temperature in both scales. Units measure in Celsius — read airtF if you work in Fahrenheit; do not assume an unlabelled value is °F.
deltapDifferential pressure across the unit (seal quality).
remainingSeconds remaining in the current cycle; 0 when not running.
activeWhether the unit is currently running.
SKUItem code stamped on the cycle in progress (always a string). Empty when no cycle is running — the unit clears it at cycle end.

3. Commands

Three commands are available: set_cycle, pause and resume. Commands are asynchronous: we validate and authorise the request, return 202, then apply it to the unit a moment later. Anything we cannot act on is rejected up front with a 4xx and an error code — we never return 202 for a command that would quietly do nothing. To confirm a change reached the unit, poll it afterwards.

Set cycle time and cycle details — set_cycle

ParameterNotes
INCUBATIONRun time in hours, whole or fractional (48, 12.5). Persists until changed; if the unit is offline it takes effect at its next check-in.
ITEM_NUMBER (or SKU)Your item code. Stamped on the unit for this cycle, and can supply the run time from your SKU library (below).
PALLET_TAG, POPallet / LP / LPN and purchase order, recorded against the cycle for reporting.

Send any combination — at least one. Only PO? Fine. Pallet details on a cycle that is already running, without touching its run time? Fine. If you send any of these fields without a COMMAND, we treat it as set_cycle.

curl -H "X-QF-API-Key: {your-api-key}" -H "User-Agent: YourCompany-WMS/1.0" \
  "https://qfreeze.com/wp-json/qf/v1/qfm?QFM_SERIAL=QFM-12107&RACK_LOCATION=2X-001B\
&COMMAND=set_cycle&INCUBATION=48&ITEM_NUMBER=I1-123456&PALLET_TAG=LP-4471&PO=PO12345"

→ 202 {"ok":true,"accepted":true,"QFM_SERIAL":"QFM-12107","RACK_LOCATION":"2X-001B",
       "controlBox":"F8B3B74E6E7C","COMMAND":"set_cycle",
       "applied":{"cycleTimeHours":48,"SKU":"I1-123456","PALLET_TAG":"LP-4471","PO":"PO12345"},
       "cycleTimeChanged":true}

applied lists exactly what we acted on and cycleTimeChanged says whether the run time moved — you never have to assume. An INCUBATION we cannot use rejects the whole call; we will not quietly apply just the metadata.

Cycle time from the SKU

Let the item code decide the run time instead of sending INCUBATION every call: &COMMAND=set_cycle&ITEM_NUMBER=I1-123456. The library builds itself from your calls: the first call that carries an item code with an explicit INCUBATION teaches us that item’s run time, and later calls can send the code alone. A new item without hours is registered but the run time is left unchanged — the reply says so with cycleTimeChanged:false and a warning. An explicit INCUBATION always wins.

The reply reports what the library learned. Three calls for the same item, in order:

# 1. First time we see I1-123456, with hours: the library records 36 h against it
&COMMAND=set_cycle&INCUBATION=36&ITEM_NUMBER=I1-123456&PALLET_TAG=LP-4471

→ 202 {"ok":true,"accepted":true,"QFM_SERIAL":"QFM-12107","RACK_LOCATION":"2X-001B",
       "controlBox":"F8B3B74E6E7C","COMMAND":"set_cycle",
       "applied":{"cycleTimeHours":36,"SKU":"I1-123456","PALLET_TAG":"LP-4471"},
       "cycleTimeChanged":true,"skuRegistered":true,"skuHoursRecorded":36}

# 2. Same item, different hours: the stored run time is replaced and the reply says from what
&COMMAND=set_cycle&INCUBATION=48&ITEM_NUMBER=I1-123456&PALLET_TAG=LP-4472

→ 202 {"ok":true,"accepted":true,"QFM_SERIAL":"QFM-12107","RACK_LOCATION":"2X-001B",
       "controlBox":"F8B3B74E6E7C","COMMAND":"set_cycle",
       "applied":{"cycleTimeHours":48,"SKU":"I1-123456","PALLET_TAG":"LP-4472"},
       "cycleTimeChanged":true,"skuHoursRecorded":48,"skuHoursChanged":{"from":36,"to":48}}

# 3. Item code alone: the 48 h on file is applied
&COMMAND=set_cycle&ITEM_NUMBER=I1-123456&PALLET_TAG=LP-4473

→ 202 {"ok":true,"accepted":true,"QFM_SERIAL":"QFM-12107","RACK_LOCATION":"2X-001B",
       "controlBox":"F8B3B74E6E7C","COMMAND":"set_cycle",
       "applied":{"cycleTimeHours":48,"SKU":"I1-123456","PALLET_TAG":"LP-4473"},
       "cycleTimeChanged":true}

skuHoursChanged is an object with two decimal-hours members: from, the run time that was on file, and to, the run time that replaced it (always equal to applied.cycleTimeHours). It appears only on a call that sent INCUBATION together with an item code that already had a different run time on file. Re-sending the same hours changes nothing, so neither skuHoursRecorded nor skuHoursChanged appears. Whole hours are sent as plain integers (36, not 36.0); fractional hours keep their decimals (12.5). Size both members as DECIMAL(5,2).

Pause / resume fans

pause stops the fans and freezes the cycle timer in place; resume continues from exactly where it stopped. DURATION (minutes, optional) is a dead-man auto-resume: if your system never sends resume, the unit restores itself. We recommend sending it on every pause.

curl -H "X-QF-API-Key: {your-api-key}" \
  "https://qfreeze.com/wp-json/qf/v1/qfm?QFM_SERIAL=QFM-12107&RACK_LOCATION=2X-001B&COMMAND=pause&DURATION=30"

curl -H "X-QF-API-Key: {your-api-key}" \
  "https://qfreeze.com/wp-json/qf/v1/qfm?QFM_SERIAL=QFM-12107&RACK_LOCATION=2X-001B&COMMAND=resume"
Pause only holds on a unit that is actually running a cycle. An idle QFM returns itself to READY a moment after being paused — that is the unit behaving correctly, not a failed command. Check state and active first if it matters to your workflow.

Repeating a command

All three commands are safe to send again — set_cycle sets a value rather than adding to one, and pause/resume set a state. Re-sending after a timeout will not compound.

4. Error responses

Alert on the error code, not the message text — messages may be reworded, codes will not change.

{"ok":false,"error":"rack_mismatch",
 "message":"RACK_LOCATION does not match the rack recorded for QFM-12107. Refusing to act on a possibly wrong unit.",
 "expectedRackLocation":"2X-001B"}
HTTPerrorMeaningWhat to do
400missing_serial / missing_rack_locationA required identifier is absentFix the request
400bad_commandUnrecognised COMMANDFix the request
400nothing_to_setset_cycle with nothing to applySend at least one field
400poll_is_read_onlyCOMMAND=poll sent with fields that would writeOmit COMMAND, or use set_cycle
400bad_cycle_timeINCUBATION not a number between 0.17 and 168 hoursFix the value — nothing was applied
400field_too_longA request field exceeds its limit (section 5); field and maxLength say whichShorten the value
401unauthorizedMissing or wrong API keyCheck the header; alert
403not_authorizedThat unit is not on your accountCheck the serial; alert
404unknown_serialNo QFM with that serialTypo or decommissioned unit; alert
409rack_mismatchSerial is yours, rack does not matchAlert. Your mapping is stale — expectedRackLocation tells you ours
409ambiguous_serialSerial matches more than one unitContact us — a data issue on our side
502upstream_errorWe could not reach the monitoring platformRetry with backoff; alert if sustained

Retries: poll and all commands are safe to retry. Use exponential backoff on 502; do not retry 4xx — they will not succeed without a change to the request.

5. Field sizes and types

Size your database columns from this table. These are commitments: a value we return will never exceed its limit, and a request value longer than its limit is refused with 400 field_too_long rather than truncated. Every response is JSON; strings are UTF-8, numbers are plain JSON numbers (no thousands separators, dot decimal), booleans are true/false.

Request fields

FieldTypeLimit
QFM_SERIALstring32 characters
RACK_LOCATIONstring32 characters
COMMANDstringone of poll, set_cycle, pause, resume (9 characters max)
ITEM_NUMBER / SKUstring64 characters
PALLET_TAG, POstring64 characters each
WAREHOUSE_IDstring64 characters
INCUBATIONdecimal hours0.17 to 168 (10 minutes to 7 days)
DURATIONinteger minutes—

Poll response (200)

FieldTypeSize / rangeNotes
okboolean—Always present. true on every successful response.
QFM_SERIALstring≤ 32Echo of yours.
RACK_LOCATIONstring≤ 32The rack on file with us.
controlBoxstring≤ 32Today a 12-character hex identifier.
tsinteger13 digitsEpoch milliseconds UTC — use a 64-bit integer.
WAREHOUSE_IDstring≤ 64Only when you sent it.
statestring≤ 14One of BOOT UP, READY, SEAL TEST, BAD SEAL, RUNNING, PAUSE, COMPLETE, MOTOR FAILURE, SENSOR FAILURE, BLOW OUT.
deltapdecimal2 decimal places, signedPascals. Normally 0 to about 300; may dip slightly negative. DECIMAL(8,2) covers anything the sensor can report.
remaininginteger0 to 604 800Whole seconds, never fractional (7 days max).
airtCdecimal2 decimal places, −55.00 to 125.00DECIMAL(5,2).
airtFdecimal1 decimal place, −67.0 to 257.0DECIMAL(4,1).
activeboolean—
SKUstring≤ 64Whatever you sent as ITEM_NUMBER; empty when no cycle is running.
Treat every reading as optional. airtC/airtF, deltap, state and SKU are omitted when the unit has never reported that value or the sensor behind it is in fault — parse by key, not by position, and allow nulls in your table.

Command response (202)

FieldTypeSize / rangeNotes
okboolean—The request succeeded. Check this first on every response.
acceptedboolean—The command was authorised and handed to the unit. Present on command responses only. Commands are asynchronous, so accepted means queued, not applied — poll to confirm. You will not see ok:true with accepted:false.
QFM_SERIAL, RACK_LOCATION, controlBox, WAREHOUSE_IDstringas above
COMMANDstring≤ 9The command that was applied.
applied.cycleTimeHoursdecimal0.17 to 168Only when the run time was set.
applied.SKU, applied.PALLET_TAG, applied.POstring≤ 64 eachEcho of what you sent; each present only if sent.
cycleTimeChanged, skuRegisteredboolean—skuRegistered only when a new item was registered.
skuHoursRecordeddecimal0.17 to 168Only when the item library learned a run time.
skuHoursChangedobjectfrom, to decimal hoursOnly when a stored run time was replaced.
warningstring≤ 255Only when present. Informational; the command was still accepted.

Error response (4xx / 5xx)

FieldTypeSizeNotes
okboolean—Always false.
errorstring≤ 32Stable lower-case code (section 4). Alert on this.
messagestring≤ 255Human-readable; may be reworded.
expectedRackLocationstring≤ 32With rack_mismatch only.
field, maxLengthstring, integer≤ 16, —With field_too_long only.
ignoredFieldsarray of strings≤ 5 namesWith poll_is_read_only only.
upstreamStatusinteger3 digitsWith some upstream_error responses.

Identity & safety

  • Each facility authenticates with its own API key and is authorised to its own units only.
  • RACK_LOCATION must match the location mapped to that QFM_SERIAL or the request is refused — this prevents adjusting the wrong unit.
  • Units are addressed by QFM serial, which stays stable across control-box swaps; controlBox in every response shows which box answered.
  • Keep your API key out of email threads and shared files. QuickFreeze may rate-limit excessive request volumes.

Getting started

QuickFreeze issues your API key and the QFM_SERIAL ↔ RACK_LOCATION map for your units. A good first call is a poll against one live unit, then a deliberately wrong rack location to see 409 rack_mismatch come back. Send us your SKU list with cycle times if you want ITEM_NUMBER alone to set run times from day one.

To request access, contact your QuickFreeze representative.