Skip to main content

Generating Work Orders

Overview

Because the scantrust platform is built to serve large numbers of codes, new codes are created asynchronously (in the background) and can be downloaded as a zip archive. (see Downloading Workorders section).

This page describes the API, however a prebuilt tool to create workorders is also available here.

Codes can be generated as a workorder in two ways:

  1. Generating Serialized Identifiers (SID) workorders: these workorders are scantrust QR codes without the secure graphic. The brand owner can self-generate and download these workorders and they do not require a printing partner.
  2. Scantrust Secure Codes (SSC) workorders: these workorders contain the copy-protection secure graphic and require a printing partner with calbrated equipment and substrate. These workorders are generated using a workorder template which is set up by one of the Scantrust Engineers during the project implementation.

UAT token permissions

The UAT token needs to have access to the following permissions:

  • workorder_create
  • workorder_delete
  • workorder_cancel
  • workorder_download
  • workorder_edit
  • workorder_view
  • workorder_sid_download
  • workorder_archive

The UAT token must be set in the header fields of all requests as described in Authentication & Tokens.

Generating Serialized Identifiers (SID) workorders

Obtaining SID codes from the scantrust system requires 3 steps:

  1. Use the create SID workorder endpoint and retrieve a new workorder id
  2. Query the search workorder endpoint to verify the workorder has the state completed as well as the codegen_file download-link is available
  3. Call the download workorder file endpoint to download the codes and their images.
  4. Optionally: call the download workorder serial numbers endpoint to download a more simple csv format

Proceed to the (Downloading Workorders section)) for more information on the file content(s).

API Design: Create SID Workorder

SID codes are codes without the secure graphic. They can be generated relatively simply and dont need a complicated setup.

POST: /api/v2/workorders/create-sid/

Generate a workorder for a company

AttributeRequired?Description
activate_on_completerequiredfalse or true wether codes should be active immediately or not.
referencerequiredstring, internal reference, must be unique for the company.
remarksoptionalstring, description of this workorder
quantityrequiredinteger, number of codes to be generated
use_serial_numberrequiredfalse or true (default), if true, serial number are added
url_prefixoptionalstring, set if a special URL is used (default: https://st4.ch/q/)
productoptionalstring: Scantrust product SKU used for these codes.
extended_id_styleoptional"compact-12" or "legacy", see Extended ID (default: legacy)

The reference is important because it allows you to later look up the newly created workorder easily.

The full URL of a scantrust SID code is formed by using the url_prefix + extended_id. The length of the extended id is determined by the extended_id_style:

  • compact-12: 12 characters a-Z,0-9,-,_ (example: aB1_3dZ97-x2)
  • legacy: 32 characters A-Z,0-9 (example: AERFJHUI2GHAIPGEUHGEYUGF69G3EXF)

Example JSON payload

{
"activate_on_complete": false,
"reference": "REF-001",
"remarks": "Generated for Customer X",
"quantity": 100,
"use_serial_number": true,
"url_prefix": "https://my-url.com/",
"extended_id_style": "compact-12",
"product": "123456789"
}

Response (201): Created

When the workorder has been created, a JSON response will contain:

{
"id": 4879,
"company": {
"id": 339,
....
},
"printing_partner": null,
"equipment": null,
"state": "new",
"due_date": null,
"reference": "REF-001",
"creation_date": "2020-01-10T08:55:08.985433Z",
"code_layout": "none",
"use_serial_number": true,
"static_unique_codes_quantity": 1,
"quantity": 10,
"is_ready_to_print": false,
"date_codes_completed": null,
"is_archived": false,
"codegen_status": 6,
"codegen_file": null,
"data": {
"remarks": "Generated for Test Brand",
"activate_on_complete": false
},
"product": {
"id": ...,
...
},
"brand": {
"id": ...,
...
},
"remarks": "Generated for Test Brand",
"printed_date": null,
"has_secure_workflow": false,
"static_impositions": 0,
"designer": null,
"external_id": "",
"is_fingerprint_trained": false,
"substrate": null,
"template": null,
"template_image": null,
"is_hybrid": false,
"is_static_print": false,
"is_fp_serialized": false,
"url_prefix": "https://my-url.com/",
"extended_id_style": "compact-12"
}

Important fields

  • state: "new", "ready to print" or "completed"
  • codegen_status: shows the code-generation status in a numerical way. "4" indicates generation has completed succesfully
  • codegen_file: the link to the file containing the generated codes. Note that this link is directly created for SID workorders, but for the SSC-workorders the printing partner needs to confirm the workorder first before the generation starts.

Generating Secure Scantrust Identifiers (SSC) workorders

Obtaining SSC codes from the scantrust system requires the same steps as SID workorders, however for SSC codes, the printing partner needs to generate the codes based on their printing equipment and substrate:

  1. Brand Owner: Call the create SG workorder endpoint and retrieve the workorder id
  2. Printing Partner: confirm the workorder and generate the codes
  3. Brand Owner: Query the search workorder endpoint to verify the workorder has the state completed as well as the codegen_file download-link is available
  4. Brand Owner: Call the download workorder file endpoint to download the codes and their images.

Proceed to the (Downloading Workorders section)) for more information on the file content(s).

API Design - Create SG Workorder

GET /api/v2/workorders/templates/

Get all available workorder templates and their attributes. To create an SG workorder, it is recommended to first choose a template.

Response (200): OK

{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": 164,
"name": "SG_Template_1",
"description": "n.a.",
"company": 6091,
"custom_layout": null,
"substrate": null,
"substrate_name": "",
"printing_partner": null,
"image": null,
"code_layout": "sg-outside",
"use_serial_number": true,
"is_hybrid": true,
"is_fp_serialized": false,
"is_static_print": false,
"is_archived": false,
"activate_on_complete": false,
"url_prefix": "",
"extended_id_style": "legacy"
}
]
}

POST /api/v2/workorders/create-sg/

AttributeRequired?Description
productoptionalstring, Scantrust product SKU used for these codes.
templateoptionalinteger, retrieved from id in the above GET template request
quantityrequiredinteger, number of codes to be generated
remarksoptionalstring, description of this workorder
activate_on_completeoptionalfalse (default) or true, whether codes should be active immediately or not.
extended_id_styleoptional"compact-12" or "legacy", see Extended ID (default: legacy)
substrateoptionalinteger, substrate id (default: null)
code_layoutrequiredstring, code layout method, "sg-inside" or "sg-outside"
use_serial_numberoptionalfalse or true (default), if true, serial numbers are added
is_hybridoptionalfalse or true (default), non-hybrid or hybrid printing method
template_imageoptionalfalse (default) or true, whether there's an image of the template
is_fp_serializedoptionalfalse or true (default), whether codes are serialized
is_static_printoptionalfalse (default) or true, whether the codes are static
static_unique_codes_quantityoptionalinteger, quantity of static unique codes
printing_partnerrequiredinteger, company ID of the Printing Partner
referencerequiredstring, internal reference, must be unique for the company.
remarksoptionalstring, description of this workorder
url_prefixoptionalstring, set if a special URL is used (default: https://st4.ch/q/)

IMPORTANT: Attribute values need to change based on workorder template. When a workorder template is chosen, if attributes are provided in workorder template, they are also required in the POST Request. The attributes cannot be passed with template id.

Example JSON payload

{
"product": "P2",
"template": "1",
"quantity": "10",
"remarks": "remarks 1",
"activate_on_complete": true,
"extended_id_style": "legacy",
"substrate": 1,
"code_layout": "sg-outside",
"use_serial_number": true,
"is_hybrid": false,
"template_image": null,
"is_fp_serialized": false,
"is_static_print": false,
"static_unique_codes_quantity": 0,
"printing_partner": 3
}

Response (201): Created

{
"id": 24,
"company": {
"id": 2,
...
},
"printing_partner": {
"id": 3,
...
},
"equipment": {
"id": 1,
...
},
"state": "new",
"due_date": null,
"reference": null,
"creation_date": "2021-03-10T08:35:39.507156Z",
"code_layout": "sg-outside",
"use_serial_number": true,
"static_unique_codes_quantity": 0,
"quantity": 10,
"is_ready_to_print": false,
"date_codes_completed": null,
"is_archived": false,
"codegen_status": 1,
"codegen_file": null,
"data": {
"remarks": "remarks 1",
"static_unique_codes_quantity": 0,
"activate_on_complete": true
},
"product": {
"id": 2,
...
},
"brand": {
"id": 1,
...
},
"remarks": "remarks 1",
"printed_date": null,
"has_secure_workflow": false,
"static_impositions": 0,
"designer": null,
"external_id": "",
"is_fingerprint_trained": false,
"substrate": {
"id": 1,
"name": "Plain Paper",
"description": ""
},
"template": 1,
"template_image": null,
"is_hybrid": false,
"is_static_print": false,
"is_fp_serialized": false,
"url_prefix": "HTTPS://QR2.CH/Q/",
"extended_id_style": "legacy"
}

API Design - Printer Confirm

Before SSC codes are generated, a printing partner needs to confirm the printing equipment and substrate in order for the QA to be done.

PATCH /api/v2/workorders/4977/printer-confirm/

Example JSON payload

{
"substrate": "1",
"equipment": "2",
"external_id": "3"
}

Response (200): Ok

{
"id": 5094,
"company": {
"id": 339,
...
},
"printing_partner": {
"id": 346,
...
},
"equipment": {
"id": 214,
...
},
"state": "new",
"due_date": null,
"reference": "Tk-022",
"creation_date": "2021-03-10T08:46:55.234818Z",
"code_layout": "sg-inside",
"use_serial_number": true,
"static_unique_codes_quantity": 1,
"quantity": 100,
"is_ready_to_print": false,
"date_codes_completed": null,
"is_archived": false,
"codegen_status": 6,
"codegen_file": null,
"data": {
"remarks": "test",
"activate_on_complete": false,
"static_unique_codes_quantity": 1
},
"product": {
"id": 6134,
...
},
"brand": {
"id": 143,
...
},
"remarks": "test",
"printed_date": null,
"has_secure_workflow": false,
"static_impositions": 0,
"designer": null,
"external_id": "tk_001",
"is_fingerprint_trained": false,
"substrate": {
"id": 74,
...
},
"template": 105,
"template_image": null,
"is_hybrid": false,
"is_static_print": false,
"is_fp_serialized": false,
"url_prefix": "HTTPS://QR1.CH/Q/",
"extended_id_style": "legacy"
}

Important fields

  • state: changes from "new" to "ready to print" or "completed"
  • codegen_status: shows the code-generation status in a numerical way. Goes from "6" to "4" to indicate generation has completed.
  • codegen_file: the link to the file containing the generated codes.
  • activate_on_complete: determines the code-status after the workorder has been printed. Either codes stay inactive (activation_status: 0) or are activated (activation_status: 1)