Skip to main content

Sandbox with test keys

You can build and test your integration without a printer or an installed agent.

Cloud sandbox (jp_test_ keys)​

Create an API key in test mode (Dashboard → Developers → API keys, mode Test). Its prefix is jp_test_.

Jobs created with a test key never reach a device. The cloud prints them on its own virtual printer:

  • no device or printer is needed (printerId and deviceId are optional);
  • the job moves through queued, sending and printed (or failed), and sends the same webhooks as a real job;
  • receipt, ESC/POS, raw and text jobs keep a PNG preview of the printed paper.
curl -X POST https://api.jodaprint.dev/v1/jobs \
  -H "Authorization: Bearer jp_test_…" \
  -H "Content-Type: application/json" \
  -d '{"type":"text","encoding":"utf8","data":"Mèsi anpil"}'

curl https://api.jodaprint.dev/v1/jobs/<id>/preview \
  -H "Authorization: Bearer jp_test_…" -o job.png

With the Node SDK: await jp.jobs.preview(job.id).

The preview is drawn by the agent's own engine, compiled to WebAssembly, so it shows exactly what an 80 mm or 58 mm thermal printer prints. Remote images (https://… in an image block) show as a crossed box because the cloud does not download them; inline base64 images render.

Sandbox jobs do not count towards the plan's monthly jobs. They have "mode": "test" in the API and appear in the dashboard's job list like other jobs.

Receipt preview​

POST /v1/receipt/preview renders any receipt document to PNG without creating a job (scope jobs:write):

curl -X POST https://api.jodaprint.dev/v1/receipt/preview \
  -H "Authorization: Bearer $JODAPRINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document":{"width":"58mm","blocks":[{"type":"text","value":"Test"}]},"paper":"58mm"}' -o receipt.png

Options: paper (58mm or 80mm), profile (printer profile, default generic-80mm) and footer (add the free plan's "Printed with JodaPrint" line).

Local virtual printer​

Every agent shows a printer named JodaPrint Virtual. It saves each job in the agent's data folder (virtual/): the printer bytes, a PNG preview and a JSON file with the job details. Use it to test local mode from the browser without paper:

await jp.print({ printer: { name: "JodaPrint Virtual" }, type: "receipt", data: myReceipt });

Turn it off with printers.virtual.enabled: false in the device config.