Tickets

Décrivez un ticket en JSON (type: "receipt", encoding: "json"). L'agent le convertit en ESC/POS pour l'imprimante cible : vous n'écrivez jamais de commandes d'imprimante. Le même document s'imprime sur les imprimantes 58 mm et 80 mm de toutes les marques prises en charge.

Exemple

{
  "width": "80mm",
  "codepage": "CP858",
  "blocks": [
    { "type": "image", "src": "https://example.com/logo.png", "width": 384, "align": "center" },
    { "type": "text", "value": "Boutique Bèl Fanm", "align": "center", "bold": true, "size": 2 },
    { "type": "text", "value": "Pétion-Ville, Haïti", "align": "center" },
    { "type": "line", "style": "dashed" },
    {
      "type": "table",
      "columns": [
        { "width": 0.6, "align": "left" },
        { "width": 0.15, "align": "right" },
        { "width": 0.25, "align": "right" }
      ],
      "rows": [
        ["Rouj a lèv", "2", "1 500,00"],
        ["Poud", "1", "900,00"]
      ]
    },
    { "type": "line", "style": "solid" },
    { "type": "pair", "left": "TOTAL", "right": "2 400,00 HTG", "bold": true },
    { "type": "qr", "value": "https://example.com/r/10492", "size": 6, "align": "center" },
    { "type": "barcode", "format": "CODE128", "value": "10492", "height": 60, "hri": "below" },
    { "type": "feed", "lines": 3 },
    { "type": "cut", "mode": "partial" },
    { "type": "drawer" }
  ]
}

Ce qu'il imprime sur une imprimante 80 mm (dessiné par le moteur de rendu de l'agent ; dans les aperçus, le logo distant s'affiche comme une case barrée) :

Le ticket d'exemple imprimé en 80 mm

Blocs

Bloc	Champs
`text`	`value`, `align` (`left`, `center`, `right`), `bold`, `underline`, `size` 1–8, `invert`, `font` (`a` ou `b`)
`line`	`style` : `solid`, `dashed` ou `double`
`pair`	`left` et `right` sur une même ligne (le côté gauche est raccourci si nécessaire), `bold`
`table`	`columns` (chacune avec `width`, une fraction de la ligne, et `align`), `rows` (listes de chaînes), `bold`. Les cellules longues passent à la ligne.
`qr`	`value`, `size` (taille d'un module en points, 1–16), `errorLevel` (`L`, `M`, `Q`, `H`), `align`
`barcode`	`format` (`CODE128`, `EAN13`, `EAN8`, `UPC-A`, `CODE39`, `ITF`), `value`, `height` en points, `width` 1–6, `hri` (`none`, `above`, `below`, `both`), `align`. Les chiffres de contrôle EAN et UPC sont vérifiés.
`image`	`src` (une URL https, ou un PNG/JPEG en base64), `width` en points, `align`, `dithering` (`floyd-steinberg` ou `threshold`)
`feed`	`lines` : nombre de lignes à avancer
`cut`	`mode` : `full` ou `partial`
`drawer`	ouvre le tiroir-caisse ; `pin` 2 (par défaut) ou 5
`raw`	`data` : octets d'imprimante en base64 (solution de secours)

Un document compte au plus 2 000 blocs. Le schéma complet est protocol/schemas/receipt-document.json.

Largeur du papier et caractères par ligne

width vaut 58mm ou 80mm ; s'il est absent, le papier de l'imprimante s'applique. Le nombre de caractères par ligne vient du profil de l'imprimante, pas du document :

Papier	Police A	Police B
58 mm	32	42
80 mm	48	64

Un ticket 58 mm avec tous les types de blocs :

Tous les types de blocs en 58 mm

Un bon de cuisine avec du texte en grand, du texte inversé, la police B et un tableau à retour à la ligne :

Un bon de cuisine de restaurant en 80 mm

Accents et pages de code

Les imprimantes thermiques ne comprennent pas l'UTF-8. L'agent convertit votre texte dans la page de code de l'imprimante : CP437, CP850, CP858 (le choix par défaut pour le français et le créole, avec le signe euro), CP1252, CP866 ou ISO-8859-15. Les caractères absents de la page de code sont translittérés (œ → oe) ou, en dernier recours, imprimés sans accent.

Choisissez la page de code dans le document (codepage), dans le travail (options.codepage) ou par imprimante dans la configuration de l'appareil (printers.defaults.<printerId>.codepage). Voir Dépannage si les accents sortent mal.

Images

Les URL sont téléchargées par l'agent (5 secondes et 2 Mo au plus, en cache pendant 24 heures). Le base64 intégré fonctionne toujours, même hors ligne.
width est en points d'imprimante : 384 points font toute la largeur d'une imprimante 58 mm, 576 celle d'une imprimante 80 mm.
Par défaut, les images sont converties en noir et blanc avec le tramage Floyd–Steinberg. Utilisez threshold pour les logos en aplats de couleur.

Construire les tickets dans le code

Le SDK navigateur propose un constructeur fluide qui produit le même JSON :

const doc = jp
  .receipt({ width: "80mm", codepage: "CP858" })
  .text("Boutique Bèl Fanm")
  .bold()
  .center()
  .size(2)
  .line("dashed")
  .pair("TOTAL", "2 400,00 HTG")
  .qr("https://example.com/r/10492")
  .feed(3)
  .cut();
await jp.print({ type: "receipt", data: doc });

Depuis un serveur, envoyez le JSON dans data avec POST /v1/jobs. Pour vérifier une mise en page sans imprimer, utilisez POST /v1/receipt/preview (voir Bac à sable).

Options de travail pour les tickets

options.cut (full, partial, none) et options.openDrawer s'appliquent après le document. options.copies l'imprime plusieurs fois. Les valeurs par défaut par imprimante (paper, codepage, cut) viennent de printers.defaults dans la configuration.

Avec le forfait gratuit, les tickets se terminent par une petite ligne « Printed with JodaPrint ».

Exemple​

Blocs​

Largeur du papier et caractères par ligne​

Accents et pages de code​

Images​

Construire les tickets dans le code​

Options de travail pour les tickets​