Créer une tâche d'impression USB

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

Envoie une tâche d'impression vers une imprimante branchée sur l'un des ports USB de votre boîtier Expedy.

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

Authentification

Ce endpoint nécessite un en-tête Authorization contenant votre SID et votre TOKEN, séparés par un seul deux-points.

Authorization: <SID>:<TOKEN>

Authorization: 9F3K7Q2WZ1ABCDEF:b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6

⚠️ Ce n'est pas un jeton Bearer. N'ajoutez pas de préfixe Bearer ni Basic — envoyez la valeur brute SID:TOKEN.

Les deux valeurs sont disponibles dans la console Expedy, rubrique API. Toutes les requêtes doivent être effectuées en HTTPS (TLS).

Paramètres de chemin

Un port n'accepte de tâche qu'une fois qu'une imprimante y a été détectée puis configurée. Si le port est libre, ou si l'imprimante qui s'y trouve n'a jamais été configurée, la tâche est refusée.

Corps de la requête

Content-Type : application/json

Exemple de requête :

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

Exemple 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"}'

Caractères asiatiques

Le chinois, le japonais et le coréen exigent printer_han, réglé sur l'écriture que vous imprimez.

1 reste accepté comme synonyme de cn.

Par défaut, le ticket est composé en mode mono-octet : chaque caractère est associé à l'une des code pages de l'imprimante. Aucune code page mono-octet ne contient de hanzi, de kana ni de hangul : sans ce paramètre, chacun de ces caractères est remplacé par un ? avant même que la tâche n'atteigne l'appareil.

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

La valeur doit correspondre à l'écriture. Chacune sélectionne un encodage différent, et ils ne se recouvrent pas : du coréen envoyé en cn ressort en ?, exactement comme si le paramètre avait été omis.

L'imprimante doit posséder la police correspondante. printer_han bascule le flux en mode multi-octets ; les glyphes, eux, viennent de la ROM de police de l'imprimante. Un modèle vendu sans cette police n'imprimera pas ces caractères, même avec la bonne valeur, et une imprimante destinée au marché chinois embarque les hanzi, ce qui ne signifie pas qu'elle embarque le hangul ou les kana. Testez l'écriture dont vous avez besoin sur le modèle exact que vous déployez, et contactez le support si le résultat n'est pas lisible.

Le texte latin n'en a pas besoin. Laissez printer_han de côté pour les langues européennes : les caractères accentués sont gérés par le mode par défaut.

Envoyez votre contenu en UTF-8 dans tous les modes. L'API stocke et renvoie exactement ce qu'elle reçoit : l'historique d'impression de la console affiche donc le texte tel qu'il est arrivé, ce qui reste le moyen le plus rapide de distinguer un problème de données d'un problème d'imprimante.

Réponse 200 OK

La tâche a été acceptée et mise en file d'attente.

ℹ️ Un 200 confirme uniquement la réception côté serveur — pas que le ticket a été physiquement imprimé. La remise est asynchrone : le boîtier reçoit la tâche lors de sa prochaine connexion. L'imprimante peut être hors ligne, à court de papier, éteinte ou injoignable à cet instant. Renseignez notification_url si vous avez besoin de savoir ce qui s'est réellement passé.

Exemple de réponse :

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

last_ping mérite d'être lu à chaque appel : c'est le signal le moins coûteux qu'un boîtier s'est tu.

Erreurs

Bonnes pratiques

• Idempotence. Chaque requête acceptée produit une impression. Le endpoint ne dédoublonne pas : si vous réessayez après une erreur réseau, protégez-vous contre la double impression de votre côté.
• Gardez usb_msg dans la largeur du papier. 32 caractères par ligne en 58 mm, 48 en 80 mm. Voir la référence de mise en page.
• Testez avec et sans images. Certains modèles d'imprimante rejettent certains types d'images et peuvent faire échouer toute la tâche — validez avant la mise en production.

Endpoints associés

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

Renvoie ce qui est actuellement branché sur chaque port USB, avec le fabricant et le modèle détectés. Utilisez-le pour découvrir sur quel port imprimer, et pour vérifier qu'une imprimante est toujours là où vous le croyez.

/usb/conf renvoie la configuration enregistrée de chaque port : largeur du papier, mode d'impression, mode graphique.

SDK & exemples

Vous préférez un client prêt à l'emploi ? Utilisez le SDK officiel Node.js :

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