Criar uma tarefa de impressão

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

Envia uma tarefa de impressão para a impressora térmica na nuvem designada.

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>

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

Authorization: 9F3K7Q2WZ1ABCDEF:b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6

Ambos os valores estão disponíveis na consola Expedy, na secção API. Os pedidos com um SID:TOKEN ausente ou inválido são rejeitados e devolvem um envelope de erro (consulte Erros).

Todos os pedidos devem ser feitos através de HTTPS (TLS).

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
`printer_uid`	`string`	Sim	UID da impressora de destino, visível na consola em Printers (ex.: `WP0RGS1SEDZ`). Não inclua o símbolo `#`. Use `GET /printers/all` para o obter programaticamente.

Corpo do pedido

Content-Type: application/json

Parâmetro	Tipo	Obrigatório	Descrição
`printer_msg`	`string`	Sim	O conteúdo a imprimir, construído com as etiquetas de layout do talão (`<C>`, `<BOLD>`, `<IMG>`, `<QR>`, `<CUT/>`, …). Texto simples, códigos QR, imagens ou o URL de um PDF — tudo o que a impressora suportar.
`origin`	`string`	Não	Uma etiqueta livre para identificar a origem da tarefa (um URI, um nome de aplicação, um departamento…). Útil para filtrar e depurar nos seus registos.
`printer_han`	`string`	Não	A escrita com que compor o talão: `cn` chinês, `kr` coreano, `jp` japonês. Omita-o para as escritas latinas. Consulte Caracteres asiáticos.

Exemplo de pedido:

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

Exemplo 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

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

Valor	Escrita
`cn`	chinês
`kr`	coreano
`jp`	japonês

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.

{
  "printer_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 pelo servidor de impressão na nuvem Expedy.

ℹ️ Um 200 confirma apenas a receção do lado do servidor — não que o talão foi fisicamente impresso. A impressão é assíncrona: o servidor entrega a tarefa ao dispositivo na sua próxima ligação. Um 200 não garante a saída em papel, porque a impressora pode estar offline, sem papel, desligada ou inacessível na sua rede/SIM nesse momento. Use o request_uid devolvido para referenciar a tarefa nos seus próprios registos e pedidos de suporte.

Parâmetro	Tipo	Descrição
`request_uid`	`string`	Identificador único da tarefa de impressão aceite (ex.: `1X5ERXL94BYVWHP92DK3MCASUGJ`).

Exemplo de resposta:

{
  "request_uid": "1X5ERXL94BYVWHP92DK3MCASUGJ"
}

Erros

Qualquer estado diferente de 2xx devolve um envelope JSON com um campo message que descreve o problema:

{
  "message": "Invalid printer"
}

Estado	Significado
`401` / `403`	Credenciais ausentes ou inválidas (`SID` / `TOKEN`).
`422`	O pedido não pôde ser processado — por ex. um `printer_uid` desconhecido ou um corpo malformado.

Leia sempre o campo message em vez de confiar apenas no código de estado.

Boas práticas

Idempotência. Cada pedido aceite produz uma impressão. O endpoint não elimina duplicados, por isso, se repetir o pedido após um erro de rede, proteja-se contra a dupla impressão do seu lado (por ex. registando o request_uid, ou marcando a encomenda como impressa assim que receber um 200).
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.
Mantenha printer_msg dentro da largura do papel. 32 caracteres por linha a 58 mm, 48 a 80 mm. Consulte a referência de layout.

Listar as impressoras

Para descobrir os valores printer_uid da sua conta:

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

Devolve as impressoras associadas à sua conta (nome, largura do papel, UID, estado), usando o mesmo cabeçalho Authorization: <SID>:<TOKEN>.

SDK e exemplos

Prefere um cliente pronto a usar? Use o SDK oficial de Node.js — encapsula a autenticação, a listagem de impressoras e as tarefas de impressão:

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