Crear una tarea de impresión

POST https://www.expedy.fr/api/v2/printers/{printer_uid}/print

Envía una tarea de impresión a la impresora térmica en la nube designada.

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>

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

Authorization: 9F3K7Q2WZ1ABCDEF:b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6

Ambos valores están disponibles en la consola Expedy, en la sección API. Las solicitudes con un SID:TOKEN ausente o no válido se rechazan y devuelven un sobre de error (consulta Errores).

Todas las solicitudes deben realizarse mediante HTTPS (TLS).

Parámetros de ruta

Cuerpo de la solicitud

Content-Type: application/json

Ejemplo de solicitud:

{
  "printer_msg": "<C><BOLD>ORDER #1234</BOLD></C>\n<C>Table 7</C>\n--------------------------------\n1 x Burger\n2 x Fries\n<CUT/>",
  "origin": "pos-kitchen-01"
}

Ejemplo cURL:

curl -X POST "https://www.expedy.fr/api/v2/printers/WP0RGS1SEDZ/print" \
  -H "Authorization: <SID>:<TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"printer_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.

{
  "printer_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 por el servidor de impresión en la nube de Expedy.

ℹ️ Un 200 confirma únicamente la recepción del lado del servidor, no que el ticket se haya impreso físicamente. La impresión es asíncrona: el servidor entrega la tarea al dispositivo en su próxima conexión. Un 200 no garantiza la salida en papel, porque la impresora puede estar desconectada, sin papel, apagada o inaccesible en su red/SIM en ese momento. Usa el request_uid devuelto para referenciar la tarea en tus propios registros y solicitudes de soporte.

Ejemplo de respuesta:

{
  "request_uid": "1X5ERXL94BYVWHP92DK3MCASUGJ"
}

Errores

Cualquier estado distinto de 2xx devuelve un sobre JSON con un campo message que describe el problema:

{
  "message": "Invalid printer"
}

Lee siempre el campo message en lugar de fiarte solo del código de estado.

Buenas prácticas

• Idempotencia. Cada solicitud aceptada produce una impresión. El endpoint no elimina duplicados, así que si reintentas tras un error de red, protégete contra la doble impresión por tu parte (p. ej. registrando el request_uid, o marcando el pedido como impreso al recibir un 200).
• 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.
• Mantén printer_msg dentro del ancho del papel. 32 caracteres por línea a 58 mm, 48 a 80 mm. Consulta la referencia de diseño.

Listar las impresoras

Para descubrir los valores printer_uid de tu cuenta:

GET https://www.expedy.fr/api/v2/printers/all

Devuelve las impresoras vinculadas a tu cuenta (nombre, ancho del papel, UID, estado), usando la misma cabecera Authorization: <SID>:<TOKEN>.

SDK y ejemplos

¿Prefieres un cliente listo para usar? Usa el SDK oficial de Node.js: encapsula la autenticación, el listado de impresoras y las tareas de impresión:

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