CloudPrint connects software running in the cloud with a printer in an office, store or warehouse. Your application uses only the Public API; the local agent receives authorized work over an outbound connection.
## The parts of the system The customer backend obtains a token, selects a `printer_id`, supplies a document and creates a job. CloudPrint stores the document and job state. The local agent reports printers, reserves work and sends it to an operating-system queue or a compatible RAW path. ## Why a local agent is necessary Printers normally live inside private networks and should not be public services. The agent initiates the connection to CloudPrint, so deployment does not require inbound firewall rules, a customer VPN or remote-desktop access. ## Print job statuses A new job starts as `pending` and may move through `reserved` and `printing`. Terminal statuses are `printed`, `failed` and `cancelled`. `printed` confirms acceptance by the operating-system spooler, not physical output. Store `print_job_id`, tolerate future non-terminal values and translate the current state into language an operator can act on. ## Safe retries A network timeout must not create a second physical print. Generate a stable `Idempotency-Key` for each business operation. The same key and payload return the original job; the same key with a changed payload returns `409 Conflict`. ## What your application is responsible for CloudPrint sends the job to the selected printer and reports the result observed by the agent. Your application remains responsible for choosing the correct customer printer, preparing the file, linking the job to a business record and deciding how operators retry a failed print. ## Next steps