Request serial number APIs

Serial number request messages allow manufacturing locations to request serial numbers for their location during production. TraceLink responds to request messages with the serial numbers provisioned for that location.

Serial Number Request

This message uses the Park and Retry functionality. If a prerequisite condition for this message has not been met, TraceLink stops processing the message, returns the message to the queue, and then tries to process the message again every 15 minutes for up to 2 hours.

TraceLink XML

Request

Guidelines

Message type: SNX_REQUEST
Info Exchange display name: Serial Number Request
Map version: TL_XML_SNX_Request_1_0_IB_V2_2

Element					Occurs Length	Type	Description
snx:SNXRequestMessage					[1…1] [-]	-	Required. The XML message root element.
	snx:ControlFileHeader				[1…1] [-]	-	Required. The XML file control header.
		cmn:FileSenderNumber			[1…1] [1/*]	String	Required. The unique identifier for the company sending the message (e.g. 7777776067344).
		cmn:FileReceiverNumber			[1…1] [1/*]	String	Required. The unique identifier for the company receiving the message (e.g. 8888884043588).
		cmn:FileControlNumber			[1…1] [1/*]	String	Required. The unique file identifier assigned by the message sender.
		cmn:FileDate			[1…1] [10/10]	Date	Required. The date the file was generated in YYYY-MM-DD format (e.g. 2023-06-30).
		cmn:FileTime			[1…1] [8/8]	Time	Required. The time the file was generated in HH:MM:SSZ format (e.g. 06:30:32Z).
	snx:MessageBody				[1…1] [-]	-	Required. The body of the XML message.
		cmn:RequestId			[1…1] [1/*]	String	Required. The unique identifier for the serial number request (e.g. 23005287-001). This identifier links the response message to this request.
		cmn:PlantLocationId			[1…1] [1/34]	String	Required. The SGLN of the plant requesting serial numbers, with the urn prefix omitted (e.g. 8888882.02867.0 instead of urn:epc:id:sgln:8888882.02867.0).
		cmn:ReferenceDocuments			[0…1] [-]	-	The business documents associated with the commissioning event.
			cmn:PONumber		[1…1] [1/20]	String	Required. The number of the purchase order (PO) issued by the manufacturer for the lot production (e.g. 1001764).
			cmn:POLine		[1…1] [1/5]	String	Required. The line number for the lot production from the PO issued by the manufacturer (e.g. 001).
			cmn:WorkOrderNumber		[0…1] [0/20]	String	The work order associated with the production of this lot (e.g. 1001764-00).
		cmn:NumberEncoding			[1…1] [1/*]	String	Required. The encoding format type for the requested serial numbers. Valid values: `AI(00)` – A Serial Shipping Container Code (SSCC). cmn:CompanyPrefixObjectKey must be present. `AI(01)+AI(21)` – An item's Global Trade Item Number (GTIN) or National Trade Item Number (NTIN) and serial number. SGTINs are mandatory for serial numbers in target markets that require crypto codes. Either cmn:GTIN-14 or cmn:NTINObjectKey must be present. `CN-EDMC` – A Chinese Electronic Data Monitoring Code. cmn:CNSubtypeObjectKey must be present.
		cmn:RU_CryptoCodeRequest			[0…1] [-]	Boolean	Indicates whether to provide crypto codes for the requested serial numbers, for any country that requires crypto codes (e.g Russia, Kazakhstan): `true` – Provide crypto codes. `false` – (default) Do not provide crypto codes.
		cmn:ObjectIdentifier			[1…1] [-]	-	Required. The identifier associated with the encoding format of the requested serial numbers. Exactly one identifier that corresponds with the value of cmn:NumberEncoding must be present.
			cmn:CompanyPrefixObjectKey		[0…1] [0/*]	String	Conditionally required if cmn:NumberEncoding is set to `AI(00)`. The company identifier used in the Serial Shipping Container Code (SSCC), assigned and administered by GS1 Global (e.g. 0388882).
				@filterValue	[1…1] [1/*]	String	Required. The filter value 0 to 7 which indicates the packaging level of the SSCC.
			cmn:GTIN-14		[0…1] [14/14]	String	Conditionally required if cmn:NumberEncoding is `AI(01)+AI(21)` and cmn:NTINObjectKey is not present. The GTIN-14 for the serial numbers (e.g. 08888882020006).
			cmn:CNSubtypeObjectKey		0…1] [10/10]	String	Conditionally required if cmn:NumberEncoding is set to `CN-EDMC`. The encoding type for the CN-EDMC (e.g. 7022014170).
				@codeLevel	[1…1] [1/*]	Integer	Required. The packaging level associated with the serial number as defined in Product Master Data (e.g. 1).
				@packageRatio	[0…1] [0/*]	String	The packaging ratio as defined in Product Master Data (e.g. 1:48:240).
			cmn:NTINObjectKey		0…1] [0/*]	String	Conditionally required if cmn:NumberEncoding is `AI(01)+AI(21)` and cmn:GTIN-14 is not present. The NTIN for the serial numbers (e.g. 70244882930006).
		cmn:Quantity			[1…1] [1/*]	Integer	Required. The quantity of requested serial numbers.

Example

Copy

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
<?xml version="1.0" encoding="UTF-8"?>
<snx:SNXRequestMessage xmlns:snx="urn:tracelink:mapper:sl:serial_number_exchange"
  xmlns:cmn="urn:tracelink:mapper:sl:commontypes"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <snx:ControlFileHeader>
        <cmn:FileSenderNumber>8779891013658</cmn:FileSenderNumber>
        <cmn:FileReceiverNumber>8888884043588</cmn:FileReceiverNumber>
        <cmn:FileControlNumber>0000000001</cmn:FileControlNumber>
        <cmn:FileDate>2020-06-30</cmn:FileDate>
        <cmn:FileTime>06:30:32Z</cmn:FileTime>
    </snx:ControlFileHeader>
    <snx:MessageBody>
        <cmn:RequestId>20120630083253</cmn:RequestId>
        <cmn:PlantLocationId>9997777.01994.0</cmn:PlantLocationId>
        <cmn:ReferenceDocuments>
            <cmn:PONumber>1001764</cmn:PONumber>
            <cmn:POLine>001</cmn:POLine>
            <cmn:WorkOrderNumber>1001764-00</cmn:WorkOrderNumber>
        </cmn:ReferenceDocuments>
        <cmn:NumberEncoding>AI(01)+AI(21)</cmn:NumberEncoding>
        <cmn:ObjectIdentifier>
            <cmn:GTIN-14>00992326050107</cmn:GTIN-14>
        </cmn:ObjectIdentifier>
        <cmn:Quantity>10</cmn:Quantity>
    </snx:MessageBody>
</snx:SNXRequestMessage>

Errors

Element	Error message	Description
Class 1
cmn:PlantLocationId	PlantLocationId is required !!!	This element must have a value specified.
cmn:PONumber	PONumber is required !!!	This element must have a value specified.
cmn:POLine	POLine is required !!!	This element must have a value specified.
cmn:NumberEncoding	Field NumberEncoding must be populated !!!	This element must have a value specified.
cmn:ObjectIdentifier	Only one choice element may be populated: CompanyPrefixObjectKey or GTIN-14, CNSubtypeObjectKey, NTINObjectKey !!!	Exactly one identifier element must have a value specified.
	Source GTIN-14 or NTINObjectKey must be populated if source NumberEncoding = AI(01)+AI(21) OR SGTIN-96 OR SGTIN-198 !!!	If cmn:NumberEncoding is set to `AI(01)+AI(21)`, then either the GTIN or NTIN for the requested serial numbers must be specified.
	Source CompanyPrefixObjectKey must be populated if source NumberEncoding = AI(00) OR SSCC-96 !!!	If cmn:NumberEncoding is set to `AI(00)`, then the company prefix must be specified.
	Source China encoded number type must be present if source NumberEncoding = CN-EDMC !!!	If cmn:NumberEncoding is set to `CN-EDMC`, then the Chinese encoded number type must be specified.
@filterValue	Source Attribute filterValue must be populated !!!	This element must have a value specified.
@codeLevel	source Attribute codeLevel must be populated !!!	This element must have a value specified.
cmn:Quantity	Field Quantity must be populated !!!	This element must have a value specified.
Class 3
The following error returns for all Class 3 errors: “INTERNALERROR=Internal error from server [server details].” Contact TraceLink Support if this error returns.

Response

Guidelines

Message type: SNX_RESPONSE
Info Exchange display name: Serial Number Response
Map version: TL_XML_SNX_Response_1_0_OB_V2_3

Element					Occurs Length	Type	Description
snx:SNXResponseMessage					[1…1] [-]	-	Required. The XML message root element.
	snx:ControlFileHeader				[1…1] [-]	-	Required. The XML file control header.
		cmn:FileSenderNumber			[1…1] [1/*]	String	Required. The unique identifier for the company sending the message (e.g. 7777776067344).
		cmn:FileReceiverNumber			[1…1] [1/*]	String	Required. The unique identifier for the company sending the message (e.g. 7777776067344).
		cmn:FileControlNumber			[1…1] [1/*]	String	Required. The unique file identifier assigned by the message sender.
		cmn:FileDate			[1…1] [10/10]	Date	Required. The date the file was generated in YYYY-MM-DD format (e.g. 2023-06-30).
		cmn:FileTime			[1…1] [8/8]	Time	Required. The time the file was generated in HH:MM:SSZ format (e.g. 06:30:32Z).
	snx:MessageBody				[1…1] [-]		Required. The body of the XML message.
		cmn:RequestId			[1…1] [1/20]	String	Required. The unique identifier for the serial number request (e.g. 23005287-001). This identifier links this response to the corresponding serial number request message.
		cmn:ReferenceDocuments			[0…1] [-]	-	The business documents associated with the event.
			cmn:PONumber		[1…1] [1/*]	String	Required. The number of the purchase order (PO) issued by the manufacturer for the lot production (e.g. 1001764).
			cmn:POLine		[1…1] [1/*]	String	Required. The line number for the lot production from the PO issued by the manufacturer (e.g. 001).
			cmn:WorkOrderNumber		[0…1] [0/*]	String	The work order associated with the production of this lot (e.g. 1001764-00).
		cmn:NumberEncoding			[1…1] [1/*]	String	Required. The encoding format type for the requested serial numbers. SGTINs are mandatory for serial numbers returned to target markets that require crypto codes. Valid values: `AI(00)` – A Serial Shipping Container Code (SSCC). cmn:CompanyPrefixObjectKey must be present. `AI(01)+AI(21)` – An item's Global Trade Item Number (GTIN) or National Trade Item Number (NTIN) and serial number. Either cmn:GTIN-14 or cmn:NTINObjectKey must be present. `CN-EDMC` – A Chinese Electronic Data Monitoring Code. cmn:CNSubtypeObjectKey must be present.
		cmn:ObjectIdentifier			[1…1] [-]	Choice	Required. The identifier associated with the encoding format of the requested serial numbers. Exactly one of the options must be present depending on the value of cmn:NumberEncoding.
			cmn:CompanyPrefixObjectKey		[0…1] [0/*]	String	Conditionally required if cmn:NumberEncoding is set to `AI(00)`. The company identifier used in the Serial Shipping Container Code (SSCC), assigned and administered by GS1 Global (e.g. 0388882).
				@filterValue	[1…1] [1/*]	String	Required. The filter value 0 to 7 which indicates the packaging level of the SSCC.
			cmn:GTIN-14		[0…1] [14/14]	String	Conditionally required if cmn:NumberEncoding is `AI(01)+AI(21)` and cmn:NTINObjectKey is not present. The GTIN-14 for the serial numbers (e.g. 08888882020006).
			cmn:CN-SubtypeObjectKey		[0…1] [10/10]	String	Conditionally required if cmn:NumberEncoding is set to `CN-EDMC`. The encoding type for the CN-EDMC (e.g. 7022014170).
				@codeLevel	[1…1] [1/*]	Integer	Required. The packaging level associated with the serial number as defined in Product Master Data (e.g. 3).
				@packageRatio	[0…1] [0/*]	String	The packaging ratio as defined in Product Master Data (e.g. 1:48:240).
			cmn:NTINObjectKey		[0…1] [0/*]	String	Conditionally required if cmn:NumberEncoding is `AI(01)+AI(21)` and GTIN-14 is not present. The NTIN for the serial numbers (e.g. 70244882930006).
		cmn:Quantity			[1…1] [1/*]	Integer	Required. The quantity of requested serial numbers.
		@choice			[1…1] [-]	Choice	Required. Exactly one of the following choice elements will be present in a response message: cmn:SerialNumberRange cmn:SerialNumberList cmn:ErrorMessage Owners configure whether to receive a range or a list of serial numbers for a packaging code in the corresponding Serial Number Manager template.
		cmn:SerialNumberRange			[0…1] [-]	-	The range of serial numbers returned from Serial Number Manager in the response.
			cmn:StartingNumber		[1…1] [1/*]	String	Required. The first serial number in the returned range. Express values in the GS1 Application Identifier format without parentheses for the AI keys. Examples: AI(01)(21): 010030069422066221100000127801 AI(00): 00003006910000010006 CN-EDMC: 88102321100002005943
			cmn:EndingNumber		[1…1] [1/*]	String	Required. The last serial number in the returned range. Express values in the GS1 Application Identifier format without parentheses for the AI keys. Examples: AI(01)(21): 010030069422066221100000127801 AI(00): 00003006910000010006 CN-EDMC: 88102321100002005943
		cmn:SerialNumberList			[0…1] [-]	-	The list of serial numbers returned from Serial Number Manager.
			@isRandom		[0…1] [0/*]	Boolean	Indicates whether the returned serial numbers are sequential or random: `true` – The list is random. `false` – (default) The list is sequential.
			cmn:SerialNumber		[1…] [1/]	String	Required. A specific serial number in the list. Express values in the GS1 Application Identifier format without parentheses for the AI keys. Examples: AI(01)(21): 010030069422066221100000127801 AI(00): 00003006910000010006 CN-EDMC: 88102321100002005943
				@cryptoKey	[0…1] [4/4]	String	Conditionally required for serial numbers with target markets that require crypto codes. The crypto key value retrieved from the crypto codes app, denoted with the AI(91) key (e.g. 911234).
				@cryptoCode	[0…1] [0/88]	String	Conditionally required for serial numbers with target markets that require crypto codes. The crypto code value retrieved from the crypto codes app, denoted with the AI(92) key (e.g. 92Ausib'LCfH2fbOoXL3yU77gRBOsnhdkl<RGjZvl7g>0&amp). TraceLink uses the following escape sequences for the corresponding XML special characters: " instead of quotation marks (") & instead of ampersands (&) ' instead of apostrophes (') < instead of less than symbols (<) > instead of greater than symbols (>)
				@cryptoAcquisitionDate	[0…1] [0/*]	Date	The date that the crypto key and crypto code are retrieved from the crypto codes app (e.g. 2023-06-01).
		cmn:ErrorMessage			[0…1] [-]	-	The error returned by Serial Number Manager when the serial number request is denied.
			cmn:ErrorCode		[0…1] [-]	String	The error code returned by Serial Number Manager.
			cmn:ErrorDescription		[1…1] [-]	String	Required. The error description returned by Serial Number Manager (e.g. Unable to provision numbers). See the errors table for specific error messages.

Examples

Without crypto codes:

Copy

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
<?xml version="1.0" encoding="UTF-8"?>
<snx:SNXResponseMessage xmlns:snx="urn:tracelink:mapper:sl:serial_number_exchange" xmlns:cmn="urn:tracelink:mapper:sl:commontypes"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> xmlns:cmn="urn:tracelink:mapper:sl:commontypes" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <snx:ControlFileHeader>
        <cmn:FileSenderNumber>8888884043588</cmn:FileSenderNumber>
        <cmn:FileReceiverNumber>8779891013658</cmn:FileReceiverNumber>
        <cmn:FileControlNumber>D000000032</cmn:FileControlNumber>
        <cmn:FileDate>2020-06-30</cmn:FileDate>
        <cmn:FileTime>06:32:34Z</cmn:FileTime>
    </snx:ControlFileHeader>
    <snx:MessageBody>
        <cmn:RequestId>202006300630304</cmn:RequestId>
        <cmn:ReferenceDocuments>
            <cmn:PONumber>1001764</cmn:PONumber>
            <cmn:POLine>001</cmn:POLine>
            <cmn:WorkOrderNumber>1001764-00</cmn:WorkOrderNumber>
        </cmn:ReferenceDocuments>
        <cmn:NumberEncoding>SSCC-96</cmn:NumberEncoding>
        <cmn:ObjectIdentifier>
            <cmn:CompanyPrefixObjectKey filterValue="0">0388882</cmn:CompanyPrefixObjectKey>
        </cmn:ObjectIdentifier>
        <cmn:Quantity>10</cmn:Quantity>
        <cmn:SerialNumberRange>
            <cmn:StartingNumber>003888820001000011</cmn:StartingNumber>
            <cmn:EndingNumber>003888820001000110</cmn:EndingNumber>
        </cmn:SerialNumberRange>
    </snx:MessageBody>
</snx:SNXResponseMessage>

With crypto codes:

Copy

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
<?xml version="1.0" encoding="UTF-8"?>
<snx:SNXResponseMessage xmlns:snx="urn:tracelink:mapper:sl:serial_number_exchange" xmlns:cmn="urn:tracelink:mapper:sl:commontypes">
    <snx:ControlFileHeader>
        <cmn:FileSenderNumber>8888884043588</cmn:FileSenderNumber>
        <cmn:FileReceiverNumber>8779891013658</cmn:FileReceiverNumber>
        <cmn:FileControlNumber>D000000032</cmn:FileControlNumber>
        <cmn:FileDate>2020-06-30</cmn:FileDate>
        <cmn:FileTime>06:32:32Z</cmn:FileTime>
    </snx:ControlFileHeader>
    <snx:MessageBody>
        <cmn:RequestId>20200630083253</cmn:RequestId>
        <cmn:ReferenceDocuments>
            <cmn:PONumber>1001764</cmn:PONumber>
            <cmn:POLine>001</cmn:POLine>
            <cmn:WorkOrderNumber>1001764-00</cmn:WorkOrderNumber>
        </cmn:ReferenceDocuments>
        <cmn:NumberEncoding>SGTIN-96</cmn:NumberEncoding>
        <cmn:ObjectIdentifier>
            <cmn:NTINObjectKey>80388882930006</cmn:NTINObjectKey>
        </cmn:ObjectIdentifier>
        <cmn:Quantity>10</cmn:Quantity>
        <cmn:SerialNumberList>
            <cmn:SerialNumber cryptoKey="911234" cryptoCode="92Ausib&apos;LCfH2fbOoXL3yU77gRBOsnhdkl&lt;RGjZvl7g&gt;0&amp;">018038888293000621100570239041 cryptoAcquisitionDate="2021-07-13"</cmn:SerialNumber>
        </cmn:SerialNumberList>
    </snx:MessageBody>
</snx:SNXResponseMessage>

Errors

Element	Error message	Description
Class 1
cmn:RequestId	RequestId must be populated !!!	This element must have a value specified.
cmn:PONumber	PONumber is required !!!	This element must have a value specified.
cmn:POLine	POLine is required !!!	This element must have a value specified.
cmn:NumberEncoding	Field NumberEncoding must be populated !!!	This element must have a value specified.
cmn:ObjectIdentifier	Only one choice element may be populated: CompanyPrefixObjectKey or GTIN-14, CNSubtypeObjectKey, NTINObjectKey !!!	Exactly one choice element must have a value specified.
	Source GTIN-14 or NTINObjectKey must be populated if source NumberEncoding = AI(01)+AI(21) OR SGTIN-96 OR SGTIN-198 !!!	If cmn:NumberEncoding is set to `AI(01)+AI(21)`, then either the GTIN or NTIN for the requested serial numbers must be specified. `SGTIN-96` and `SGTIN-198` are no longer valid values for cmn:NumberEncoding.
	Source CompanyPrefixObjectKey must be populated if source NumberEncoding = AI(00) OR SSCC-96 !!!	If cmn:NumberEncoding is set to `AI(00)`, then the company prefix must be specified. `SSCC-96` is no longer a valid value for cmn:NumberEncoding.
	Source China encoded number type must be present if source NumberEncoding = CN-EDMC !!!	If cmn:NumberEncoding is set to `CN-EDMC`, then the Chinese encoded number type must be specified.
cmn:CompanyPrefixObjectKey \| @filterValue	Source Attribute filterValue must be populated !!!	This element must have a value specified.
@codeLevel	Source Attribute codeLevel must be populated !!!	This element must have a value specified.
cmn:Quantity	Quantity must be populated !!!	This element must have a value specified.
cmn:SerialNumberRange	Only one choice element may be populated: SerialNumberRange or SerialNumberList or ErrorMessage !!!	Exactly one choice element must have a value specified.
cmn:SerialNumberList
cmn:ErrorMessage
Class 3
The following is thrown for all Class 3 errors: “INTERNALERROR=Internal error from server [server details].” Please contact Support if this error is encountered.

TraceLink SOAP

Request

Companies can request up to 500,000 serial numbers in a SOAP API.

Guidelines

Element					Type	Description
soapenv:Envelope					-	Required. The SOAP message envelope.
	soapenv:Header				-	Required. Not used.
	soapenv:Body				-	Required. The SOAP message body.
		urn:serialNumbersRequest			-	Required. The request body.
			SendingSystem		String	Required. The unique identifier for the company requesting the serial numbers (e.g. 7777776067344). This value is repeated in the response as the receiving system.
			ReceivingSystem		String	Required. The unique identifier for the company responding with the serial numbers (e.g. 8888884043588). This value is repeated in the response as the sending system.
			IdType		String	The type of serial numbers requested. Valid values: `CN_SER` – Chinese Electronic Data Monitoring Code (CN-EDMC) serial numbers. `GS1_SER` – SGTIN or SSCC serial numbers.
			EncodingType		String	Required. The encoding type of requested serial numbers. Valid values: `CN_EDMC` – Chinese serial numbers in CN-EDMC format. `SGTIN` – GTIN-14 or NTIN numbers in AI(01)+(21) format. `SSCC` – SSCCs in AI(00) format.
			Size		Integer	Required. The quantity of serial numbers requested (e.g. 100000). The maximum value is 500,000.
			ObjectKey		-	Required. The type and identifier values for the requested serial numbers.
				Name	String	Required. The type of serial numbers requested. This value determines which information ObjectKey \| Value must contain. Valid values: `CN_SYBTYPE_LEVEL_RATIO` – The China subtype code, code level, and packaging ratio. `COMPANY_PREFIX` – A company identifier used in a Serial Shipping Container Code (SSCC), assigned and administered by GS1 Global. `GTIN-14` – A 14-digit Global Trade Identification Number. `NTIN` – A 14-digit National Trade Item Number.
				Value	String	Required. The corresponding identifier value or values that correspond with the requested serial number type (e.g. the GTIN-14 identifier). This element must match the following format for CN-EDMC and SSCC serial number requests. Valid formats: CN-EDMCs (Name must be set to `CN_SUBTYPE_LEVEL_RATIO`): Format: [Subtype Code]\|[Code Level]\|[Packaging Ratio (optional)] Example: 1008721001\|1\|1:5:50 SSCCs (Name must be set to `COMPANY_PREFIX`): Format: [Company Prefix]\|[Logistic Unit Indicator] Example: 088202\|0
			RequestRandomizedNumbers		String	Not used.
			ReferenceDocuments		-	The business documents associated with the commissioning event.
				PONumber	String	The number of the purchase order (PO) issued by the manufacturer for the lot production (e.g. 1001764).
				POLine	String	The line number for the lot production from the PO issued by the manufacturer (e.g. 001).
				WorkOrderNumber	String	The work order associated with the production of this lot (e.g. 1001764-00).
				ReferenceId	String	The internal business identifier associated with the production of this lot (e.g. A100352).
			SyncRequest		Boolean	Indicates whether to process the message synchronously: `true` – Enable synchronous processing. `false` – (default) Enable asynchronous processing. Recommended if requesting more than 100,000 serial numbers to avoid an error.

Examples

GTIN request:

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:tracelink:soap">
   <soapenv:Header/>
   <soapenv:Body>
      <urn:serialNumbersRequest>
         <SendingSystem>LineSys11</SendingSystem>
         <ReceivingSystem>0060354701201</ReceivingSystem>
         <IdType>GS1_SER</IdType>
         <EncodingType>SGTIN</EncodingType>
         <Size>10</Size>
         <ObjectKey>
            <Name>GTIN</Name>
            <Value>50882025010333</Value>
         </ObjectKey>
      </urn:serialNumbersRequest>
   </soapenv:Body>
</soapenv:Envelope>

CN-EDMC request:

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:tracelink:soap">
   <soapenv:Header/>
   <soapenv:Body>
      <urn:serialNumbersRequest>
         <SendingSystem>LineSys11</SendingSystem>
         <ReceivingSystem>0060354701201</ReceivingSystem>
        <IdType>CN_SER</IdType>
         <EncodingType>CN_EDMC</EncodingType>
         <Size>10</Size>
         <ObjectKey>
            <Name>CN_SUBTYPE_LEVEL_RATIO</Name>
            <Value>1008721001|3|1:5:50></Value>
         </ObjectKey>
     <ReferenceDocuments>
        <PONumber>10043</PONumber>
        <POLine>2</POLine>
        <WorkOrderNumber>10043-001<WorkOrderNumber>
        <ReferenceIdentifier>917902db-1307-4182-ad3d-29eca2d699ae</ReferenceIdentifier>
     </ReferenceDocuments>    
      </urn:serialNumbersRequest>
   </soapenv:Body>
</soapenv:Envelope>

Response

Guidelines

Element						Type	Description
S:Envelope						-	Required. The envelope of the SOAP message.
	S:Body					-	Required. The body of the SOAP message.
		ns2:serialNumbersRequestResponse				-	Required. The response body. With the exception of RfidException, elements are omitted if an error response is returned. Owners configure whether to receive a range or a list of serial numbers for a packaging code in the corresponding Serial Number template. Exactly one of the following elements will be included in each response: Interval RandomizedNumberList RfidException
			ReceivingSystem			String	The unique identifier for the company requesting the serial numbers (e.g. 7777776067344).
			SendingSystem			String	The unique identifier for the company responding with the serial numbers (e.g. 8888884043588).
			ActionCode			String	The value `C` is always returned. This value can be ignored.
			EncodingType			String	Required. The encoding type of returned serial numbers, as provided in the request. Valid values: `CN_EDMC` – Chinese serial numbers in CN-EDMC format. `SGTIN` – GTIN-14 or NTIN numbers in AI(01)+(21) format. `SSCC` – SSCCs in AI(00) format.
			IdType			String	The type of serial numbers returned as provided in the request. Valid values: `CN_SER` – Chinese Electronic Data Monitoring Code (CN-EDMC) serial numbers. `GS1_SER` – SGTIN or SSCC serial numbers.
			Interval			-	The range of returned serial numbers.
				NumberFrom		String	Required. The starting value in the serial number range. Express values in the GS1 Application Identifier format without parentheses for the AI keys. Examples: AI(01)(21): 010030069422066221100000127801 AI(00): 00003006910000010006 CN-EDMC: 88102321100002005943
				NumberTo		String	Required. The ending value in the serial number range.Express values in the GS1 Application Identifier format without parentheses for the AI keys. Examples: AI(01)(21): 010030069422066221100000127801 AI(00): 00003006910000010006 CN-EDMC: 88102321100002005943
			ObjectKey			-	Required. The type and identifier values for the requested serial numbers.
				Name		String	Required. The type of serial numbers returned as provided in the request. This value identifies which information ObjectKey \| Value must contain. Valid values: `CN-RESCODE` – A 5-digit China packaging code. `CN_SYBTYPE_LEVEL_RATIO` – The China subtype code, code level, and packaging ratio. `COMPANY_PREFIX` – A company identifier used in a Serial Shipping Container Code (SSCC), assigned and administered by GS1 Global. `GTIN-14` – A 14-digit Global Trade Identification Number. `NTIN` – A 14-digit National Trade Item Number.
				Value		String	Required. The corresponding identifier value or values that correspond with the requested serial number type. This element must match the following format for CN-EDMC and SSCC serial number responses. Valid formats: CN-EDMCs (type must be set to `CN_SUBTYPE_LEVEL_RATIO`): Format: [Subtype Code] \| [Code Level] \| [Package Ratio (optional)] Example: 1008721001\|1\|1:5:50 SSCCs (type must be set to `COMPANY_PREFIX`): Format: [Company Prefix] \| [Logistic Unit Indicator] Example: 088202\|0
			ReferenceDocuments			-	The business documents associated with the commissioning event.
				PONumber		String	The number of the purchase order (PO) issued by the manufacturer for the lot production (e.g. 1001764).
				POLine		String	The line number for the lot production from the PO issued by the manufacturer (e.g. 001).
				WorkOrderNumber		String	The work order associated with the production of this lot (e.g. 1001764-00).
				ReferenceIdentifier		String	The internal business identifier associated with the production of this lot (e.g. A100352).
			RandomizedNumberList			-	The randomized list of returned serial numbers.
				SerialNo		String	Required. The returned serial number. Express values in the GS1 Application Identifier format without parentheses for the AI keys. Examples: AI(01)(21): 010030069422066221100000127801 AI(00): 00003006910000010006 CN-EDMC: 88102321100002005943
					cryptoKey	String	Conditionally required for serial numbers returned to target markets that require crypto codes. The crypto key value retrieved from the crypto codes app, denoted with the AI(91) key (e.g. 911234).
					cryptoCode	String	Conditionally required for serial numbers returned to target markets that require crypto codes. The crypto code value retrieved from the crypto codes app denoted with the AI(92) key (e.g. 92Ausib'LCfH2fbOoXL3yU77gRBOsnhdkl<RGjZvl7g>0&amp). TraceLink uses the following escape sequences for the corresponding XML special characters: " instead of quotation marks (") & instead of ampersands (&) ' instead of apostrophes (') < instead of less than symbols (<) > instead of greater than symbols (>)
					cryptoAcquisitionDate	Date	The date that the crypto key and crypto code are retrieved from the crypto codes app (e.g. 2023-06-01).
			RfidException			-	The error returned by Serial Number Manager when the serial number request is denied. See the errors table for guidance.
				errorCode		String	The error code returned by Serial Number Manager.
				errorMessage		String	Required. The error message description returned from Serial Number Manager (e.g. NTIN identifier [NTIN Value] is not in the permitted serial number request list).

Example

Copy

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
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:serialNumbersRequestResponse xmlns:ns2="urn:tracelink:soap">
         <SNResponse>
            <ReceivingSystem>LineSys11</ReceivingSystem>
            <SendingSystem>0060354701201</SendingSystem>
            <ActionCode>C</ActionCode>
            <EncodingType>SGTIN</EncodingType>
            <IDType>GS1_SER</IDType>
            <ObjectKey>
               <Name>GTIN</Name>
                <Value>00882025010338</Value>
            </ObjectKey>        
            <RandomizedNumberList>
                <SerialNo>010088202501033821100011946933</SerialNo>
                <SerialNo>010088202501033821100015310495</SerialNo>
                <SerialNo>010088202501033821100018139350</SerialNo>
                <SerialNo>010088202501033821100012121992</SerialNo>
                <SerialNo>010088202501033821100016483276</SerialNo>
                <SerialNo>010088202501033821100012414042</SerialNo>
                <SerialNo>010088202501033821100016102891</SerialNo>
                <SerialNo>010088202501033821100013578725</SerialNo>
                <SerialNo>010088202501033821100018119185</SerialNo>
                <SerialNo>010088202501033821100011320392</SerialNo>
            </RandomizedNumberList>
         </SNResponse>
      </ns2:serialNumbersRequestResponse>
   </S:Body>
</S:Envelope>

Errors

Error code	Error message	Description
500	CN-Subtype identifier [CN-EDMC Subtype] is not in the permitted serial number request list.	This packaging code value does not exist or is not assigned to the location.
500	GTIN-14 identifier [GTIN-14] is not in the permitted serial number request list.	This packaging code value does not exist or is not assigned to the location.
500	NTIN identifier [NTIN] is not in the permitted serial number request list.	This packaging code value does not exist or is not assigned to the location.
500	Encoding type requested is not correct type for product [identifier type] [identifier] and service [receiving company Service ID].	The encoding type in the request is not the same encoding type of the template for that product.
500	Filter value [filter value] or Company Prefix [company prefix] is not valid.	The SSCC values are not properly configured with Product Master Data.
500	Non-numeric value specified for code level: [code level].	The code level for requested CN-EDMCs must be a digit.
500	More than one Code Level found for [CN-EDMC identifier value]. PackagingRatio must be specified to disambiguate request.	The packaging ratio must be specified for this subtype and code level.
500	THROUGHPUT_EXCEEDED:Throughput has been exceeded. Please retry your message again. If this error continues, consider reducing the size of your operation or contact TraceLink support.	The system could not process the request at this time. Try again later.
500	Quantity requested for [identifier type] [identifier] exceeds the maximum quantity allowed: 500000	The size element must be between 0 and 500000.
500	Request for too few serial numbers: quantity [requested quantity] must be greater than 0.	The size element must be between 0 and 500000.
500	Serial Number Manager does not have serial numbers to satisfy the serial number request for [identifier]. This template has serial numbers associated with a production order. The serial number request must include a PO Number, Work Order Number, or Reference Identifier to request numbers against the associated production order.	Reference documents must be present to request serial numbers using the serial number template associated with the provided identifiers.
500	Serial Number Manager does not have serial numbers to satisfy the serial number request for [identifier] with [PO Number [PO number]] [and] [WorkOrder [work order number]] [and] [Reference Identifier [reference ID]].	Production identifiers must be present to request serial numbers using the serial number template associated with the provided identifiers. The request exceeds the available serial numbers from this production order pool.
500	Unable to acquire lock on serial number space for [identifier type] [identifier]. Please try again.	Another location is requesting serial numbers for the packaging code at the same time. Try again later.
500	Unable to find service from lookup id: [Service ID].	The SendingSystem or RecievingSystem does not correspond with any identifiers included in the Owner's Serial Number Exchange app configuration.
500	Product ID [identifier type] [identifier] is not valid for products in service [receiving company Service ID].	The packaging code for the requested serial numbers does not exist in Product Master Data or does not have a template assigned to the requesting location.
500	The serial number template is configured to not allow provisioning for [packaging code].	The serial number template associated with the packaging code is not enabled to provision externally.
500	You are not authorized to access this service.	The authentication information provided in the tool used to send and receive this message does not correspond to a user with access to the Owner's Serial Number Exchange app.

Arvato XML

This message can only be used in response to a TraceLink XML request. If the company needs serial numbers for target markets that require crypto codes (e.g. Russia, Kazakhstan), use the TraceLink XML response instead.

Response

Guidelines

Message type: SNX_RESPONSE
Info Exchange display name: Serial Number Response
Map version: Arvato_XML_SNX_Response_1_0_OB_V1_0

Element					Occurs Length	Type	Description
snx:SNXResponseMessage					[1…1] [-]	-	Required. The XML message root element.
	snx:ControlFileHeader				[1…1] [-]	-	Required. The XML file control header.
		cmn:FileSenderNumber			[1…1] [1/10]	String	Required. The unique identifier for the company sending the message (e.g. 7777776067344).
		cmn:FileReceiverNumber			[1…1] [1/10]	String	Required. The unique identifier for the company receiving the message (e.g. 8888884043588).
		cmn:FileControlNumber			[1…1] [1/*]	String	Required. The unique file identifier assigned by the message sender.
		cmn:FileDate			[1…1] [10/10]	Date	Required. The date the file was generated in YYYY-MM-DD format (e.g. 2023-06-30).
		cmn:FileTime			[1…1] [8/8]	Time	Required. The time the file was generated in HH:MM:SSZ format (e.g. 06:30:32Z).
	snx:MessageBody				[1…1] [-]	-	Required. The body of the XML message.
		cmn:RequestId			[1…1] [1/20]	String	Required. The unique identifier for the serial number request (e.g. 23005287-001). This identifier links this response to the corresponding serial number request message.
		cmn:ReferenceDocuments			[0…1] [-]	-	Not used by TraceLink.
			cmn:PONumber		[1…1] [0/*]	String	Required. The number of the purchase order (PO) issued by the manufacturer for the lot production (e.g. 1001764).
			cmn:POLine		[1…1] [0/*]	String	Required. The line number for the lot production from the PO issued by the manufacturer (e.g. 001).
			cmn:WorkOrderNumber		[0…1] [0/*]	String	The work order associated with the production of this lot (e.g. 1001764-00).
			cmn:ReferenceIdentifier		[0…1] [1/10]	String	The business documents associated with the serial number request.
		cmn:NumberEncoding			[1…1] [0/*]	String	Required. The encoding format type for the requested serial numbers. Valid values: `AI(00)` – A Serial Shipping Container Code (SSCC). cmn:CompanyPrefixObjectKey must be present. `AI(01)+AI(21)` – An item's Global Trade Item Number (GTIN) or National Trade Item Number (NTIN) and serial number. Either cmn:GTIN-14 or cmn:NTINObjectKey must be present. `CN-EDMC` – A Chinese Electronic Data Monitoring Code. cmn:CNSubtypeObjectKey must be present.
		cmn:ObjectIdentifier			[1…1] [-]	Choice	Required. The identifier associated with the encoding format of the requested serial numbers. Exactly one of the options must be present depending on the value of cmn:NumberEncoding.
			cmn:CompanyPrefixObjectKey		[0…1] [0/*]	String	Conditionally required if cmn:NumberEncoding is set to `AI(00)`. The company identifier used in the Serial Shipping Container Code (SSCC), assigned and administered by GS1 Global (e.g. 0388882).
				@filterValue	[1…1] [0/*]	String	Required. The filter value 0 to 7 which indicates the packaging level of the SSCC.
			cmn:GTIN-14		[0…1] [1/14]	String	Conditionally required if cmn:NumberEncoding is `AI(01)+AI(21)` and cmn:NTINObjectKey is not present. The GTIN-14 for the serial numbers (e.g. 08888882020006).
			cmn:CN-SubtypeObjectKey		[0…1] [10/10]	String	Conditionally required if cmn:NumberEncoding is set to `CN-EDMC`. The encoding type for the CN-EDMC (e.g. 7022014170).
				@codeLevel	[1…1] [0/*]	Integer	Required.The packaging level associated with the serial number as defined in Product Master Data (e.g. 3).
				@packageRatio	[0…1] [0/*]	String	The packaging ratio as defined in Product Master Data (e.g. 1:48:240).
			cmn:NTINObjectKey		[0…1] [0/*]	String	Conditionally required if cmn:NumberEncoding is `AI(01)+AI(21)` and GTIN-14 is not present. The NTIN for the serial numbers (e.g. 70244882930006).
		cmn:Quantity			[1…1] [1/*]	Integer	Required. The quantity of requested serial numbers.
		@choice			[1…1] [-]	Choice	Required. Exactly one of the following choice elements will be present in a response message: cmn:SerialNumberRange cmn:SerialNumberList cmn:ErrorMessage Owners configure whether to receive a range or a list of serial numbers for a packaging code in the corresponding Serial Number Manager template.
		cmn:SerialNumberRange			[0…1] [-]	-	The range of serial numbers returned from Serial Number Manager in the response.
			cmn:StartingNumber		[1…1] [1/*]	String	Required. The first serial number in the returned range. Express values in the GS1 Application Identifier format without parentheses for the AI keys. Examples: AI(01)(21): 010030069422066221100000127801 AI(00): 00003006910000010006 CN-EDMC: 88102321100002005943
			cmn:EndingNumber		[1…1] [1/*]	String	Required. The last serial number in the returned range. Express values in the GS1 Application Identifier format without parentheses for the AI keys. Examples: AI(01)(21): 010030069422066221100000127801 AI(00): 00003006910000010006 CN-EDMC: 88102321100002005943
		cmn:SerialNumberList			[0…1] [-]	-	The list of serial numbers returned from Serial Number Manager.
			@isRandom		[0…1] [0/*]	Boolean	Indicates whether the returned serial numbers are sequential or random: `true` – The list is random. `false` – (default) The list is sequential.
			SerialNumber		[1…] [1/]	String	Required. A specific serial number in the list. Express values in the GS1 Application Identifier format without parentheses for the AI keys. Examples: AI(01)(21): 010030069422066221100000127801 AI(00): 00003006910000010006 CN-EDMC: 88102321100002005943
		cmn:ErrorMessage			[0…1] [-]	-	The error returned by Serial Number Manager when the serial number request is denied.
			cmn:ErrorCode		[0…1] [-]	String	The error code returned by Serial Number Manager.
			cmn:ErrorDescription		[1…1] [-]	String	Required. The error description returned by Serial Number Manager (e.g. Unable to provision numbers). See the errors table for specific error messages.

Example

Copy

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
<?xml version="1.0" encoding="UTF-8"?>
<snx:SNXResponseMessage xmlns:snx="urn:tracelink:mapper:sl:serial_number_exchange" xmlns:cmn="urn:tracelink:mapper:sl:commontypes">
    <snx:ControlFileHeader>
        <cmn:FileSenderNumber>8888882028655</cmn:FileSenderNumber>
        <cmn:FileReceiverNumber>8888882028677</cmn:FileReceiverNumber>
        <cmn:FileControlNumber>8900788</cmn:FileControlNumber>
        <cmn:FileDate>2023-08-17</cmn:FileDate>
        <cmn:FileTime>10:30:41</cmn:FileTime>
    </snx:ControlFileHeader>
    <snx:MessageBody>
        <cmn:RequestId>YDUFIFN3UF37Z4QD</cmn:RequestId>
        <cmn:NumberEncoding>AI(01)+AI(21)</cmn:NumberEncoding>
        <cmn:ObjectIdentifier>
            <cmn:GTIN-14>00992326050107</cmn:GTIN-14>
        </cmn:ObjectIdentifier>
        <cmn:Quantity>10</cmn:Quantity>
        <cmn:SerialNumberList isRandom="true">
            <cmn:SerialNumber>015088202501033321100000060001</cmn:SerialNumber>
            <cmn:SerialNumber>015088202501033321100000060002</cmn:SerialNumber>
            <cmn:SerialNumber>015088202501033321100000060003</cmn:SerialNumber>
            <cmn:SerialNumber>015088202501033321100000060004</cmn:SerialNumber>
            <cmn:SerialNumber>015088202501033321100000060005</cmn:SerialNumber>
            <cmn:SerialNumber>015088202501033321100000060006</cmn:SerialNumber>
            <cmn:SerialNumber>015088202501033321100000060007</cmn:SerialNumber>
            <cmn:SerialNumber>015088202501033321100000060008</cmn:SerialNumber>
            <cmn:SerialNumber>015088202501033321100000060009</cmn:SerialNumber>
            <cmn:SerialNumber>015088202501033321100000060010</cmn:SerialNumber>
        </cmn:SerialNumberList>
    </snx:MessageBody>
</snx:SNXResponseMessage>

Errors

Element	Error message	Description
Class 1
cmn:RequestId	RequestId must be populated !!!	This element must have a value specified.
cmn:PONumber	PONumber is required !!!	This element must have a value specified.
cmn:NumberEncoding	Field NumberEncoding must be populated !!!	This element must have a value specified.
cmn:ObjectIdentifier	Only one choice element may be populated: CompanyPrefixObjectKey or GTIN-14, CNSubtypeObjectKey, NTINObjectKey !!!	Exactly one choice element must have a value specified.
	Source GTIN-14 or NTINObjectKey must be populated if source NumberEncoding = AI(01)+AI(21) OR SGTIN-96 OR SGTIN-198 !!!	If cmn:NumberEncoding is set to `AI(01)+AI(21)`, then either the GTIN or NTIN for the requested serial numbers must be specified. `SGTIN-96` and `SGTIN-198` are no longer valid values for cmn:NumberEncoding.
	Source CompanyPrefixObjectKey must be populated if source NumberEncoding = AI(00) OR SSCC-96 !!!	If cmn:NumberEncoding is set to `AI(00)`, then the company prefix must be specified. `SSCC-96` is no longer a valid value for cmn:NumberEncoding.
	Source China encoded number type must be present if source NumberEncoding = CN-EDMC !!!	If cmn:NumberEncoding is set to `CN-EDMC`, then the Chinese encoded number type must be specified.
cmn:CompanyPrefixObjectKey \| @filterValue	Source Attribute filterValue must be populated !!!	This element must have a value specified.
@codeLevel	Source Attribute codeLevel must be populated !!!	This element must have a value specified.
cmn:Quantity	Quantity must be populated !!!	This element must have a value specified.
cmn:SerialNumberRange	Only one choice element may be populated: SerialNumberRange or SerialNumberList or ErrorMessage !!!	Exactly one choice element must have a value specified.
cmn:SerialNumberList
cmn:ErrorMessage
Class 3
The following is thrown for all Class 3 errors: “INTERNALERROR=Internal error from server [server details].” Please contact Support if this error is encountered.