Skip to main content

First print from a server

In cloud mode your backend sends the job to the JodaPrint cloud, which forwards it to the agent over the connection the agent keeps open. It works from any server, behind any NAT, and the printer does not need to be reachable from the internet.

1. Create an API key​

Dashboard → Developers → API keys → Create. Choose the scopes jobs:write, jobs:read and printers:read. The key (jp_live_…) is shown once; store it as JODAPRINT_API_KEY.

Use a jp_test_… key to print in the sandbox instead of on a real printer.

2. Find the printer​

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

Each printer has a cloud id (prn_…) and belongs to a device (dev_…). Target a printer with printerId, or a device with deviceId and an optional alias (receipt, label…) set in the device config. Without an alias, the device's default printer prints.

3. Print​

With curl​

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

The answer is the job (201). When the device is online it prints within a second; otherwise the job stays queued until the device reconnects or the job expires (24 hours by default).

With the Node SDK​

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: "Bonjou!" }, { type: "cut" }] },
    metadata: { orderId: "10492" },
  },
  { idempotencyKey: "order-10492-receipt" },
);

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

The client retries rate limits (429), server errors and network errors with backoff. Job creations always carry an idempotency key (yours or a generated one), so a retry never prints twice.

4. Follow the job​

  • Poll GET /v1/jobs/{id}: the job carries its state history in events.
  • Or receive webhooks job.printed and job.failed: see Webhooks.

Idempotency​

A second job with the same Idempotency-Key within 24 hours returns the first job and prints nothing. Use your order number: a retried request or a double click never prints twice.

Next​