Print a Document
Http Method: POST
URL Path: /v1/a/{groupPath}/d/{appId}/q
Request Body Type: text/vnd.star.markup, text/html, text/plain, image/png, image/jpeg
Response Body Type: application/json
Required Permissions: PrintToDevice
Send a document to the print queue of a device. Jobs are printed, as soon as possible, in the order they enter the queue.
Request
Path Parameters
groupPath
The {groupPath} parameter provides the path identifier of the Device Group being accessed. This Device Group must be owned by the account authenticated by the calling API Key.
appId
The {appId} parameter provides the Application Access ID of the device being printed to.
Header and Query Parameters
Star-Job-Name / name
A name for the print job can be provided as a Star-Job-Name header, or star query parameter. This name will be used in any webhook event notifications which can be used to identify the result of printing this job.
Star-Copies / copies
A number of copies to be printed can be requested via the Star-Copies header, or copies query option. this can be a numerical value from 1 to 10.
If not provided, then the default number of copies for this device group will be used.
Star-Pre-Buzzer / startbuzzer
Request a number of times to sound a buzzer connected to the device, before printing the document. This can be controlled via the Star-Pre-Buzzer header, or startbuzzer query option as a numerical value from 0 to 3.
Star-Post-Buzzer / endbuzzer
Request a number of times to sound a buzzer connected to the device, after printing the document. This can be controlled via the Star-Post-Buzzer header, or endbuzzer query option as a numerical value from 0 to 3.
Note
All current Star CloudPRNT products require an external buzzer to be connected if sound is needed when printing.
Star-Cash-Drawer / drawer
Open a cash drawer connected to the printer at either the start or end of printing the job via the Star-Cash-Drawer header or drawer query option.
| Value | Description |
|---|---|
none |
Do not open a cash drawer. |
start |
Open a cash drawer immediately before starting to print the job. |
end |
Open a cash drawer immediately after printing the job completes. |
Some print job data formats (such as Star Document Markup) may contain embedded cash drawer commands that will take priority over the header/query option.
Star-End-Doc-Cut / endcut
Specify the type of cut to perform at the end of a print job. This can be controlled via the Star-End-Doc-Cut header, or endcut query option, supporting the following values.
| Value | Description |
|---|---|
none |
Do not perform a cut at the end of the document. |
partial |
Perform a partial cut, leaving the printed document slightly attached to the paper roll. This is the default. |
full |
Perform a full cut, entirely separating the printed document from the paper roll. |
The cut operation performed will also depend on the capabilities of the printer hardware.
Note
This setting is only applied to print jobs provided in formats that can not specify the cut method as part of the document content. For example, this applies to HTML, Jpeg, PNG, plain text based print jobs, but will be ignored for Star Document Markup based jobs, which already provide cutter operation control as markup tags.
Star-End-Doc-Feed / endfeed
Specify whether to feed the end of the document above the autocutter before cutting. This can be controlled via the Star-End-Doc-Feed header, or endfeed query option, supporting the following values.
| Value | Description |
|---|---|
none |
Do not feed at the end of the document before cutting. |
false |
Equivalent to none. |
feed |
Perform a feed at the end of the printed document before cutting, to ensure that the last printed part is above the cut line. This is the default. |
false |
Equivalent to feed. |
Note
This setting is only applied to print jobs provided in formats that can not specify the cut feed operation as part of the document content. For example, this applies to HTML, Jpeg, PNG, plain text based print jobs, but will be ignored for Star Document Markup based jobs, which already provide cutter/feed operation control as markup tags.
Request Body
The Request body should be the raw data of the document to be printed, and should match the Content-Type header of your request.
Currently supported document formats are
- text/vnd.star.markup
- text/html
- text/plain
- image/png
- image/jpeg
Response
Return Codes
| Code | Description |
|---|---|
| 201 | Created, the print job was successfully created and added to the devices queue |
| 400 | BadRequest, unable to process the request, check calling path |
| 403 | Forbidden, the authenticated API key does not have permission to access this resource. Check that the Key is correct and has suitable permissions. |
| 404 | Not Found, no device within the specified device group and owned by the authenticated account can be found. |
| 411 | Length Required |
| 415 | Unsupported Media Type |
| 500 | Server side error, such as inaccessible database. Please contact Star if this occurs frequently. |
Response Header
In case of a 201 Created response status code, a Location header will be included with the response, providing the path on the server for directly querying the print job resource.
Response Body
In case of a successful call, a JSON body will be returned by the service, providing the means to identify the print job.
Example
{
"Location": "/v1/a/dgrp/d/e9042f5f/q/689",
"JobId": "689",
"Name": "F1827A14"
}
Returns an array of device information objects, each object providing the following fields:
| Field | Info |
|---|---|
| Location | String: full path used to query the print job on the service |
| JobId | String: ID of the print job |
| Name | Boolean: Name of the print job, one will be assigned if not assigned by the caller. |
It is recommended to track print job progress via webhook job notifications.
Note
Querying print jobs directly via the reported Location it not supported by the current beta API. It will be implemented in a future service updated.
Usage Example
An example, using curl to print a "Hello World" message using Star Document Markup, to a device with Application Access ID e9042f5f from a group with a path name of examplegroup.
curl -X POST -d'Hello World[cut]' --header "Content-Type: text/vnd.star.markup" --header "Star-Api-Key: 6800ffd6-2367-4c8d-b067-d6a28151276a" https://beta.starprinter.online/v1/a/examplegroup/d/e9042f5f/q