Creating 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.

Workorders can be of 2 types and are created through pre-defined templates.

1. 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_view
• workorder_create
• workorder_edit
• workorder_cancel
• 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 - Overview

Obtaining SID codes from the scantrust system requires 3 steps:

1. Use the create workorder endpoint with a SID template 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).

Generating Secure Scantrust Identifiers (SSC) workorders - Overview

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 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 Workorder

GET /api/v2/workorders/templates/

Get all available workorder templates and their attributes. The ID field of the template will later serve as the input for the workorder create POST call.

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-from-template/

Attribute	Required?	Description
template	required	integer, retrieved from id in the above GET template request
quantity	required	integer, number of codes to be generated
reference	optional	string, internal reference, must be unique for the company. Generated by the API if not set.
printing_partner	optional*	integer, company ID of the Printing Partner. Required for SSC workorders that have no partner set in template.
product	optional	integer/string, Product ID/SKU, assigns codes to given product on generation.
due_date	optional	date, 'YYYY-MM-dd' Due date (informational for printing partner)
total_impressions	optional	integer, only applicable for static workorders, amount of impressions per static code.

Example JSON payload

{
  "template": "1",
  "quantity": "10",
  "reference": "Workorder for product P2", //Optional (generated if not set)
  "printing_partner": 3, //Optional
  "product": "P2" //optional
}

Response (201): Created

{
    "id": 24,
    "company": {
        "id": 2,
        ...
    },
    "printing_partner": {
        "id": 3,
        ...
    },
    "equipment": {
        "id": 1,
        ...
    },
    "state": "new",
    "due_date": null,
    "reference": "Workorder for product P2",
    "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": "",
    "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

Only applies to SSC workorders!

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)

Legacy workorder endpoints

Previously, the API required all template fields to be copied within the relevant create endpoints. You can find the legacy documentation below. It is highly recommended to migrate to above create from template method.

Legacy SID workorder creation documentation

Legacy SSC workorder creation documentation