API de QuickFreeze QFM
Consulta el estado en tiempo real y controla tus unidades QFM desde tu sistema de gestión de almacén (WMS) o tu sistema de automatización de edificios: configura los tiempos de ciclo, registra el contenido del palé, pon en pausa y reanuda el funcionamiento de los ventiladores.
Tu software se refiere a cada unidad por su Número de serie de QFM (impreso en la unidad) más el ubicación del estante que tengas registrado para ello. Todo pasa por un único punto de conexión seguro, limitado a las unidades de tu propia instalación. El número de serie es permanente: cuando se reemplaza una caja de control, la API asocia el número de serie a la caja que esté instalada en ese momento, por lo que un cambio no requiere ninguna modificación de tu parte.
Conexión
- Punto final
https://qfreeze.com/wp-json/qf/v1/qfm
la misma dirección para todos los clientes — tu clave la limita a tus unidades- Encabezado de autenticación
X-QF-API-Key: {tu-clave-de-API}— emitido por cada instalación; se requiere TLS 1.2 o superior- Métodos
- HTTP OBTENER (parámetros de consulta) o PUBLICAR (Cuerpo JSON)
- Respuestas
- Devuelve el número de lecturas 200 con el estado actual de la unidad; los comandos devuelven 202 aceptado. Cada error es un JSON con una versión estable
errorcódigo: si falta una clave o está incorrecta, se devuelve 401. - Agente de usuario
- Por favor, envíe un agente identificador, por ejemplo:.
TuEmpresa-WMS/1.0. Nuestro sistema bloquea algunas firmas conocidas de clientes automatizados; si alguna vez recibes un código de error HTML 403 en lugar de JSON, avísanos y autorizaremos tu cliente.
1. Identificación de una unidad
Cada solicitud conlleva dos identificadores, y ambos deben coincidir con nuestros registros:
| Parámetro | Ejemplo | Notas |
|---|---|---|
QFM_SERIAL | QFM-12107 | Está impreso en la unidad. Permanente: no se borra al cambiar la caja de control. |
UBICACIÓN_DEL_RACK | 2X-001B | La posición en el rack que hemos registrado para ese QFM. |
WAREHOUSE_ID | DC-EAST | Opcional. Tu propio código de sitio o de almacén, que se devuelve sin cambios: se trata de una etiqueta para sistemas con múltiples sitios, no de un permiso. |
Si el número de serie existe pero el rack no coincide, la solicitud es rechazado y la respuesta
te indica qué rack tenemos registrado (409 discrepancia de rack). Una asignación desactualizada o mal ingresada en el
WMS nunca nos hará actuar sobre la unidad equivocada. Un número de serie que pertenece a otro cliente devuelve
403, incluso con un soporte adecuado.
2. Interrogar una unidad (leer el último valor)
COMANDO=poll Es el valor predeterminado y se puede omitir. La consulta es de solo lectura y no puede afectar al equipo.
curl -H "X-QF-API-Key: {tu-clave-de-API}" -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":172 800,"active":true,"SKU":"I1-123456"}
| Campo | Significado |
|---|---|
ok | verdadero en el éxito. Siempre presente. |
UBICACIÓN_DEL_RACK | El estante nosotros que tenemos en nuestros archivos para esa unidad. |
controlBox | La caja de control ya está instalada. Aunque no la veas, menciónala cuando reportes un problema. |
ts | Hora de la lectura, milisegundos de época UTC. Verifícalo siempre: una unidad fuera de línea devuelve sus últimos valores conocidos con una marca de tiempo anterior. |
estado | Estado actual de la unidad, p. ej.:. LISTO, CORRER, COMPLETO, PAUSA, SELLADO DEFECTUOSO. |
airtF / airtC | Temperatura del aire en ambas escalas. Las unidades se miden en grados Celsius — leer airtF Si trabajas en grados Fahrenheit, no des por sentado que un valor sin etiquetar está en °F. |
deltap | Presión diferencial a través de la unidad (calidad del sellado). |
restante | Segundos que quedan en el ciclo actual; 0 cuando no está en funcionamiento. |
activo | Si la unidad está funcionando en este momento. |
SKU | Código de artículo impreso en el ciclo en curso (siempre una cadena). Vacío cuando no hay ningún ciclo en ejecución; la unidad lo borra al finalizar el ciclo. |
3. Comandos
Hay tres comandos disponibles: set_cycle, pausa y currículum.
Los comandos son asíncrono: validamos y autorizamos la solicitud, devolvemos
202, y luego lo aplicamos a la unidad un momento después. Todo aquello sobre lo que no podamos actuar es
rechazado de inmediato con un 4xx y un error código: nunca devolvemos un código 202 para un
comando que, en silencio, no haría nada. Para confirmar que el cambio llegó a la unidad, compruébalo posteriormente.
Configurar la duración del ciclo y los detalles del ciclo — set_cycle
| Parámetro | Notas |
|---|---|
INCUBACIÓN | Tiempo de ejecución en horas, entero o fraccionario (48, 12.5). Persiste hasta que se modifique; si la unidad está fuera de línea, entra en vigor en su próximo registro. |
NÚMERO DE ARTÍCULO (o SKU) | Tu código de artículo. Está estampado en la unidad correspondiente a este ciclo y te permite consultar el tiempo de funcionamiento en tu biblioteca de SKU (a continuación). |
PALLET_TAG, PO | Palé / LP / LPN y orden de compra, registrados en el ciclo para la generación de informes. |
Envía cualquier combinación —al menos una—. Solo PO? Está bien. ¿Los detalles del palé en un ciclo que
ya está en ejecución, sin alterar su tiempo de ejecución? Está bien. Si envías cualquiera de estos campos sin un
COMANDO, lo consideramos como set_cycle.
curl -H "X-QF-API-Key: {tu-clave-API}" -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}
aplicado enumera exactamente las medidas que tomamos y cycleTimeChanged indica si el
tiempo de ejecución ha cambiado; nunca tienes que darlo por sentado. Un INCUBACIÓN No podemos descartar toda la
llamada; no nos limitaremos a aplicar silenciosamente solo los metadatos.
Tiempo de ciclo a partir de la SKU
Que el código del artículo determine el tiempo de ejecución, en lugar de enviar INCUBACIÓN cada llamada:
&COMMAND=set_cycle&ITEM_NUMBER=I1-123456. La biblioteca se arma a partir de tus llamadas: la
primera llamada que incluye un código de artículo con un explícito INCUBACIÓN nos enseña que
el tiempo de ejecución del elemento, y las llamadas posteriores pueden enviar solo el código. Se registra un nuevo elemento sin horas, pero
el tiempo de ejecución permanece sin cambios; la respuesta lo indica con cycleTimeChanged:false y un
advertencia. Un explícito INCUBACIÓN siempre gana.
La respuesta informa lo que la biblioteca averiguó. Tres solicitudes del mismo artículo, en orden:
# 1. Primera vez que vemos el I1-123456, con horas: la biblioteca registra 36 h para este artículo
&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. Mismo artículo, horas diferentes: se reemplaza el tiempo de funcionamiento almacenado y la respuesta indica de dónde
&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. Solo el código de artículo: se aplica el valor de 48 h registrado
&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 es un objeto con dos miembros de tipo «hora decimal»: de, el tiempo de ejecución
que figuraba en el expediente, y a, el tiempo de ejecución que lo sustituyó (siempre igual a
tiempo de ciclo aplicado en horas). Solo aparece en una llamada que se envió INCUBACIÓN junto con un
código de artículo que ya tenía un diferente tiempo de ejecución según el archivo. Volver a enviar las mismas horas no cambia nada,
así que tampoco skuHorasRegistradas ni skuHoursChanged aparece. Las horas completas se envían como
números enteros sin formato (36, no 36.0); las horas fraccionarias conservan sus decimales (12.5).
Dimensiona ambos elementos como DECIMAL(5,2).
Detener / reanudar los ventiladores
pausa apaga los ventiladores y congela el temporizador del ciclo en su posición actual; currículum
continúa exactamente de donde se había quedado. DURACIÓN (minutos, opcional) es un mecanismo de
reanudación automática por inactividad: si tu sistema nunca envía currículum, la unidad se reinicia automáticamente. Recomendamos enviarla
cada vez que haya una pausa.
curl -H "X-QF-API-Key: {tu-clave-de-API}" \
"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: {tu-clave-de-API}" \
"https://qfreeze.com/wp-json/qf/v1/qfm?QFM_SERIAL=QFM-12107&RACK_LOCATION=2X-001B&COMMAND=resume"
LISTO un momento después de haberlo puesto en pausa — eso significa que la unidad está funcionando correctamente, no que se trate de un
comando fallido. Verifica estado y activo En primer lugar, si es relevante para tu flujo de trabajo.Repetir un comando
Los tres comandos se pueden volver a enviar sin problema — set_cycle establece un valor en lugar de sumar
uno, y pausa/currículum Establecer un estado. El reenvío tras un tiempo de espera no se acumulará.
4. Respuestas de error
Alerta sobre el error código, no el texto del mensaje: los mensajes pueden modificarse, pero los códigos no cambiarán.
{"ok":false,"error":"rack_mismatch",
"message":"RACK_LOCATION no coincide con el rack registrado para QFM-12107. No se procesará una unidad que podría ser incorrecta.",
"expectedRackLocation":"2X-001B"}
| HTTP | error | Significado | Qué hacer |
|---|---|---|---|
| 400 | número de serie faltante / ubicación_del_rack_faltante | Falta un identificador obligatorio | Corrige la solicitud |
| 400 | comando_incorrecto | No reconocido COMANDO | Corrige la solicitud |
| 400 | nada_que_configurar | set_cycle sin nada que aplicar | Envía al menos un campo |
| 400 | poll_is_read_only | COMANDO=poll enviado con campos que escribirían | Omitir COMANDO, o usa set_cycle |
| 400 | tiempo_de_ciclo_defectuoso | INCUBACIÓN No es un número comprendido entre 0,17 y 168 horas | Corrige el valor — no se aplicó nada |
| 400 | campo_demasiado_largo | Un campo de la solicitud excede su límite (sección 5); campo y maxLength di cuál | Acortar el valor |
| 401 | no autorizado | Clave de API faltante o incorrecta | Revisa el encabezado; alerta |
| 403 | no_autorizado | Esa unidad no figura en tu cuenta | Revisa el número de serie; alerta |
| 404 | número de serie desconocido | No hay QFM con ese número de serie | Error tipográfico o unidad fuera de servicio; alerta |
| 409 | rack_mismatch | El número de serie es el tuyo, pero el rack no coincide | Alerta. Tu mapa está desactualizado — ubicación prevista del rack te dice cuál es la nuestra |
| 409 | ambiguous_serial | El número de serie coincide con más de una unidad | Contáctanos — un problema con los datos por nuestra parte |
| 502 | error_de_origen | No pudimos llegar a la plataforma de monitoreo | Volver a intentarlo con retrasos; alertar si la situación persiste |
Reintentos: se pueden reintentar sin problema los comandos «poll» y todos los demás. Usa un retroceso exponencial para el código 502; no reintentes los códigos 4xx, ya que no se resolverán sin modificar la solicitud.
5. Tamaños y tipos de campos
Define el tamaño de las columnas de tu base de datos según esta tabla. Estas son reglas fijas: el valor que devolvamos nunca
superará su límite, y cualquier valor solicitado que exceda dicho límite será rechazado con 400 campo_demasiado_largo
en lugar de truncadas. Cada respuesta está en formato JSON; las cadenas están en UTF-8, los números son números JSON sin formato
(sin separadores de miles, con punto decimal), los valores booleanos son verdadero/falso.
Campos de la solicitud
| Campo | Tipo | Límite |
|---|---|---|
QFM_SERIAL | cadena | 32 caracteres |
UBICACIÓN_DEL_RACK | cadena | 32 caracteres |
COMANDO | cadena | uno de encuesta, set_cycle, pausa, currículum (máximo 9 caracteres) |
NÚMERO DE ARTÍCULO / SKU | cadena | 64 caracteres |
PALLET_TAG, PO | cadena | 64 caracteres cada uno |
WAREHOUSE_ID | cadena | 64 caracteres |
INCUBACIÓN | horas decimales | De 0,17 a 168 (de 10 minutos a 7 días) |
DURACIÓN | minutos enteros | — |
Respuestas a la encuesta (200)
| Campo | Tipo | Tamaño / rango | Notas |
|---|---|---|---|
ok | booleano | — | Siempre presente. verdadero por cada respuesta correcta. |
QFM_SERIAL | cadena | ≤ 32 | Tu eco. |
UBICACIÓN_DEL_RACK | cadena | ≤ 32 | El estante que tenemos registrado. |
controlBox | cadena | ≤ 32 | Hoy, un identificador hexadecimal de 12 caracteres. |
ts | entero | 13 dígitos | Milenos de segundos desde el inicio de la era UTC: utilice un entero de 64 bits. |
WAREHOUSE_ID | cadena | ≤ 64 | Solo cuando lo enviaste. |
estado | cadena | ≤ 14 | Uno de INICIO, LISTO, PRUEBA DE ESTANQUEIDAD, SELLADO DEFECTUOSO, CORRER, PAUSA, COMPLETO, FALLO DEL MOTOR, FALLO DEL SENSOR, EXPLOSIÓN. |
deltap | decimal | 2 decimales, con signo | Pascals. Normalmente de 0 a unos 300; puede descender ligeramente a valores negativos. DECIMAL(8,2) abarca todo lo que el sensor puede reportar. |
restante | entero | De 0 a 604 800 | Segundos completos, nunca fraccionarios (máximo 7 días). |
airtC | decimal | 2 decimales, de −55,00 a 125,00 | DECIMAL(5,2). |
airtF | decimal | 1 cifra decimal, de −67,0 a 257,0 | DECIMAL(4,1). |
activo | booleano | — | |
SKU | cadena | ≤ 64 | Lo que sea que hayas enviado como NÚMERO DE ARTÍCULO; vacío cuando no hay ningún ciclo en ejecución. |
airtC/airtF, deltap, estado
y SKU son omitido cuando la unidad nunca haya reportado ese valor o el sensor
que lo controla esté fallando: analiza por clave, no por posición, y permite valores nulos en tu tabla.Respuesta al comando (202)
| Campo | Tipo | Tamaño / rango | Notas |
|---|---|---|---|
ok | booleano | — | La solicitud se realizó con éxito. Verifica esto primero en cada respuesta. |
aceptado | booleano | — | La orden fue autorizada y transmitida a la unidad. Solo se responderá a las órdenes que se den en el momento. Las órdenes son asincrónicas, por lo que aceptado significa en la fila, no aplicado — encuesta para confirmar. No verás ok:true con aceptado:false. |
QFM_SERIAL, UBICACIÓN_DEL_RACK, controlBox, WAREHOUSE_ID | cadena | como se indicó anteriormente | |
COMANDO | cadena | ≤ 9 | El comando que se ejecutó. |
tiempo de ciclo aplicado en horas | decimal | De 0,17 a 168 | Solo cuando se configuró el tiempo de ejecución. |
applied.SKU, applied.PALLET_TAG, applied.PO | cadena | ≤ 64 cada uno | Reflejo de lo que enviaste; cada uno está presente solo si se envió. |
cycleTimeChanged, skuRegistrado | booleano | — | skuRegistrado solo cuando se registraba un nuevo artículo. |
skuHorasRegistradas | decimal | De 0,17 a 168 | Solo cuando la biblioteca de elementos haya aprendido un tiempo de ejecución. |
skuHoursChanged | objeto | de, a horas decimales | Solo cuando se sustituyó un tiempo de ejecución almacenado. |
advertencia | cadena | ≤ 255 | Solo cuando está presente. A título informativo; el comando se aceptó de todos modos. |
Respuesta de error (4xx / 5xx)
| Campo | Tipo | Tamaño | Notas |
|---|---|---|---|
ok | booleano | — | Siempre falso. |
error | cadena | ≤ 32 | Código estable en minúsculas (sección 4). Alerta sobre esto. |
mensaje | cadena | ≤ 255 | Legible para los humanos; puede reformularse. |
ubicación prevista del rack | cadena | ≤ 32 | Con rack_mismatch solo. |
campo, maxLength | cadena, entero | ≤ 16, — | Con campo_demasiado_largo solo. |
campos ignorados | matriz de cadenas | ≤ 5 nombres | Con poll_is_read_only solo. |
estado de la etapa anterior | entero | 3 dígitos | Con algunos error_de_origen respuestas. |
Identidad y seguridad
- Cada instalación se autentica con su propia clave de API y está autorizada a solo sus propias unidades.
UBICACIÓN_DEL_RACKdebe coincidir con la ubicación asociada a eseQFM_SERIALo se rechaza la solicitud; esto evita que se ajuste la unidad incorrecta.- Las unidades se identifican mediante Serie QFM, que se mantiene estable incluso cuando se cambian las cajas de control;
controlBoxEn cada respuesta se indica qué casilla se seleccionó. - No incluyas tu clave de API en cadenas de correo electrónico ni en archivos compartidos. QuickFreeze podría limitar la frecuencia de los volúmenes excesivos de solicitudes.
Primeros pasos
QuickFreeze te proporciona tu clave de API y el QFM_SERIAL ↔ UBICACIÓN_EN_RACK mapa para tus unidades.
Una buena primera opción es realizar una consulta con una unidad activa y, luego, indicar una ubicación de rack deliberadamente incorrecta para ver
409 discrepancia de rack Vuelve. Si quieres, mándanos tu lista de SKU con los tiempos de ciclo.
NÚMERO DE ARTÍCULO solo para establecer los tiempos de ejecución desde el primer día.
Para solicitar acceso, comuníquese con su representante de QuickFreeze.
