Serialization

The “serialization-service” provides methods for creating SGTIN and LGTIN

Requirements

  1. User's session must contain field “current_participant”.
{
  "id": "urn:authenticateit:user:email:my@gmail.com",
  "name": "ivan",
  "roles": [
    "user"
  ],
  "ticket": "7b758d11-a597-44ae-8ab4-dd3cf864e20f",
  "current_participant": {
    "id": "urn:epc:sgln:0614141.12345.1"
  }
}
  1. This participant must be presented in doc_storage with “type” field equals to “outsource” or “manufacturer”. Document also must provide a list of company prefixes
{
  "_id": "urn:epc:sgln:0614141.12345.1",
  "type": "participant",
  "participant_type": [
    "manufacturer"
  ],
  "company_prefix": [
    "0614141"
  ]
}

Create SGTINs or LGTINs with requested paremeters

Start serialization process with the given parameters. Responds with JSON object containing serialization task id. The returned identifier may be used to request task status.

GS1 application identifiers (see here for additional information) may be included in the generated SGTINs or LGTINs. The following AIs are supported:

  • Date AIs 11–17. Data for these AIs is a 6 digits string representing date in YYMMDD format. E.g., June 11, 2019 will be represented as 190611.
  • Measurement AIs 310–369. Data for these AIs is a 6 digits string representing the measurement. The first digit in the data indicates the number of decimal places. The rest of the digits represent the measured value. E.g., net weight of 1.23 kg will be represented as AI 310 with data 200123.
  • Additional product identification AI 240. Data for this AI is a string up to 30 characters long. The following characters and character ranges are allowed in the data: !–", %–/, 0–9, A–Z, _ and a–z.
  • Company internal information AIs 91–99. Data for these AIs is a string up to 90 characters long. The same characters are allowed in the data as in AI 240 (see above).
POST /serialization-service/serialize
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
gtin base gtin “00614141791304”
format serialization format “gs1” or “epc”
type serialization type “sgtin” or “lgtin”
count requested number integer
data_type "numeric" or "alphanumeric"
length integer from 1 to 20
sequence sequence option “ordered” or “random”
owner owner of serialized gtin not required
settings export settings not required, if not presented - use default
labels_as_titles labels as titles in csv header “yes” or “no”, default “no”
code gs1 code in csv “yes” or “no”, default “yes”
owner owner id in csv “yes” or “no”, default “no”
delimiter delimiter in csv default "|"
name export product name in csv “yes” or “no”, default “no”
ai GS1 AI to be included in SGTIN or LGTIN List of application identifiers.
participant Participant identifier Assing child supply chain participant as SGTIN owner
location Business location identifier Assing business location owner as SGTIN owner
source Additional source in SGTIN or LGTIN doc single source object
sources Additional sources in SGTIN or LGTIN doc list of source objects
Example Request
{
  "gtin": "02933451000009",
  "name": "Butter",
  "type": "lgtin",
  "format": "epc",
  "count": 2,
  "ai": [
    "12180608"
  ],
  "sequence": "random",
  "length": 12,
  "data_type": "alphanumeric",
  "source": {
    "data": [
      {
        "text": {
          "title": "44",
          "text": "444444"
        }
      },
      {
        "text": {
          "title": "55",
          "text": "555555"
        }
      }
    ],
    "conditions": {
      "country": "036",
      "language": "zh"
    }
  }
}

{
  "gtin": "02933451000009",
  "name": "Shoes",
  "type": "sgtin",
  "format": "gs1",
  "count": 3,
  "ai": [
    "13180609",
    "15180602",
    "16180609",
    "3110000033",
    "17180602"
  ],
  "sequence": "random",
  "length": 12,
  "data_type": "numeric",
  "sources": [
    {
      "conditions": {},
      "data": [
        {
          "text": {
            "title": "text",
            "text": "Update SGTIN widget",
            "markdown": false
          }
        },
        {
          "link": {
            "text": "Link",
            "url": "http://www.facebook.com/shping"
          }
        }
      ]
    }
  ]
}
Example Response
{
  "id": "ff79bfae-3713-49ec-8551-2f29bb4d3b72"
}

Get status of serialization

Get status of previously started serialization task.

GET /serialization-service/serialize/:task_id
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
task_id string Serialization task identifier.
Example Response
{
  "progress": 100,
  "status": "started"
}

{
  "status": "done",
  "link": "https://dev-test-cdn.shping.com/2016-12-04T19:44:49Z-b3c59bfa-4f8e-431e-b445-de2417cdffa8.csv"
}

{
  "error": "Serialization not has been started"
}

Get serialization tasks

Returns list of previously started serialization tasks.

Number of returned tasks may be limited with the limit parameter (default valus is 100). Number of tasks may be skipped from the list with the offset parameter (0 by default).

Returned tasks may be filtered by status (either started or done), gtin, name (tasks for GTINs with product name matching this string).

The resulting list may be sorted. Parameter sort_by should be used to specify sorting field (start_time, gtin, name or status). Sorting order may be specified with sort_order parameter (asc for ascending order and desc for descending order).

GET /serialization-service/tasks
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
offset Skip number of tasks from the resulting list.
limit Limite the number of tasks in the resulting list.
from_date Only tasks started after this date.
to_date Only tasks started before this date.
status Only tasks with this status.
gtin Only tasks for the GTIN.
name Only tasks for products matching this name.
sort_by Sort tasks by field.
sort_order Ascending or descending sort order.
Example Response
{
  "id": "task_serialization",
  "serialization_list": [
    {
      "ai": "02",
      "check_digit": "4",
      "company_prefix": "0614141",
      "count": 10,
      "end_time": "2016-12-03T13:00:43Z",
      "epc_header": "urn:epc:id:lgtin:0614141.079130.",
      "gs1_header": "020061414179130410",
      "gtin": "00614141791304",
      "indicator": "0",
      "item_reference": "79130",
      "link": "https://dev-test-cdn.shping.com/2016-12-03T13:00:40Z-6d20f9c0-811b-4829-b899-9512ef4ad356.csv",
      "owner": "urn:epc:sgln:0614141.12345.1",
      "participant": "urn:epc:sgln:0614141.123451",
      "sequence": "random",
      "settings": {
        "code": "no",
        "delimiter": "|",
        "labels_as_titles": "yes",
        "name": "yes",
        "owner": "yes"
      },
      "start_time": "2016-12-03T13:00:40Z",
      "type": "lgtin",
      "user": "urn:epc:sgln:0614141.12345.1"
    },
    {
      "ai": "02",
      "check_digit": "4",
      "company_prefix": "0614141",
      "count": 10,
      "end_time": "2016-12-03T10:18:50Z",
      "epc_header": "urn:epc:id:lgtin:0614141.079130.",
      "gs1_header": "020061414179130410",
      "gtin": "00614141791304",
      "indicator": "0",
      "item_reference": "79130",
      "last_element": "urn:epc:id:lgtin:0614141.079130.0000010030",
      "link": "https://dev-test-cdn.shping.com/2016-12-03T10:18:25Z-6efdca22-e049-4f6d-9faa-ac4b7c739e1f.csv",
      "owner": "urn:epc:sgln:0614141.12345.1",
      "participant": "urn:epc:sgln:0614141.12345.1",
      "sequence": "ordered",
      "settings": {
        "code": "no",
        "delimiter": "|",
        "labels_as_titles": "yes",
        "name": "yes",
        "owner": "yes"
      },
      "start_time": "2016-12-03T10:18:25Z",
      "type": "lgtin",
      "user": "urn:epc:sgln:0614141.12345.1"
    }
  ]
}

Shipping Containers

All endpoints require serialization_admin role for the calling user.

Import SSCCs

Create SSCC documents in the system from provided SSCC codes. Accepts JSON object representation of the import task parameters, starts the task and responds with id of the task. Import description has the following fields:

  • id — a single SSCC or a list of SSCC codes to be imported. SSCCs as GS1 codes and SSCCs in EPC format are accepted.
  • company_prefix — import only SSCCs which have company prefix compatible with the specified prefix. The prefix must be in participant's list of prefixes or participant should have a wildcard (*) prefix *.

Only SSCCs which are not already present will be created. Company prefix of SSCCs should correspond to current participant's company prefixes.

POST /serialization-service/packaging/tasks
Parameters
Name Type Description
authenticateit_identity_ticket header Session ticket
Example Request
{
  "id": [
    "urn:epc:id:sscc:9212345.0000000001",
    "urn:epc:id:sscc:1111111.1111111111",
    "00193423360000001230",
    "00111111111111111118"
  ]
}
Example Response
{
  "id": "d78c69d3-5a64-4fed-bf93-5621be12aece"
}

Generate SSCCs

Generate list of random or serial SSCCs for current participant. Accepts JSON object representation of the generation task parameters, starts the task and responds with id of the task. Generate task description has the following fields:

  • count — positive number of SSCCs to be generated. This parameter is required and has no default value.
  • sequence — either ordered or random. The default value is random.
  • company_prefix — use this company prefix in generated SSCCs. The prefix must be accessible by current participant, or current participant should have a wildcard prefix *. The parameter is optional, first valid company prefix of participant will be used, if unspecified.
  • serial_number — start ordered SSCCs from this serial number. Only applicable for the ordered sequence. Has no default value, must be specified explicitly if sequence is ordered.

In ordered mode, if generated SSCC is already present, next serial number will be tried.

POST /serialization-service/packaging/tasks
Parameters
Name Type Description
authenticateit_identity_ticket header Session ticket
Example Request
{
  "count": 3,
  "sequence": "ordered",
  "company_prefix": "9212345",
  "serial_number": 1
}
Example Response
{
  "id": "344d2f8f-8aeb-4ae2-9cc7-954cbe3231d6"
}

Status of a SSCC Generation Task

Query status of SSCC import/generation task.

Task status representation has the total count of SSCCs to be created, number of already processed SSCCs in the progress field, list of already created SSCCs in the created field and the list of errors.

GET /serialization-service/packaging/tasks/:id
Parameters
Name Type Description
authenticateit_identity_ticket header Session ticket
Example Response
{
  "count": 4,
  "created": [
    "urn:epc:id:sscc:9342336.0000000123"
  ],
  "end_time": "2019-06-11T21:23:03Z",
  "errors": [
    {
      "error_id": "serialization-bad_sscc_prefix",
      "sscc": "00111111111111111118"
    },
    {
      "error_id": "serialization-bad_sscc_prefix",
      "sscc": "urn:epc:id:sscc:1111111.1111111111"
    },
    {
      "error_id": "serialization-sscc_exists",
      "sscc": "urn:epc:id:sscc:9212345.0000000001"
    }
  ],
  "id": "d78c69d3-5a64-4fed-bf93-5621be12aece",
  "progress": 4,
  "start_time": "2019-06-11T21:23:03Z",
  "status": "done"
}

Status of All SSCC Generation Tasks

Get status of all SSCC create/import tasks for the participant. Response has list of tasks. Each entry represents a single task (see Status of a Task endpoint for task representation).

GET /serialization-service/packaging/tasks
Parameters
Name Type Description
authenticateit_identity_ticket header Session ticket
Example Response
{
  "tasks": [
    {
      "company_prefix": "9212345",
      "count": 3,
      "created": [
        "urn:epc:id:sscc:9212345.9191483550",
        "urn:epc:id:sscc:9212345.3714625108",
        "urn:epc:id:sscc:9212345.0912305529"
      ],
      "end_time": "2019-06-11T21:43:22Z",
      "id": "79b35062-8a08-4019-a782-55523c56df8c",
      "progress": 3,
      "sequence": "random",
      "start_time": "2019-06-11T21:43:21Z",
      "status": "done"
    },
    {
      "company_prefix": "9212345",
      "count": 3,
      "created": [
        "urn:epc:id:sscc:9212345.0000000004",
        "urn:epc:id:sscc:9212345.0000000003",
        "urn:epc:id:sscc:9212345.0000000002"
      ],
      "end_time": "2019-06-11T21:35:42Z",
      "id": "344d2f8f-8aeb-4ae2-9cc7-954cbe3231d6",
      "progress": 3,
      "sequence": "ordered",
      "serial_number": 1,
      "start_time": "2019-06-11T21:35:42Z",
      "status": "done"
    },
    {
      "count": 4,
      "created": [
        "urn:epc:id:sscc:9342336.0000000123"
      ],
      "end_time": "2019-06-11T21:23:03Z",
      "errors": [
        {
          "error_id": "serialization-bad_sscc_prefix",
          "sscc": "00111111111111111118"
        },
        {
          "error_id": "serialization-bad_sscc_prefix",
          "sscc": "urn:epc:id:sscc:1111111.1111111111"
        },
        {
          "error_id": "serialization-sscc_exists",
          "sscc": "urn:epc:id:sscc:9212345.0000000001"
        }
      ],
      "id": "d78c69d3-5a64-4fed-bf93-5621be12aece",
      "progress": 4,
      "start_time": "2019-06-11T21:23:03Z",
      "status": "done"
    }
  ]
}

Pack Items into a Container

Endpoint to package existing SGTIN, LGTIN or children SSCC items into a container.

Item identifiers must be provided in items field in request body. Container is identified by SSCC in request URL.

Responds with list of sucessfully packed items and with the list of errors.

POST /serialization-service/packaging/container/:sscc/pack
Parameters
Name Type Description
authenticateit_identity_ticket header Session ticket
sscc string Container identifier to pack into
Example Request
{
  "items": [
    "urn:epc:id:sscc:9212345.0000000001",
    "urn:epc:id:sscc:1111111.1111111111",
    "urn:epc:id:sgtin:652086.0004527.000000000000001"
  ]
}
Example Response
{
  "packed": [
    "urn:epc:id:sscc:9212345.0000000001",
    "urn:epc:id:sgtin:652086.0004527.000000000000001"
  ],
  "errors": [
    {
      "item": "urn:epc:id:sscc:1111111.1111111111",
      "error_id": "serialization-bad_pack_item"
    }
  ]
}

Unpack Container

Endpoint to explicitly mark a container as unpacked. Responds with no content.

POST /serialization-service/packaging/container/:sscc/pack
Parameters
Name Type Description
authenticateit_identity_ticket header Session ticket
sscc string Container to unpack
Example Request
{
}

Query Participant Packaging Settings

Endpoint for system participant to query packaging settings of a serialization admin participant.

Packaging settings consists of container_company_prefix list (participant is allowed to pack items into containers with these prefixes) and item_company_prefix list (participant is allowed to pack items with these prefixes).

GET /serialization-service/packaging/participant/:participant_id/settings
Parameters
Name Type Description
authenticateit_identity_ticket header Session ticket
participant_id string Participant identifier
Example Response
{
  "container_company_prefix": [
    "9212345",
    "9523452"
  ],
  "item_company_prefix": [
    "9212345"
  ]
}

Update Participant Packaging Settings

Endpoint for system participant to update packaging settings of a serialization admin participant. container_company_prefix and item_company_prefix lists may be updated. Responds with the updated settings.

PUT /serialization-service/packaging/participant/:participant_id/settings
Parameters
Name Type Description
authenticateit_identity_ticket header Session ticket
participant_id string Participant identifier
Example Request
{
  "item_company_prefix": [
    "9212345",
    "9523452"
  ]
}
Example Response
{
  "container_company_prefix": [
    "9212345",
    "9523452"
  ],
  "item_company_prefix": [
    "9212345",
    "9523452"
  ]
}

results matching ""

    No results matching ""