Aller au contenu principal

Première impression depuis le navigateur

En mode local, votre page web parle directement à l'agent du même ordinateur. Chaque requête est signée par votre backend : un site quelconque ne peut donc pas imprimer sur les imprimantes de vos clients.

Il vous faut un agent installé et activé, et Node 18.4 ou plus récent pour le point de signature.

1. Autoriser votre site​

Tableau de bord → Développeurs → Origines autorisées → Ajouter, par exemple https://pos.example.com. Une origine est un schéma, un hôte et un port, sans chemin.

Pendant le développement sur http://localhost:3000, activez plutôt le mode développement sur la même page : il autorise tous les ports de http://localhost.

2. Créer une clé de signature​

Tableau de bord → Développeurs → Clés de signature → Créer. Le tableau de bord affiche :

  • l'identifiant de clé (par exemple sk_01J9…),
  • l'identifiant de votre organisation (org_…),
  • la clé privée, affichée une seule fois.

Rangez la clé privée dans les secrets de votre serveur, par exemple dans la variable d'environnement JODAPRINT_SIGNING_KEY. Ne la mettez jamais dans la page web. Les agents reçoivent la clé publique avec leur configuration en quelques secondes.

3. Ajouter le point de signature à votre serveur​

npm install @jodaprint/node
// server.ts (Express)
import express from "express";
import { createSigner, signRequestHandler } from "@jodaprint/node";

const signer = createSigner({
  orgId: "org_123",
  keyId: "sk_01J9ABC",
  privateKey: process.env.JODAPRINT_SIGNING_KEY!,
});

const app = express();
app.post(
  "/jodaprint/sign",
  express.json(),
  signRequestHandler(signer, {
    // Obligatoire : décidez qui peut imprimer. Ici, tout utilisateur connecté.
    authorize: (req) => Boolean(req.session?.user),
  }),
);
app.listen(3000);

Le même gestionnaire fonctionne avec les route handlers Next.js, Bun, Deno et Hono :

// app/jodaprint/sign/route.ts
export const POST = signRequestHandler(signer, { authorize: async (req) => isLoggedIn(req) });

4. Imprimer depuis la page​

npm install @jodaprint/sdk
import { JodaPrint, httpSigner } from "@jodaprint/sdk";

const jp = new JodaPrint({ orgId: "org_123", signer: httpSigner("/jodaprint/sign"), locale: "fr" });
await jp.connect(); // trouve l'agent sur wss://localhost:8182, 8283, 8384 ou 8485

const printers = await jp.printers.list();
console.log(printers.map((p) => `${p.id} ${p.name}`));

const job = await jp.printAndWait({
  type: "receipt",
  data: jp.receipt().text("Bonjour !").bold().center().feed(3).cut(),
  idempotencyKey: "commande-10492",
});
console.log(job.state); // "printed"

Sans printer, le travail part sur l'imprimante par défaut. Pour en choisir une : printer: { id: "prn_…" }, { alias: "receipt" } ou { name: "EPSON TM-T20III" }.

Sans bundler, chargez la version UMD. Elle définit window.JodaPrint :

<script src="https://cdn.jsdelivr.net/npm/@jodaprint/sdk/dist/jodaprint.umd.min.js"></script>
<script>
  const jp = new JodaPrint({ orgId: "org_123", signer: JodaPrint.httpSigner("/jodaprint/sign") });
</script>

En cas de problème​

ErreurSignification
AGENT_NOT_FOUNDAucun agent ne répond. Installez-le ou démarrez-le ; error.helpUrl pointe vers la page de téléchargement.
AGENT_CERT_UNTRUSTEDL'agent tourne mais le navigateur ne fait pas confiance à son certificat. Voir Dépannage.
ORIGIN_NOT_ALLOWEDAjoutez l'origine de la page (étape 1).
SIGNATURE_INVALIDMauvais identifiant de clé, organisation ou clé privée côté serveur.

Chaque erreur a un code, un message et retryable. Avec l'option locale: "fr", les messages propres au SDK sont en français. La liste complète est dans Codes d'erreur.

Ensuite​