CloudPrint provides server-controlled web application printing for invoices, labels, receipts and operational documents. The browser sends user intent to your backend; the backend selects the local printer, creates an idempotent job and reports the actual result.
## When the browser print dialog is enough Use `window.print()` when a person can choose a printer and confirm every job locally. Use a Web Application Printing API when your product must route to a saved printer, print at another location, remove repetitive dialogs, audit results or recover safely from network failures. ## Send print jobs from your backend The frontend sends your backend a document reference and the selected location or printer. The backend generates or retrieves the file, calls the CloudPrint Public API and returns its own operation identifier. Neither `client_secret` nor the Bearer token reaches the browser. ## Use the minimal API flow Read printers with `GET /api/v1/printers`, upload the prepared file through `POST /api/v1/documents`, create the job with `POST /api/v1/print-jobs`, then read `GET /api/v1/print-jobs/{printJobId}` until a terminal result. The [Local Printer API guide](/docs/api/agents-and-printers/) explains agent and queue setup. ## Printer selection During setup, read printers from `GET /api/v1/printers` and persist the stable `printer_id`. The UI may show the printer name, agent and online state, but a display name is not a routing key. ## Operator experience After a user selects Print, show accepted, waiting, printing and final states. Prevent accidental double-clicks while allowing an intentional reprint as a new operation. A failure view should include a readable reason and a reference support can use. ## Surviving network failures The backend should send a stable `Idempotency-Key`, persist `print_job_id` and continue status tracking after a page refresh. After a timeout, do not assume the request failed; repeat the same idempotent request or recover the stored result first. ## Patterns to avoid Do not call the agent from browser code, expose printers to the internet, put credentials in localStorage or treat an accepted HTTP request as proof of printing. Only a terminal print job status describes the outcome. ## Next steps