Criar uma tarefa de impressão USB

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

Envia uma tarefa de impressão para uma impressora ligada a uma das portas USB do seu dispositivo Expedy.

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

Autenticação

Este endpoint requer um cabeçalho Authorization contendo o seu SID e o seu TOKEN, separados por um único caractere de dois-pontos.

Authorization: <SID>:<TOKEN>

Authorization: 9F3K7Q2WZ1ABCDEF:b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6

⚠️ Isto não é um token Bearer. Não adicione um prefixo Bearer ou Basic — envie o valor bruto SID:TOKEN.

Ambos os valores estão disponíveis na consola Expedy, na secção API. Todos os pedidos devem ser feitos através de HTTPS (TLS).

Parâmetros de caminho

Uma porta só aceita tarefas depois de uma impressora ter sido detetada e configurada nela. Se a porta estiver livre, ou se a impressora nela nunca tiver sido configurada, a tarefa é rejeitada.

Corpo do pedido

Content-Type: application/json

Exemplo de pedido:

{
  "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"
}

Exemplo 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

O chinês, o japonês e o coreano exigem printer_han, definido com a escrita que vai imprimir.

1 continua a ser aceite como sinónimo de cn.

Por predefinição, o talão é composto em modo de byte único: cada caractere é mapeado através de uma das code pages da impressora. Nenhuma code page de byte único contém hanzi, kana ou hangul, pelo que sem este parâmetro cada um desses caracteres é substituído por um ? antes mesmo de a tarefa chegar ao dispositivo.

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

O valor tem de corresponder à escrita. Cada um seleciona uma codificação diferente e não se sobrepõem: coreano enviado como cn sai como ?, exatamente como se o parâmetro tivesse sido omitido.

A impressora tem de possuir o tipo de letra correspondente. O printer_han comuta o fluxo para o modo multibyte; os glifos vêm da ROM de tipos de letra da impressora. Um modelo vendido sem esse tipo de letra não imprimirá os caracteres mesmo com o valor certo, e uma impressora destinada ao mercado chinês inclui hanzi, o que não significa que inclua hangul ou kana. Teste a escrita de que precisa no modelo exato que vai instalar e contacte o suporte se o resultado não for legível.

O texto latino não precisa dele. Omita printer_han nas línguas europeias: os caracteres acentuados são tratados no modo predefinido.

Envie o seu conteúdo em UTF-8 em todos os modos. A API armazena e devolve exatamente o que recebe, pelo que o histórico de impressão na consola mostra o texto tal como chegou — a forma mais rápida de distinguir um problema de dados de um problema de impressora.

Resposta 200 OK

A tarefa foi aceite e colocada em fila.

ℹ️ Um 200 confirma apenas a receção do lado do servidor — não que o talão foi fisicamente impresso. A entrega é assíncrona: o dispositivo recebe a tarefa na sua próxima ligação. A impressora pode estar offline, sem papel, desligada ou inacessível nesse momento. Indique um notification_url se precisar de saber o que aconteceu realmente.

Exemplo de resposta:

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

Vale a pena ler last_ping em cada chamada: é o sinal mais barato de que um dispositivo se calou.

Erros

Boas práticas

• Idempotência. Cada pedido aceite produz uma impressão. O endpoint não elimina duplicados: se repetir o pedido após um erro de rede, proteja-se contra a dupla impressão do seu lado.
• Mantenha usb_msg dentro da largura do papel. 32 caracteres por linha a 58 mm, 48 a 80 mm. Consulte a referência de layout.
• Teste com e sem imagens. Alguns modelos de impressora rejeitam certos tipos de imagem e podem fazer falhar toda a tarefa — valide antes de entrar em produção.

Endpoints relacionados

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

Devolve o que está atualmente ligado a cada porta USB, com o fabricante e o modelo detetados. Use-o para descobrir em que porta imprimir e para confirmar que uma impressora continua onde espera.

/usb/conf devolve a configuração guardada de cada porta: largura do papel, modo de impressão, modo gráfico.

SDK e exemplos

Prefere um cliente pronto a usar? Use o SDK oficial de Node.js:

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