Aller au contenu principal

Première impression depuis un serveur

En mode cloud, votre backend envoie le travail au cloud JodaPrint, qui le transmet à l'agent par la connexion que l'agent garde ouverte. Cela fonctionne depuis n'importe quel serveur, derrière n'importe quel NAT, et l'imprimante n'a pas besoin d'être joignable depuis internet.

1. Créer une clé d'API​

Tableau de bord → Développeurs → Clés d'API → Créer. Choisissez les portées jobs:write, jobs:read et printers:read. La clé (jp_live_…) n'est affichée qu'une fois ; rangez-la dans JODAPRINT_API_KEY.

Utilisez une clé jp_test_… pour imprimer dans le bac à sable plutôt que sur une vraie imprimante.

2. Trouver l'imprimante​

curl https://api.jodaprint.dev/v1/printers -H "Authorization: Bearer $JODAPRINT_API_KEY"

Chaque imprimante a un id cloud (prn_…) et appartient à un appareil (dev_…). Ciblez une imprimante avec printerId, ou un appareil avec deviceId et un alias facultatif (receipt, label…) défini dans la configuration de l'appareil. Sans alias, l'imprimante par défaut de l'appareil imprime.

3. Imprimer​

Avec curl​

curl https://api.jodaprint.dev/v1/jobs \
  -H "Authorization: Bearer $JODAPRINT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: commande-10492-ticket" \
  -d '{
    "printerId": "prn_01J8Z2ABCDEF",
    "type": "receipt",
    "encoding": "json",
    "data": { "width": "80mm", "blocks": [
      { "type": "text", "value": "Bonjour !", "align": "center", "bold": true, "size": 2 },
      { "type": "feed", "lines": 3 },
      { "type": "cut", "mode": "partial" }
    ] }
  }'

La réponse est le travail (201). Si l'appareil est en ligne, il imprime en moins d'une seconde ; sinon le travail reste queued jusqu'à la reconnexion de l'appareil ou l'expiration du travail (24 heures par défaut).

Avec le SDK Node​

npm install @jodaprint/node
import { JodaPrintClient } from "@jodaprint/node";

const jp = new JodaPrintClient({ apiKey: process.env.JODAPRINT_API_KEY! });

const job = await jp.jobs.create(
  {
    deviceId: "dev_01J8Z2ABCDEF",
    alias: "receipt",
    type: "receipt",
    encoding: "json",
    data: { width: "80mm", blocks: [{ type: "text", value: "Bonjour !" }, { type: "cut" }] },
    metadata: { orderId: "10492" },
  },
  { idempotencyKey: "commande-10492-ticket" },
);

const latest = await jp.jobs.get(job.id);
console.log(latest.state); // queued, sending, printed, failed ou cancelled

Le client réessaie les limites de débit (429), les erreurs serveur et les erreurs réseau avec un délai croissant. Les créations de travaux portent toujours une clé d'idempotence (la vôtre ou une clé générée) : une nouvelle tentative n'imprime jamais deux fois.

4. Suivre le travail​

  • Interrogez GET /v1/jobs/{id} : le travail contient l'historique de ses états dans events.
  • Ou recevez les webhooks job.printed et job.failed : voir Webhooks.

Idempotence​

Un second travail avec la même Idempotency-Key dans les 24 heures renvoie le premier travail et n'imprime rien. Utilisez votre numéro de commande : une requête répétée ou un double clic n'imprime jamais deux fois.

Ensuite​