Crear una tarea de impresión USB

POST https://www.expedy.fr/api/v2/devices/{device_uid}/usb/{usb_port}/print

Envía una tarea de impresión a una impresora conectada a uno de los puertos USB de tu dispositivo Expedy.

URL base: https://www.expedy.fr/api/v2

Autenticación

Este endpoint requiere una cabecera Authorization que contenga tu SID y tu TOKEN, separados por un solo signo de dos puntos.

Authorization: <SID>:<TOKEN>

Authorization: 9F3K7Q2WZ1ABCDEF:b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6

⚠️ Esto no es un token Bearer. No añadas un prefijo Bearer ni Basic: envía el valor en bruto SID:TOKEN.

Ambos valores están disponibles en la consola Expedy, en la sección API. Todas las solicitudes deben realizarse mediante HTTPS (TLS).

Parámetros de ruta

Un puerto solo acepta tareas cuando se ha detectado y configurado una impresora en él. Si el puerto está libre, o la impresora que hay en él nunca se configuró, la tarea se rechaza.

Cuerpo de la solicitud

Content-Type: application/json

Ejemplo de solicitud:

{
  "usb_msg": "<C><BOLD>ORDER #1234</BOLD></C>\n<C>Table 7</C>\n--------------------------------\n1 x Burger\n2 x Fries\n<CUT/>",
  "notification_url": "https://www.example.com/print-callback",
  "origin": "pos-kitchen-01"
}

Ejemplo cURL:

curl -X POST "https://www.expedy.fr/api/v2/devices/OOBBZ100PI/usb/1/print" \
  -H "Authorization: <SID>:<TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"usb_msg":"<C><BOLD>Hello</BOLD></C><CUT/>","origin":"my-app"}'

Caracteres asiáticos

El chino, el japonés y el coreano requieren printer_han, ajustado a la escritura que vas a imprimir.

1 se sigue aceptando como sinónimo de cn.

De forma predeterminada, el ticket se compone en modo de un solo byte: cada carácter se asigna mediante una de las code pages de la impresora. Ninguna code page de un solo byte contiene hanzi, kana ni hangul, de modo que sin este parámetro cada uno de esos caracteres se sustituye por un ? antes incluso de que la tarea llegue al dispositivo.

{
  "usb_msg": "<C><BOLD>주문 #1234</BOLD></C>\n<CUT/>",
  "printer_han": "kr"
}

El valor debe coincidir con la escritura. Cada uno selecciona una codificación distinta y no se solapan: el coreano enviado como cn sale como ?, exactamente igual que si se hubiera omitido el parámetro.

La impresora debe incorporar la fuente correspondiente. printer_han cambia el flujo a modo multibyte; los glifos proceden de la ROM de fuentes de la impresora. Un modelo vendido sin esa fuente no imprimirá los caracteres aunque el valor sea el correcto, y una impresora destinada al mercado chino incorpora hanzi, lo que no significa que incorpore hangul o kana. Prueba la escritura que necesitas en el modelo exacto que vayas a desplegar y contacta con soporte si el resultado no es legible.

El texto latino no lo necesita. Omite printer_han para las lenguas europeas: los caracteres acentuados se gestionan en el modo predeterminado.

Envía tu contenido en UTF-8 en todos los modos. La API almacena y devuelve exactamente lo que recibe, por lo que el historial de impresión de la consola muestra el texto tal como llegó, que es la forma más rápida de distinguir un problema de datos de uno de impresora.

Respuesta 200 OK

La tarea fue aceptada y puesta en cola.

ℹ️ Un 200 confirma únicamente la recepción del lado del servidor, no que el ticket se haya impreso físicamente. La entrega es asíncrona: el dispositivo recibe la tarea en su próxima conexión. La impresora puede estar desconectada, sin papel, apagada o inaccesible en ese momento. Indica una notification_url si necesitas saber qué ocurrió realmente.

Ejemplo de respuesta:

{
  "last_ping": 1641509604,
  "request_uid": "1X5ERXL94BYVWHP92DK3MCASUGJ"
}

Conviene leer last_ping en cada llamada: es la señal más barata de que un dispositivo ha dejado de responder.

Errores

Buenas prácticas

• Idempotencia. Cada solicitud aceptada produce una impresión. El endpoint no elimina duplicados: si reintentas tras un error de red, protégete contra la doble impresión por tu parte.
• Mantén usb_msg dentro del ancho del papel. 32 caracteres por línea a 58 mm, 48 a 80 mm. Consulta la referencia de diseño.
• Prueba con y sin imágenes. Algunos modelos de impresora rechazan ciertos tipos de imagen y pueden hacer fallar toda la tarea: valida antes de pasar a producción.

Endpoints relacionados

GET https://www.expedy.fr/api/v2/devices/{device_uid}/usb/scan/read

Devuelve lo que hay conectado actualmente en cada puerto USB, con el fabricante y el modelo detectados. Úsalo para descubrir en qué puerto imprimir y para confirmar que una impresora sigue donde esperas.

/usb/conf devuelve la configuración guardada de cada puerto: ancho del papel, modo de impresión, modo gráfico.

SDK y ejemplos

¿Prefieres un cliente listo para usar? Usa el SDK oficial de Node.js:

👉 github.com/ExpedyDev/expedy-sdk-node