Serial Number Provision API

Before calling the Serial Number Provision API, ensure that:

• The identifiers specified in serviceOwnerIdentifier and partnerIdentifier must exist on the TraceLink Network.

• The identifiers do not need to match the identifiers configured in the Serial Number Exchange subscription.

Users are granted authorization to the Serial Number Provision API through OAuth 2.0 (2-legged) authorization on OPUS. Users must generate an API key and API secret and use these credentials to obtain an OAuth token. The OAuth token must be included in each SNX API request for authentication.

To authorize access to the Serial Number Provision API:

1. Create an Integration Principal or use an existing Integration Principal other than the System Integration in Administration. For instructions, see Configure B2B integrations > Create Integration Principals.

2. Assign the Serialization Operator role to the Integration Principal used for SNX API access. For instructions, see Configure B2B integrations > View and edit Integration Principals.

3. Generate an apiKey and apiSecret in OPUS. For instructions, see the Configure B2B integrations > View and edit Integration Principals > To generate an API key step.
   The apiKey and apiSecret are generated and required to obtain an OAuth access token.
   

4. Use the apiKey and apiSecret to request an OAuth access token:

   POST {{host}}/oauth/token
   

5. Pass the apiKey and apiSecret using:

   Authorization: Basic <base64(apiKey:apiSecret)>
   A OAuth access_token is returned with token_type: Bearer and expires_in. By default, the access token remains valid for 900 seconds (15 minutes).
   Sample response:
   { "access_token": "[access_token]", "token_type": "Bearer", "expires_in": 900 }

6. Call the Serial Number Provision API using the OAuth access token as a Bearer token: Authorization: Bearer <access_token>.
   

7. Include the required HTTP headers listed in the following table.

   Header Name	Values
   Content-Type	The media type for the message. Valid value is application/json.
   dataspace	The dataspace within the environment that the request call is being made. Valid value is default.
   applicationName	The application associated with the request. Valid value is SERIAL_NUMBER_EXCHANGE.
   partnerIdentifier	The identifier of the Partner requesting serial numbers. The identifier must exist on the TraceLink Network. Use a globally unique identifier, such as a GLN. Format: IdentifierType:Value (e.g. GLN:1234567890123).
   serviceOwnerIdentifier	The identifier of the service Owner. The identifier must exist on the TraceLink Network. Use a globally unique identifier, such as an SGLN. Format: IdentifierType:Value (e.g. SGLN:2169080129840).
   businessobjecttypename	serialNumberExchangeOperationObject

   The Serial Number Provision API request is authenticated using the OAuth access token and the requested operation is performed.
   

8. When the OAuth access token expires, call POST {{host}}/oauth/token again using the same apiKey and apiSecret.
   A new OAuth access token is generated. Subsequent Serial Number Provision API request can be performed using the new access token until it expires
   

Endpoint: POST {{host}}/api/graphql

Guidelines

Serial number provision SGTIN request example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
mutation SerialNumberExchangeOperationObjectExecute {
  serialNumberExchangeOperationObject {
    execute(
      input: {
        serialNumberExchangeOperationObject: {
          operationType: "PROVISION"
          additionalProperties: {
            ext_TRACELINK_serialNumberEncodingType: "SGTIN"
            ext_TRACELINK_requestQuantity: 15
            ext_TRACELINK_itemCodeDetails: {
                packagingCodeType: "GTIN_14"
                packagingCodeValue: "06888629590416"
            }
            ext_TRACELINK_referenceDocuments: {
                purchaseOrderNumber: "PO-6"
                purchaseOrderLineNumber: "L-6"
                workOrderNumber: "WO-6"
                referenceIdentifier:"RI-6"
            }
          }
        }
      }) {
      additionalProperties
    }
  }
}

Serial number provision NTIN request example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
mutation SerialNumberExchangeOperationObjectExecute {
  serialNumberExchangeOperationObject {
    execute(
      input: {
        serialNumberExchangeOperationObject: {
          operationType: "PROVISION"
          additionalProperties: {
            ext_TRACELINK_serialNumberEncodingType: "SGTIN"
            ext_TRACELINK_requestQuantity: 10
            ext_TRACELINK_itemCodeDetails: {
                packagingCodeType: "NTIN"
                packagingCodeValue: "35978578874506"
            }
            ext_TRACELINK_referenceDocuments: {
                purchaseOrderNumber: "40XWE"
                purchaseOrderLineNumber: "L-8"
                workOrderNumber: "WO-8"
                referenceIdentifier:"RI-8"
            }
          }
        }
      }) {
      additionalProperties
    }
  }
}

Serial number provision SSCC request example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
mutation SerialNumberExchangeOperationObjectExecute {
  serialNumberExchangeOperationObject {
    execute(
      input: {
        serialNumberExchangeOperationObject: {
          operationType: "PROVISION"
          additionalProperties: {
            ext_TRACELINK_serialNumberEncodingType: "SSCC"
            ext_TRACELINK_requestQuantity: 20
            ext_TRACELINK_itemCodeDetails: {
                packagingCodeType: "SSCC"
                packagingCodeValue: "106161"
                filterValue: "2"
            }
            ext_TRACELINK_referenceDocuments: {
                purchaseOrderNumber: "40XWE"
                purchaseOrderLineNumber: "L-6"
                workOrderNumber: "WO-6"
                referenceIdentifier:"RI-6"
            }
          }
        }
      }) {
      additionalProperties
    }
  }
}

Serial number provision CN-EDMC request example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
mutation SerialNumberExchangeOperationObjectExecute {
  serialNumberExchangeOperationObject {
    execute(
      input: {
        serialNumberExchangeOperationObject: {
          operationType: "PROVISION"
          additionalProperties: {
            ext_TRACELINK_serialNumberEncodingType: "CN-EDMC"
            ext_TRACELINK_requestQuantity: 25
            ext_TRACELINK_itemCodeDetails: {
                packagingCodeType: "CN_RESCODE"
                packagingCodeValue: "1234567892"
                packagingRatio: "1:20:40"
                codeLevel: "1"
            }
            ext_TRACELINK_referenceDocuments: {
                purchaseOrderNumber: "40XWE"
                purchaseOrderLineNumber: "L-8"
                workOrderNumber: "WO-8"
                referenceIdentifier:"RI-8"
            }
          }
        }
      }) {
      additionalProperties
    }
  }
}

Guidelines

Serial number provision Sequential Range Templates response example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "data": {
    "serialNumberExchangeOperationObject": {
      "execute": {
        "additionalProperties": {
          "operationType": "PROVISION",
          "serialNumberEncodingType": "SGTIN",
          "requestQuantity": 1,
          "itemCodeDetails": {
            "packagingCodeType": "NTIN",
            "packagingCodeValue": "33845947477922"
          },
          "provisionedSerialNumberRange": {
            "startingSerialNumber": "013384594747792221200000000006",
            "endingSerialNumber": "013384594747792221200000000006"
          },
          "referenceDocuments": {
            "purchaseOrderNumber": "462MID",
            "purchaseOrderLineNumber": "1",
            "referenceIdentifier": "b573652f-02ed-44e8-b2f0-9855d961ebd5",
            "workOrderNumber": "269374-01"
          },
          "displayIdentifier": "PROV-597"
        }
      }
    }
  },
  "extensions": {
    "licensePlate": "qUumg9-T5k"
  }
}

Serial number provision Sequential List, Imported List, Random List and Auto-replenishment type of Templates response example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
{
  "data": {
    "serialNumberExchangeOperationObject": {
      "execute": {
        "additionalProperties": {
          "operationType": "PROVISION",
          "serialNumberEncodingType": "SSCC",
          "requestQuantity": 10,
          "itemCodeDetails": {
            "packagingCodeType": "SSCC",
            "packagingCodeValue": "338459",
            "filterValue": "1"
          },
          "provisionedSerialNumbers": [
            {
              "serialNumber": "00133845900002000940"
            },
            {
              "serialNumber": "00133845900002000957"
            },
            {
              "serialNumber": "00133845900002000964"
            },
            {
              "serialNumber": "00133845900002000971"
            },
            {
              "serialNumber": "00133845900002000988"
            },
            {
              "serialNumber": "00133845900002000995"
            },
            {
              "serialNumber": "00133845900002001008"
            },
            {
              "serialNumber": "00133845900002001015"
            },
            {
              "serialNumber": "00133845900002001022"
            },
            {
              "serialNumber": "00133845900002001039"
            }
          ],
          "referenceDocuments": {
            "purchaseOrderNumber": "WRE4QI",
            "purchaseOrderLineNumber": "1",
            "referenceIdentifier": "9dc2a280-1b2b-4637-a78e-24bda49a2b44",
            "workOrderNumber": "299917-01"
          },
          "displayIdentifier": "PROV-525"
        }
      }
    }
  },
  "extensions": {
    "licensePlate": "s1A4ra-xc8"
  }
}