Crypto code and serialization APIs

Use the following request and response messages to fetch a certain quantity of serial numbers in the appropriate format when serializing product on the packaging line. The request message specifies the information that is needed, and the response message returns the serial numbers and associated crypto codes, if applicable. The serial numbers can then be added to products on the packaging line.

Serial Number Exchange Request & Response (XML)

Serial Number Exchange Request

Guidelines

Message Type: SNX_REQUEST

Info Exchange Display Name: Serial Number Request

When sending an element in Date or DateTime format, a valid date must be given. "00" is not a valid day or month value and "0000" is not a valid year value.

Data Element					Occurs Length	Type	Description
snx:SNXRequestMessage					[1...1] [-]	-	Required. Root element of message.
	snx:ControlFileHeader				[1...1] [-]	-	Required. XML file control header record.
		cmn:FileSenderNumber			[1...1] [1/10]	String	Required. File sender's company identifier (e.g. 7777776067344).
		cmn:FileReceiverNumber			[1...1] [1/10]	String	Required. File recipient's company identifier (e.g. 8888884043588).
		cmn:FileControlNumber			[1...1] [1/*]	String	Required. Unique file control ID number (e.g. 0000000001).
		cmn:FileDate			[1...1] [10/10]	Date	Required. Date file generated in XML YYYY-MM-DD format (e.g. 2012-06-30).
		cmn:FileTime			[1...1] [8/8]	Time	Required. Time file generated in XML HH:MM:SSZ format (e.g. 06:30:32Z).
	snx:MessageBody				[1...1] [-]	-	Required. XML file control header record.
		cmn:RequestId			[1...1] [1/*]	String	Required. Unique identifier for the serial number request. This is used to link the serial number response from Serial Number Manager back to the originating serial number request (e.g. 20120630083253).
		cmn:PlantLocationId			[1...1] [1/34]	String	Required. The SGLN of the plant that is requesting the serial numbers. This is required by the Serial Number Manager application to track the plant that commissioned the serial numbers. SGLN format is the decimal separated numeric component only, with the urn prefix stripped away (e.g. <company prefix>.<location reference>.<extension> 8888882.02867.0 instead of urn:epc:id:sgln:8888882.02867.0 typically found in EPCIS events).
		cmn:ReferenceDocuments			[0...1] [-]	-	References specific manufacturing orders associated with the serial number request. Indicates that the requested serial numbers will be used for the referenced manufacturing orders.
			cmn:PONumber		[1...1] [1/20]	String	Required. Purchase Order (PO) number associated with serial number request (e.g. 1001764).
			cmn:POLine		[1...1] [1/5]	String	Required. PO line number associated with serial number request (e.g. 001).
			cmn:WorkOrderNumber		[0...1] [1/20]	String	Work Order number associated with serial number request (e.g. 1001764-00).
		cmn:NumberEncoding			[1...1] [0/*]	String	Required. Encoding format for the type of serial numbers that are being requested from the enumeration list. Number encoding is tied to one of the three choice elements below. A specific number encoding is tied to a specific choice data element (e.g. AI(01)+AI(21)). The rule is: If NumberEncoding = AI(01)+AI(21), SGTIN-96, or SGTIN-198 Either Objectdentifier/GTIN-14 or ObjectIdentifier/NTINObjectKey must be populated. If NumberEncoding = AI(00) or SSCC-96 Objectdentifier/CompanyPrefixObjectKey must be populated. If NumberEncoding = CN-EDMC Objectdentifier/CN-SubTypeObjectKey must be populated. All other encodings (AI(8003), GRAI-96, GRAI-170) Either GTIN-14 or CompanyPrefixObjectKey must be populated. See the Encoding enumeration list for valid values.
		cmn:ObjectIdentifier			[1...1] [-]	Choice	Conditionally required to populate with one of the three choice options. The identifier associated with the NumberEncoding for the serial numbers being requested. Only one of the three element options below can be populated: `CompanyPrefixObjectKey` `CN-SubtypeObjectKey` `GTIN14`
			cmn:CompanyPrefixObjectKey		[0...1] [1/*]	String	Conditionally required if NumberEncoding is for SSCC numbers. The company prefix assigned by GS1 for the required SSCC numbers (e.g. 0388882). Values: `AI(01)+AI(21)` `GRAI-96` `GRAI-170 OR AI(8003)` `SGTIN-96` `SGTIN-198`
				@filterValue	[1...1] [-]	String	Required. The Filter Value for the packaging level of the SSCC number that is being requested to indicate if the SSCC is for a pallet, mixed case, etc. See the FilterValue enumeration list for valid values.
			cmn:GTIN-14		[0...1] [14/14]	String	The GTIN-14 for the required SGTIN and AI(01)+AI(21) serial numbers. The GTIN-14 also informs the logistical unit. Used only when NumberEncoding is for SGTIN and AI(01)+AI(21) (e.g. 08888882020006).
			cmn:NTINObjectKey		[1...1] [0/*]	String	Conditionally required if NumberEncoding is for SGTIN and AI(01)+AI(21). The NTIN for the required SGTIN and AI(01)+AI(21) serial numbers (e.g. 70244882930006).
		cmn:Quantity			[1...1] [1/*]	Integer	Required. Quantity of serial numbers requested (e.g. 100000).

Example

<?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>7777776067344</cmn:FileSenderNumber>			
        <cmn:FileReceiverNumber>8888884043588</cmn:FileReceiverNumber>			
        <cmn:FileControlNumber>0000000001</cmn:FileControlNumber>			
        <cmn:FileDate>2012-06-30</cmn:FileDate>			
        <cmn:FileTime>06:30:32Z</cmn:FileTime>			
    </snx:ControlFileHeader>			
    <snx:MessageBody>			
        <cmn:RequestId>20120630083253</cmn:RequestId>			
        <cmn:PlantLocationId>8888882.02867.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>80388882930006</cmn:GTIN-14>			
        </cmn:ObjectIdentifier>			
        <cmn:Quantity>10</cmn:Quantity>			
    </snx:MessageBody>			
</snx:SNXRequestMessage>

Errors

Data Element	Error Message	Description
Class 1
cmn:PlantLocationId	PlantLocationId is required !!!	The error occurs if the source is empty or null.
cmn:PONumber	PONumber is required !!!	The error occurs if the source is empty or null.
cmn:POLine	POLine is required !!!	The error occurs if the source is empty or null.
cmn:NumberEncoding	Field NumberEncoding must be populated !!!	The error occurs if the source is empty or null.
cmn:ObjectIdentifier	Only one choice element may be populated: CompanyPrefixObjectKey or GTIN-14, CNSubtypeObjectKey, NTINObjectKey !!!	The error occurs if the source is empty or null.
	Source GTIN-14 or NTINObjectKey must be populated if source NumberEncoding = AI(01)+AI(21) OR SGTIN-96 OR SGTIN-198 !!!	The error occurs if NumberEncoding = AI(01)+AI(21), SGTIN-96, or SGTIN-198, and both GTIN-14 and NTINObjectKey are empty or null.
	Source CompanyPrefixObjectKey must be populated if source NumberEncoding = AI(00) OR SSCC-96 !!!	The error occurs if NumberEncoding = AI(00) or SSCC-96, and CompanyPrefixObjectKey is empty or null.
	Source China encoded number type must be present if source NumberEncoding = CN-EDMC !!!	The error occurs if NumberEncoding = CN-EDMC, and CN-SubType is empty or null.
	Either source CompanyPrefixObjectKey or GTIN-14 may be populated !!!	The error occurs if both, or neither, of ObjectIdentifier \| GTIN-14 and ObjectIdentifier \| CompanyPrefixObjectKey are populated.
@filterValue	Source Attribute filterValue must be populated !!!	The error occurs if the source is empty or null.
@codeLevel	Source Attribute codeLevel must be populated !!!	The error occurs if the source is empty or null.
cmn:Quantity	Field Quantity must be populated !!!	The error occurs if the source is empty or null.
Class 2
-	-	-
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.

Serial Number Exchange Response

Guidelines

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

Message Type: SNX_RESPONSE

Info Exchange Display Name: Serial Number Response

When sending an element in Date or DateTime format, a valid date must be given. "00" is not a valid day or month value and "0000" is not a valid year value.

Data Element					Occurs Length	Type	Description
snx:SNXResponseMessage					[1...1] [-]	-	Required. Root element of message.
	snx:ControlFileHeader				[1...1] [-]	-	Required. XML file control header record.
		cmn:FileSenderNumber			[1...1] [1/10]	String	Required. File sender's company identifier.
		cmn:FileReceiverNumber			[1...1] [1/10]	String	Required. File recipient's company identifier.
		cmn:FileControlNumber			[1...1] [1/*]	String	Required. Unique file control ID number.
		cmn:FileDate			[1...1] [10/10]	Date	Required. Date file generated in XML YYYY-MM-DD format.
		cmn:FileTime			[1...1] [8/8]	Time	Required. Time file generated in XML HH:MM:SSZ format.
	snx:MessageBody				[1...1] [-]	-	Required. XML file control header record.
		cmn:RequestId			[1...1] [1/20]	String	Required. Unique identifier for the serial number request. This is used to link the serial number response from SNM back to the originating serial number request (e.g. 20120630083253).
		cmn:ReferenceDocuments			[0...1] [-]	-	References specific manufacturing orders associated with the serial number request. Indicates if the requested serial numbers will be used for the referenced manufacturing orders.
			cmn:PONumber		[1...1] [0/*]	String	Required. Purchase Order (PO) number associated with serial number request (e.g. 1001764).
			cmn:POLine		[1...1] [0/*]	String	Required. PO line number associated with serial number request (e.g. 001).
			cmn:WorkOrderNumber		[0...1] [0/*]	String	Work Order number associated with serial number request (e.g. 1001764-00).
			cmn:ReferenceIdentifier		[0...1] [0/*]	String	Other referenced document identifier number.
		cmn:NumberEncoding			[1...1] [0/*]	String	Required. Encoding format for the type of serial numbers that were requested from the enumeration list. Number encoding is tied to one of the three choice elements below. A specific number encoding is tied to a specific choice data element. The rule is:(e.g. AI(01)+AI(21)). If NumberEncoding = AI(01)+AI(21), SGTIN-96, or SGTIN-198 Either Objectdentifier/GTIN-14 or ObjectIdentifier/NTINObjectKey must be populated. If NumberEncoding = AI(00) or SSCC-96 Objectdentifier/CompanyPrefixObjectKey must be populated If NumberEncoding = CN-EDMC Objectdentifier/CN-SubTypeObjectKey must be populated. All other encodings (AI(8003), GRAI-96, or GRAI-170) Either GTIN-14 or CompanyPrefixObjectKey must be populated. See the Encoding enumeration list for valid values.
		cmn:ObjectIdentifier			[1...1] [-]	Choice	Required. The identifier associated with the NumberEncoding for the serial numbers that were requested. This is a choice element. Only one of the four element options below may be populated: CompanyPrefixObjectKey GTIN-14 NTINObjectKey If all or none of the option fields are populated, an error is returned. See the rule in the cell above concerning number encoding options and population fields within this choice element.
			cmn:CompanyPrefixObjectKey		[0...1] [0/*]	String	The company prefix assigned by GS1 for the required SSCC numbers. Used only if NumberEncoding was for SSCC numbers (e.g. 0388882). Values: `AI(00)` `SSCC`
				@filterValue	[1...1] [0/*]	String	Required. The Filter Value for the packaging level of the SSCC number that was requested to indicate if the SSCC is for a pallet, mixed case, etc. This should be an integer with a value from 0 to 7 (e.g. 0). See the FilterValue enumeration list for valid values.
			cmn:GTIN-14		[0...1] [1/14]	String	Conditionally required if CompanyPrefixObjectKey or NTINObjectKey are not populated. The GTIN-14 for the required SGTIN. The GTIN-14 also informs the logistical unit. Values:(e.g. 80388882930006). `AI(00)` `AI(8003)` `GRAI-96` `GRAI-170` `SSCC-96`
			cmn:NTINObjectKey		[0...1] [0/*]	String	Conditionally required if NumberEncoding was for SGTIN and AI(01)+AI(21). The NTIN for the required SGTIN and AI(01)+AI(21) serial numbers (e.g. 70244882930006).
		cmn:Quantity			[1...1] [1/*]	Integer	Required. Quantity of serial numbers requested (e.g. 100000).
		@choice			[1...1] [-]	Choice	Required. Choice group with the response to a serial number request. Returns either a serial number range, serial number list, or an error message if the request was denied. Only one of the following three elements can be populated: ErrorMessage SerialNumberList SerialNumberRange
		cmn:SerialNumberRange			[0...1] [-]	-	Serial number range if a range of serial numbers is returned in the response.
			cmn:StartingNumber		[1...1] [1/*]	String	Required. Serial number range starting value (e.g. 018038888293000621100570239041). This element returns serial numbers in their fully formed format: AI (01) (21) formatted numbers for SGTINs are populated in the fields fully formed as “018038888293000621100000000001” with the “01” and “21” values present. AI (00) formatted numbers for SSCCs are populated in the fields fully formed as "00003888820001000011" with the “00” value present.
			cmn:EndingNumber		[1...1] [1/*]	String	Required. Serial number range ending value (e.g. 018038888293000621100570239049). This element returns serial numbers in their fully formed format: AI (01) (21) formatted numbers for SGTINs are populated in the fields fully formed as “018038888293000621100000000001” with the “01” and “21” values present. AI (00) formatted numbers for SSCCs are populated in the fields fully formed as "00003888820001000011" with the “00” value present.
		cmn:SerialNumberList			[0...1] [-]	-	Serial number list response returned from the serial number manager.
			@isRandom		[0...1] [-]	Boolean	Specifies if returned serial numbers are sequential or random. Optional attribute of the SerialNumber element. If set to true, the list of serial numbers is random and is a sequentially numbered list (e.g. true).
			cmn:SerialNumber		[1...] [1/]	String	Required. Serial number in a list of serial numbers (e.g. 018038888293000621100570239041). This element returns serial numbers in their fully formed format: AI (01) (21) formatted numbers for SGTINs are populated in the fields fully formed as “018038888293000621100000000001” with the “01” and “21” values present. AI (00) formatted numbers for SSCCs are populated in the fields fully formed as "00003888820001000011" with the “00” value present. SGTINs are mandatory for Russia serial numbers.
				@cryptoKey	[0...1] [0/4]	String	Conditionally required for Russia serial numbers. The crypto key value retrieved from the CRPT Order Management Station. This is an alphanumeric value. AI (91) denotes this value in the serial number (e.g. 911234).
				@cryptoCode	[0...1] [0/44]	String	Conditionally required for Russia serial numbers. The crypto code value retrieved from the CRPT Order Management Station. This value can contain alphanumeric values as well as symbols. AI (92) denotes this value in the serial number. The following are valid symbols:(e.g. 92AusibQLCfH2fbOoXL3yU77gRBOsnhdkljRGjZvl7gy0U). ! " – (") % & – (&) ' – (') * + - . / _ , : ; = < – (<) > – (>) ? TraceLink escapes the following special XML characters before sending the Serial Number Exchange Response message: " – (") & – (&) ' – (') < – (<) > – (>)
		cmn:ErrorMessage			[0...1] [-]	-	Error response information returned by SNM when the serial number request is denied.
			cmn:ErrorCode		[0...1] [-]	String	Error code returned by the SNM when the serial number request is denied (e.g. 100).
			cmn:ErrorDescription		[1...1] [-]	String	Required. Error description returned by the SNM when the serial number request is denied (e.g. Invalid GTIN specified in request.).

Example

<?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>7777776067344</cmn:FileReceiverNumber>
        <cmn:FileControlNumber>D000000032</cmn:FileControlNumber>
        <cmn:FileDate>2012-06-30</cmn:FileDate>
        <cmn:FileTime>06:32:32Z</cmn:FileTime>
    </snx:ControlFileHeader>
    <snx:MessageBody>
        <cmn:RequestId>20120630083253</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</cmn:SerialNumber>
        </cmn:SerialNumberList>
    </snx:MessageBody>
</snx:SNXResponseMessage>

Errors

Data Element	Error Message	Description
Class 1
cmn:PONumber	PONumber is required !!!	The error occurs if the source is empty or null.
cmn:POLine	POLine is required !!!	The error occurs if the source is empty or null.
cmn:NumberEncoding	Field NumberEncoding must be populated !!!	The error occurs if the source is empty or null.
cmn:ObjectIdentifier	Only one choice element may be populated: CompanyPrefixObjectKey or GTIN-14, CNSubtypeObjectKey, NTINObjectKey !!!	The error occurs if more than one element is populated.
	Source GTIN-14 or NTINObjectKey must be populated if source NumberEncoding = AI(01)+AI(21) OR SGTIN-96 OR SGTIN-198 !!!	The error occurs if NumberEncoding = AI(01)+AI(21), SGTIN-96, or SGTIN-198, and both GTIN-14 and NTINObjectKey are empty or null.
	Source CompanyPrefixObjectKey must be populated if source NumberEncoding = AI(00) OR SSCC-96 !!!	The error occurs if NumberEncoding = AI(00) or SSCC-96, and CompanyPrefixObjectKey is empty or null.
	Source China encoded number type must be present if source NumberEncoding = CN-EDMC !!!	The error occurs if NumberEncoding = CN-EDMC, and CN-SubType is empty or null.
	Either source CompanyPrefixObjectKey or GTIN-14 may be populated !!!	The error occurs if both, or neither, of ObjectIdentifier \| GTIN-14 and ObjectIdentifier \| CompanyPrefixObjectKey are populated.
cmn:CompanyPrefixObjectKey \| @filterValue	Source Attribute filterValue must be populated !!!	The error occurs if the source is empty or null.
@codeLevel	Source Attribute codeLevel must be populated !!!	The error occurs if the source is empty or null.
cmn:Quantity	Quantity must be populated !!!	The error occurs if the source is empty or null.
@choice	Only one choice element may be populated: SerialNumberRange or SerialNumberList or ErrorMessage !!!	The error occurs if more than one element is populated.
Class 2
-	-	-
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.

Serial Number Exchange Request & Response (SAP ATTP)

Serial Number Exchange Request

Guidelines

Message Type: SNX_REQUEST

Info Exchange Display Name: Serial Number Request

When sending an element in Date or DateTime format, a valid date must be given. "00" is not a valid day or month value and "0000" is not a valid year value.

Data Element			Occurs Length	Type	Description
n1:SNR_REQ_ASYNC_IN			[1...1] [-]	-	Required. Root data element.
	IB_ONLY_EXACT		[0...1] [0/1]	String	Some consumer services cannot handle partial responded serial number requests (internal SAP ATTP buffer does have enough numbers. The request can only be responded partial). This parameter controls whether partial responses are allowed. "`X`": The parameter is set to true. Full quantity of the numbers or nothing. " ": The parameter is blank. Partial quantity is allowed.
	IS_SSCC		[0...1] [-]	-	Conditionally required for SSCC requests. SSCC Information.
		GCP	[1...1] [0/12]	String	Required. The Global company prefix that is assigned to the business partner in the system (e.g. 4298382). This Request Id is required by TraceLink. TraceLink uses this value in the Serial Number Response message to link the request and the response.
		EXT_DIGIT	[1...1] [0/1]	String	Required. In SAP ATTP, the SSCC Extension Digit is the first digit of the serial number (e.g. 2).
	IS_TRADE_ITEM		[0...1] [-]	-	Conditionally required for GTIN requests. SGTIN Information.
		TRADE_ITEM_TYPE	[1...1] [0/10]	String	Required. This parameter defines trade item type. Value = `GTIN` (e.g. GTIN).
		TRADE_ITEM_ID	[1...1] [0/40]	String	Required. Depends on TRADE_ITEM_TYPE value (e.g. 14298382900015). The GTIN-14 for the required SGTIN and AI(01)+AI(21) serial numbers. The GTIN-14 also informs the logistical unit. Use only when NumberEncoding is for SGTIN and AI(01)+AI(21).
	IV_LIST_RANGE		[1...1] [0/1]	String	Required. Defines the type of the serial number response. Values: (e.g. L) `R` – The response contains a range. `L` – The response contains a list. (Default)
	IV_READILY_ENCODE		[1...1] [0/1]	String	Required. In addition to the numbers or range, the request also optionally provides readily encoded data in either a GS1 element string or in EPC URI: 1: Encoding in GS1 Element format. The Serial Number Exchange Response (SAP ATTP) message includes Russia crypto codes if enabled in the serial number template. 2: Encoding in EPC URI format.
	IV_SIZE		[1...1] [1/*]	Integer	Required. Quantity of serial numbers within range request (e.g. 1000).
	IV_SYSTEM		[1...1] [0/60]	String	Required. The system name that has been created for the caller in SAP Advanced Track and Trace for Pharmaceuticals (e.g. 5060173540005\|TRACELINK). TraceLink uses this field to store the Sender and Receiver information separated by a pipe (\|) character.

Example

TraceLink does not provide examples for third-party message format. Please contact SAP for message examples pertaining to this message.

Errors

Data Element	Error Message	Description
Class 1
GCP	Either GCP or TRADE_ITEM_TYPE must be populated, but not both !!!	The error occurs if both GCP and TRADE_ITEM_TYPE are populated.
TRADE_ITEM_TYPE	Either GCP or TRADE_ITEM_TYPE must be populated, but not both !!!	The error occurs if both GCP and TRADE_ITEM_TYPE are populated.
TRADE_ITEM_ID	TRADE_ITEM_ID is required if TRADE_ITEM_TYPE GTIN is present !!!	The error occurs if TRADE_ITEM_TYPE equals "GTIN", but the source is empty or null.
Class 2
GCP	GCP occurs fewer times than its minimum number of occurrences !!!	The error occurs if both GCP or TRADE_ITEM_TYPE are empty or null.
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.

Serial Number Exchange Response

Guidelines

Message Type: SNX_RESPONSE

Info Exchange Display Name: Serial Number Response

When sending an element in Date or DateTime format, a valid date must be given. "00" is not a valid day or month value and "0000" is not a valid year value.

Data Element				Occurs Length	Type	Description
n1:SNR_REQ_ASYNC_OUT				[1...1] [-]	-	Required. Root data element.
	IB_ONLY_EXACT			[0...1] [0/1]	String	Some consumer services cannot handle partial responded serial number requests (internal SAP ATTP buffer does have enough numbers. The request can only be responded partial). This parameter controls whether partial responses are allowed. Values: `X` – The parameter is set to true. Full quantity of the numbers or nothing. " " – The parameter is blank. Partial quantity is allowed.
	IS_RANGE			[1...1] [-]	-	Contains serial number ranges for a range request. In case of a list request, it will be empty.
		NUMBER_FROM		[1...1] [0/40]	String	Required. Lower limit of the range (e.g. 012030001123498721123456789012).
		NUMBER_TO		[1...1] [0/40]	String	Required. Upper limit of the range (e.g. 012030001123498721333456799012).
		TIME_REQ		[1...1] [0/40]	Date	Required. Timestamp of the range request (e.g. 20110815063032).
	IS_SSCC			[0...1] [-]	-	Conditionally required for SSCC requests. SSCC Information.
		GCP		[1...1] [0/12]	String	Required. The Global company prefix that is assigned to the business partner in the system. Returns request parameters (e.g. 030001).
		EXT_DIGIT		[1...1] [0/1]	String	In SAP ATTP, the SSCC Extension Digit is the first digit of the serial number (e.g. 2).
	IS_TRADE_ITEM			[0...1] [-]	-	Conditionally required for GTIN requests. SGTIN Information.
		TRADE_ITEM_TYPE		[1...1] [0/10]	String	Required. This parameter defines trade item type (e.g. GTIN). Value = `GTIN`.
		TRADE_ITEM_ID		[1...1] [0/40]	String	Required. Filled with a GTIN (e.g. 20300011234987).
	IT_SERIALS			[1...1] [-]	-	Contains list of serial numbers in case of list request. It is empty in case of range request.
		item		[0...*] [-]	-	Required.
			NUMBER	[1...1] [0/40]	String	Required. Contains list of serial numbers (e.g. 012030001123498721123456789012).
	IT_ENCODED			[0...1] [-]	-	Conditionally required for Russia serial numbers. Contains list of serial numbers with crypto keys and crypto codes retrieved from the CRPT Order Management Station.
		item		[0...*] [-]	-	Required. Group of serial numbers with their corresponding crypto key and crypto code.
			OBJ_CODE	[1...1] [0/*]	String	Required. Contains encoded serial number including corresponding crypto key and crypto code. Must include both the crypto key and crypto code values. Format is AI(01)+(21)+(91)+(92), where (91) denotes the crypto key and (92) denotes the crypto code (e.g. (01)20300011234987(21)123456789012(91)1129(92)AusibQLCfH2fbOoXL3yU77gRBOsnhdkljRGjZvl7gy0Uu9E1l0x6S2RzaWbKSgI1RmYQnZyumM6ZWhx3ktKOCw==). Crypto key value is alphanumeric. Crypto code can contain alphanumeric values and symbols.
	IV_ACTION			[1...1] [0/1]	String	Return parameter which indicates the level of completeness of the request. TraceLink sends a reject error code if request is rejected:(e.g. R). `R` – Request has been rejected.
	IV_LIST_RANGE			[1...1] [0/1]	String	Defines the type of the serial number response. This can be a list or a range. Values:(e.g. L). `R` – The response contains a range. `L` – The response contains a list.
	IV_READYLY_ENCODE			[1...1] [0/1]	String	In addition to the numbers or range the request optionally also provides back readily encoded data either in GS1 element string or in EPC URI: 1: Encoding in GS1 Element format. 2: Encoding in EPC URI format. TraceLink will not populate this element, so an empty tag will be sent.
	IV_SIZE			[1...1] [1/*]	Integer	Required. Quantity of serial numbers within range request (e.g. 1000).
	IV_SYSTEM			[1...1] [0/60]	String	Required. The system name that has been created for the caller in SAP Advanced Track and Trace for Pharmaceuticals (e.g. 5060173540005\|TRACELINK). TraceLink uses this field to store the Sender and Receiver information separated by a pipe (\|) character.

Example

<?xml version="1.0" encoding="UTF-8"?>
<n1:SNR_REQ_ASYNC_OUT xmlns:n1="urn:sap-com:document:sap:rfc:functions">
  <IS_RANGE>
    <NUMBER_FROM/>
    <NUMBER_TO/>
    <TIME_REQ>20120630063234</TIME_REQ>
  </IS_RANGE>
  <IS_TRADE_ITEM>
    <TRADE_ITEM_TYPE>GTIN</TRADE_ITEM_TYPE>
    <TRADE_ITEM_ID>20300011234987</TRADE_ITEM_ID>
  </IS_TRADE_ITEM>
  <IT_ENCODED>
    <item>
      <OBJ_CODE>(01)00882025030220(21)100000001020(91)2332(92)AusibQLCfH2fbOoXL3yU77gRBOsnhdkljRGjZvl7gy0Uu9E1l0x6S2RzaWbKSgI1RmYQnZyumM6ZWhx3kt</OBJ_CODE>
    </item>
    <item>
      <OBJ_CODE>(01)00882025030220(21)100000001021(91)2332(92)AusibQLCfH2fbOoXL3yU77gRBOsnhdkljRGjZvl7gy0Uu9E1l0x6S2RzaWbKSgI1RmYQnZyumM6ZWhx3kt</OBJ_CODE>
    </item>
  </IT_ENCODED>
  <IT_RETURN/>
  <IT_SERIALS>
    <item>
      <NUMBER>(01)00882025030220(21)100000001020</NUMBER>
    </item>
    <item>
      <NUMBER>(01)00882025030220(21)100000001021</NUMBER>
    </item>
  </IT_SERIALS>
  <IV_ACTION/>
  <IV_LIST_RANGE>L</IV_LIST_RANGE>
  <IV_READYLY_ENCODE/>
  <IV_SIZE>10</IV_SIZE>
  <IV_SYSTEM>8888884043588|7777776067344</IV_SYSTEM>
</n1:SNR_REQ_ASYNC_OUT>

Errors

Data Element	Error Message	Description
Class 1
NUMBER_FROM	EndingNumber is required when StartingNumber is populated !!!	The error occurs if cmn:StartingNumber is present in the source and cmn:EndingNumber is missing.
NUMBER_TO	StartingNumber is required when EndingNumber is populated !!!	The error occurs if cmn:EndingNumber is present in the source and cmnStartingNumber is missing.
GCP	At least one of CompanyPrefixObjectKey or GTIN14ObjectKey must be present in source !!!	The error occurs if neither cmn:CompanyPrefixObjectKey and cmn:GTIN14ObjectKey are present in the source.
GCP	Only one of CompanyPrefixObjectKey or GTIN14ObjectKey should be present in source !!!	The error occurs if both cmn:CompanyPrefixObjectKey and cmn:GTIN14ObjectKey are present in the source.
NUMBER	Only one choice element may be populated: SerialNumberRange or SerialNumberList or ErrorMessage !!!	The error occurs if more than one of the following elements are populated: NUMBER, IV_ACTION, or IV_LIST_RANGE.
NUMBER	One of the choice elements SerialNumberRange or SerialNumberList or ErrorMessage must be populated !!!	The error occurs if more than one of the following elements are populated: NUMBER, IV_ACTION, or IV_LIST_RANGE.
OBJ_CODE	Both crypto key and crypto code are required to build an encoded serial number !!!	The error occurs if either the crypto key or crypto code is present in the source and the other value missing.
IV_ACTION	Only one choice element may be populated: SerialNumberRange or SerialNumberList or ErrorMessage !!!	The error occurs if more than one of the following elements are populated: NUMBER, IV_ACTION, or IV_LIST_RANGE.
IV_ACTION	One of the choice elements SerialNumberRange or SerialNumberList or ErrorMessage must be populated !!!	The error occurs if more than one of the following elements are populated: NUMBER, IV_ACTION, or IV_LIST_RANGE.
IV_LIST_RANGE	Only one choice element may be populated: SerialNumberRange or SerialNumberList or ErrorMessage !!!	The error occurs if more than one of the following elements are populated: NUMBER, IV_ACTION, or IV_LIST_RANGE.
IV_LIST_RANGE	One of the choice elements SerialNumberRange or SerialNumberList or ErrorMessage must be populated !!!	The error occurs if more than one of the following elements are populated: NUMBER, IV_ACTION, or IV_LIST_RANGE.
Class 2
-
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.

Serial Number Request & Response (SOAP)

Serial Number Request

Guidelines

Data Element					Occurs Length	Type	Description
soapenv:Envelope					[1...1] [1/*]	-	Required. Soap envelope.
	soapenv:Header				[0...1] [-]	-	Not used by TraceLink, therefore the element can be null or omitted.
	soapenv:Body				[1...1] [-]	-	Required. Soap message body.
		urn:serialNumbersRequest			[1...1] [-]	-	Required. The Serial Number Request message payload.
			SendingSystem		[0...1] [1/*]	String	Required. Identifier for site manager system requesting serial numbers. This value must match the configured value for the requesting system in the Serial Number Exchange configuration. This value is repeated in the response message as the ReceivingSystem (e.g. SYSTEM-100001).
			ReceivingSystem		[0...1] [1/*]	String	Required. Identifier for target service that responds to serial number requests. This value must match the configured value for the service in the Serial Number Manager configuration. This value is repeated in the response message as the SendingSystem (e.g. 0060354701201).
			IdType		[0...] [1/*]	String	Specifies the type of serial numbers requested (e.g. GS1_SER CN_SER).
			EncodingType		[0...1] [1/*]	String	Required. Specifies the encoding format for the type of serial numbers requested. SGTIN is used for both GTIN-14 and NTIN numbers (e.g. SGTIN SSCC CN_EDMC). See the Encoding enumeration list for valid values.
			Size		[0...1] [-]	Int	Required. Specifies the quantity of serial numbers requested (e.g. 100000).
			ObjectKey		[0...1] [-]	-	Required. The key for the associated object (that holds the identifier type and value) for which the serial numbers are being requested.
				Name	[0...1] [1/*]	String	Required. Specifies the identifier type of the associated object for which serial numbers are being requested (e.g. GTIN).
				Value	[0...1] [1/*]	String	Required. The corresponding identifier of the associated object for which serial numbers are being requested (e.g. the GTIN-14 identifier, NTIN 14-digit identifier, GS1 Company Prefix value, or China Subtype and attributes). If ObjectKey/Name requests an SSCC code using COMPANY_PREFIX, the format of the Value is as follows:(e.g. GTIN: 00882026030229). <Company Prefix>\|<Logistic Unit Indicator> The Logistic Unit Indicator to request an SSCC for a pallet or case must match the configured value in Serial Number Manager. If ObjectKey/Name requests a CN_EDMC code using CN_SUBTYPE_LEVEL_RATIO, the format of the Value is as follows: <CN-Subtype Code>\|<CN Code Level>\|<CN Package Ratio> The Code Level must be the configured code level value for the packaging hierarchy as configured in China Master Data that maps to a specific Resource Code. The PackageRatio is optional. If included, it must use the PackageRatio exactly as configured in China Master Data that maps to a specific Resource Code. It is used to disambiguate when there are serial numbers associated with multiple Resource Codes for the Code Level or Package Ratio for the Subtype. If it is omitted and there are multiple Resource codes for the same Code Level or Package Ratio, the system returns an error.
			RequestRandomizedNumbers		[0...1] [1/*]	String	Not used by TraceLink, the element can be null or omitted.
			ReferenceDocuments		[1...1] [-]	-	Indicates optional reference documents related to the request.
				PONumber	[1...1] [1/*]	String	The Purchase Order (PO) number associated with serial number request (e.g. 10043).
				POLine	[1...1] [1/*]	String	Conditionally required if PONumber is populated. The PO line number associated with serial number request (e.g. 1).
				WorkOrderNumber	[0...1] [1/*]	String	The Work Order number associated with serial number request (e.g. 10043-001).
				ReferenceId	[0...1] [1/*]	String	The Reference Identifier associated with serial number request (e.g. 917902db-1307-4182-ad3d-29eca2d699ae).
			SyncRequest		[0...1] [1/*]	Boolean	If requesting more than 100,000 serial numbers, it is recommended to set SyncRequest to "false" to enable asynchronous processing to avoid an error. Values: `true` - enables synchronous processing. `false` - enables asynchronous processing. (Default)

Example

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

Errors

Error Code	Error Messages
500	CN-Subtype identifier <CN-Subtype> is not in the permitted serial number request list.
500	Encoding type requested is not correct type for product <ObjectKey/Name> <ObjectKey/Value> and service <SNX Service Identifier>.
500	Filter value <FilterValue> or Company Prefix <CompanyPrefix ObjectKey> is not valid.
500	GTIN-14 identifier <GTIN-14> is not in the permitted serial number request list.
500	More than one Code Level found for <CN_SUBTYPE_LEVEL_RATIO>. PackagingRatio must be specified to disambiguate request.
500	NTIN identifier <NTIN Value> is not in the permitted serial number request list.
500	Product ID <ObjectKey/Name> <ObjectKey/Value> is not valid for products in service <SNX ServiceID>.
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.
500	Quantity requested for <Object Identifier> exceeds the maximum quantity allowed: <Maximum Quantity for Serial Number Requests>.
500	Quantity requested for <Object Identifier> exceeds the maximum quantity allowed: 500000.
500	Request for too few serial numbers: quantity <quantity requested> must be greater than 0.
500	Serial Number Manager does not have serial numbers to satisfy the serial number request for <Object 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 (e.g. This occurs when the template TraceLink attempts to look-up numbers against requires reference documents, however, the request did not include any.).
500	Serial Number Manager does not have serial numbers to satisfy the serial number request for <Object Identifier> with [PO Number <PONumber>] [and] [WorkOrder <WorkOrderNumber>] [and] [<Reference Identifier> <ReferenceIdentifierNumber>] (e.g. Error message should include only the combination of one or more identifiers that are provided in the request. Rejected if a serial number request is made against a template that is configured AutoReplenishment and SN Pools Tagged with Production Order Id and request does not contain a production order id (PONumber, WorkOrder and/or ReferenceIdentifier). If the Serial Number Exchange application that receives the SN Request is connected to a TraceLink Serial Number Manager application of the same application owner's, the system checks the Serial Number Manager Template for the ObjectIdentifier and if it is configured as AutoReplenishment, the system needs to check if the Pharmaceutical Manufacturer of the serial numbers is maintaining separate serial number pools for each production order and ensure that the serial numbers provisioned against a request are drawing from the correct production order pool.).
500	Unable to acquire lock on serial number space for <ObjectKey/Value>. Please try again.
500	Unable to find service from lookup id: <SNX ServiceID>.
500	When requesting China serial numbers and a non-numeric code level value is supplied: Non-numeric value specified for code level: <value>.
500	When requesting China serial numbers and a non-numeric code level value is supplied: Non-numeric value specified for code level: <Value>.
500	When requesting serial numbers for a template that is enabled to be provisioned externally: The serial number template is configured to not allow provisioning for <packagingCode>.
500	You are not authorized to access this service.

Serial Number Response

Guidelines

Data Element						Occurs Length	Type	Description
S:Envelope						[ 1...1] [-]	-	Required. Soap envelope.
	S:Body					[ 1...1] [-]	-	Required. Soap message body.
		ns2:serialNumbersRequestResponse				[ 1...1] [-]	-	Required. The Serial Number Response message payload.
			ReceivingSystem			[ 1...1] [ 1/*]	String	Identifier for site manager system that requested the serial numbers. This value must match the configured value for the requesting system in the Serial Number Manager application configuration. Included in the response if the serial number range or list is returned, and omitted if an error response is returned (e.g. 0060354701201).
			SendingSystem			[ 1...1] [ 1/*]	String	Identifier for the service responding to serial number requests. This value must match the configured value for the service in the SNM configuration. Included in the response if the serial number range or list is returned, and omitted if an error response is returned (e.g. SYSTEM-100001).
			ActionCode			[1...1] [1/*]	String	Value "C" is always returned. This value may be ignored. Included in response if serial number range or list is returned, omitted if error response is returned (e.g. C).
			EncodingType			[1...1] [1/*]	String	Specifies the encoding format for the type of serial numbers requested as provided in the request. SGTIN is used for both GTIN-14 and NTIN numbers. Included in response if the serial number range or list is returned, and omitted if an error response is returned. See the Encoding enumeration list for valid values.
			IdType			[1...1] [1/*]	String	Specifies the type of serial numbers requested as provided in the request. Included in the response if the serial number range or list is returned, and omitted if an error response is returned.
			Interval			[1...1] [-]	-	If a serial number range is returned, specifies the serial number range. Only one of the following is returned: `Interval` `RandomizedNumberList` `RfidException`
				NumberFrom		[1...1] [1/*]	String	Required. If a serial number range is returned, specifies the starting serial number value. This element returns serial numbers in their fully formed format (e.g. AI(01)(21) formatted numbers for SGTINs are populated in the fields fully formed as “018038888293000621100000000001” with the “01” and “21” values present, and the AI(00) formatted numbers for SSCCs are populated in the fields fully formed as "00003888820001000011" with the “00” value present) (e.g. 010088202603022921100000000000).
				NumberTo		[1...1] [1/*]	String	Required. If a serial number range is returned, specifies the ending serial number value. This element returns serial numbers in their fully formed format (e.g. AI(01)(21) formatted numbers for SGTINs are populated in the fields fully formed as “018038888293000621100000000001” with the “01” and “21” values present, and the AI(00) formatted numbers for SSCCs are populated in the fields fully formed as "00003888820001000011" with the “00” value present) (e.g. 010088202603022921100000000009).
			ObjectKey			[1...1] [-]	-	The key for the associated object (that holds the identifier type and value) for which the serial numbers were requested. Included in the response if a serial number range or list is returned, and omitted if an error response is returned.
				Name		[1...1] [1/*]	String	Required. Specifies the identifier type of the associated object for which serial numbers were requested.
				Value		[1...1] [1/*]	String	Required. The corresponding identifier of the associated object for which serial numbers are requested (for example, the GTIN-14 identifier, NTIN 14-digit identifier, GS1 Company Prefix value, or China Subtype and attributes). If ObjectKey / Name requests an SSCC code using COMPANY_PREFIX, the format of the Value is as follows:(e.g. GTIN: 00882026030229). <`Company Prefix`>\|<`Logistic Unit Indicator`> The Logistic Unit Indicator to request an SSCC for a pallet or case must match the configured value in Serial Number Manager. If ObjectKey / Name requests a CN_EDMC code using CN_SUBTYPE_LEVEL_RATIO, the format of the Value is as follows: <`CN-Subtype Code`>\|<`CN Code Level`>\|<`CN Package Ratio`> The Code Level must be the configured code level value for the packaging hierarchy as configured in China Master Data that maps to a specific Resource Code. The PackageRatio is optional. If included, it must use the PackageRatio exactly as configured in China Master Data that maps to a specific Resource Code. It is used to disambiguate when there are serial numbers associated with multiple Resource Codes for the Code Level or Package Ratio of the Subtype. If it is omitted and there are multiple Resource codes for the same Code Level or Package Ratio, the system returns an error.
			ReferenceDocuments			[1...1] [-]	-	The reference documents passed in on request, returned with the response.
				PONumber		[1...1] [1/*]	String	The PO number associated with serial number request.
				POLine		[1...1] [1/*]	String	Conditionally required if PONumber is present. The PO line number associated with serial number request.
				WorkOrderNumber		[1...1] [1/*]	String	The Work Order number associated with serial number request.
				ReferenceIdentifier		[1...1] [1/*]	String	The Reference Identifier associated with serial number request.
			RandomizedNumberList			[1...1] [-]	-	If a serial number range is returned, specifies the serial number range. Only one of following is returned: `Interval` `RandomizedNumberList` `RfidException`
				SerialNo		[1...] [1/]	String	Required. If a serial number list is returned, specifies the list of serial numbers in the SerialNo repeating element. This element returns serial numbers in their fully formed format (e.g. AI(01)(21) formatted numbers for SGTINs are populated in the fields fully formed as “018038888293000621100000000001” with the “01” and “21” values present, and the AI(00) formatted numbers for SSCCs are populated in the fields fully formed as "00003888820001000011" with the “00” value present) (e.g. 010088202501033821100011946933 and 00008820210000000005). If a serial number list is not returned (e.g. range is returned), the RandomizedNumberList element group is omitted. SGTINs are mandatory for Russia serial numbers.
					cryptoKey	[0...*] [0/4]	String	Conditionally required if for Russia serial numbers. The alphanumeric crypto key value retrieved from the CRPT Order Management Station. AI(91) denotes this value in the serial number (e.g. 911234).
					cryptoCode	[0...*] [0/44]	String	Conditionally required if for Russia serial numbers. The crypto code value retrieved from the CRPT Order Management Station. This value can contain alphanumeric values as well as symbols. AI(92) denotes this value in the serial number. The following are valid symbols:(e.g. 92AusibQLCfH2fbOoXL3yU77gRBOsnhdkljRGjZvl7gy0U). See Crypto Code Symbols for valid symbols allowed in the `cryptoCode`.
			RfidException			[-] [-]	-	If an error is returned, specifies the error. Only one of the following values is returned: `Interval` `RandomizedNumberList` `RfidException`
				errorCode		[1...1] [1/*]	String	The error code returned from Serial Number Manager.
				errorMessage		[1...1] [-]	String	Required. The error message description returned from Serial Number Manager (e.g. GTIN-14 identifier 00882026030229 is not in the permitted serial number request list.).

Example

<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 cryptoKey="918567" cryptoCode="9269139&quot;9926C19%4400G21300791248!74,35&lt;,575162">010088202501033821100011946933</SerialNo>
                    <SerialNo cryptoKey="918567" cryptoCode="92JEIF840$JDFDSA!L;ASDJASDMASDLKFJANE;ASD&gt;LHJA">010088202501033821100015310495</SerialNo>
                    <SerialNo cryptoKey="918567" cryptoCode="92546KLJDFG94N&amp;ALDFJ^KLJBN346#NDSFL%LKJADADNRI">010088202501033821100018139350</SerialNo>
                    <SerialNo cryptoKey="918567" cryptoCode="92489345MDFSLK8945893,5HJDSFKL3$LKJSDGF&amp;LKJDFG">010088202501033821100012121992</SerialNo>
                    <SerialNo cryptoKey="918567" cryptoCode="92DSAFL48904!KASDFG^;LKJASDF%ASDFLKJ9ASL34JD34">010088202501033821100016483276</SerialNo>
                    <SerialNo cryptoKey="918567" cryptoCode="92%LSDAFASDF9084&amp;;LKLJ!;LKJA234ASDF724LK$LJ$;L">010088202501033821100012414042</SerialNo>
                    <SerialNo cryptoKey="918567" cryptoCode="92834HASKLJHSDA$KJH%;LHJLKSDF^ASDFKLJDSFLKW!;L">010088202501033821100016102891</SerialNo>
                    <SerialNo cryptoKey="918567" cryptoCode="9290KLKLNAB%KLJ&amp;KLJ^7DSFKLJASDG234KLJSD#4L&apos;ASD">010088202501033821100013578725</SerialNo>
                </RandomizedNumberList>
            </SNResponse>
        </ns2:serialNumbersRequestResponse>
    </S:Body>
</S:Envelope>

Serial Number Manager Request and Response (Verify Brand)

Serial Number Manager Request

Guidelines

Use this message to replenish serial numbers from the Verify Brand system.

Message Type: SNM_REQUEST

Info Exchange Display Name: Serial Number Replenish Request

When sending an element in Date or DateTime format, a valid date must be given. "00" is not a valid day or month value and "0000" is not a valid year value.

Data Element					Occurs	Format	Length	Enums	Req	Description
snm:SNMRequestType					[1...1]	-	-	-	M	Root data element.
	snm:ControlFileHeader				[1...1]	-	-	-	M	Serial Number Manager control header record group.
		cmn:FileSenderNumber			[1...1]	String	[1/*]	-	M	File sender's company identifier. *1
		cmn:FileReceiverNumber			[1...1]	String	[1/*]	-	M	File recipient's company identifier. *2
		cmn:FileControlNumber			[1...1]	String	[1/*]	-	M	Unique file control ID number. *3
		cmn:FileDate			[1...1]	Date	[0/*]	-	M	Date file generated in XML YYYY-MM-DD format. *4
		cmn:FileTime			[1...1]	Time	[0/*]	-	M	Time file generated in XML HH:MM:SSZ format (must be GMT). *5
	snm:MessageBody				[1...1]	-	-	-	M	Request Details.
		cmn:RequestId			[1...1]	String	[1/*]	-	M	Unique identifier for the serial number request. This is used to link the Serial Number Response from Serial Number Manager back to the originating Serial Number Response. *6
		cmn:PlantIdentifier			[0...1]	String	[0/*]	-	O	Identifier of plant location requesting serial numbers. Required by Serial Number Manager applications to track the plant that commissioned the serial numbers. *7
			@type		[1...1]	String	[0/*]	LocationType	M	Plant location identifier type. Indicates the encoding type that is used to identify the requesting site location. *8
		cmn:ReferenceDocuments			[0...1]	-	-	-	-	Reference to specific manufacturing orders associated with the Serial Number Request. Indicates that the requested serial numbers will be used for the referenced manufacturing orders.
			cmn:PONumber		[0...1]	String	[0/*]	-	O	Purchase order (PO) number associated with Serial Number Request. *9
			cmn:POLine		[0...1]	String	[0/*]	-	O	PO line number associated with Serial Number Request. *10
			cmn:WorkOrderNumber		[0...1]	String	[0/*]	-	O	Work order number associated with Serial Number Request. *11
			cmn:ReferenceIdentifier		[0...1]	String	[0/*]	-	O	Reference identifier. *12
		cmn:NumberEncoding			[1...1]	String	[0/*]	Encoding	M	Encoding format for the type of serial numbers that are being requested from the enumeration list (e.g. AI(01)+AI(21) for serialized GTIN, AI(00) for SSCC-18). *13
		cmn:RU_CryptoCodeRequest			[0...1]	Boolean	-	-	M	Indicates a request for Kazakhstan Crypto Codes, Russia crypto codes , or Uzbekistan Crypto Codes. The default value is "false". Valid values: *14 true = Request crypto codes. Kazakhstan Crypto Codes, Russia crypto codes, or Uzbekistan Crypto Codes are expected in the Serial Number Manager Response. false = Do not request crypto codes. Kazakhstan Crypto Codes, Russia crypto codes , or Uzbekistan Crypto Codes are not expected in the Serial Number Manager Response.
		cmn:ObjectIdentifier			[1...1]	Choice	-	-	M	The identifier associated with the cmn:NumberEncoding for the serial numbers being requested. There is a choice element within the ObjectIdentifier data element, meaning that only one of the four options below can be populated.
			cmn:CompanyPrefixObjectKey		[0...1]	String	[1/*]	-	O	The company prefix assigned by GS1 for the required SSCC numbers. Used only when cmn:NumberEncoding is for SSCC numbers. *15
				@filterValue	[0...1]	Integer	[0/*]	FilterValue	O	The Filter Value for the packaging level of the SSCC number that is being requested to indicate if the SSCC is for a pallet, mixed case, etc. This should be an integer with a value 0-7.
			cmn:GTIN-14		[0...1]	String	[1/*]	-	O	The GTIN-14 for the required SGTIN and AI(01)+AI(21) serial numbers. The GTIN-14 also informs logistical unit. Used only when cmn:NumberEncoding is for SGTIN and AI(01)+AI(21). *16
			cmn:NTINObjectKey		[0...1]	String	[1/*]	-	C	The NTIN for the required NTIN and AI(01)+AI(21) serial numbers. The NTIN also informs logistical unit. Used only when cmn:NumberEncoding is for SGTIN and AI(01)+AI(21). *17
		cmn:Quantity			[1...1]	Int	[1/*]	-	M	Quantity of serial numbers requested. *18

Example

<?xml version="1.0" encoding="UTF-8"?>
<snm:SNMRequestType xmlns:snm="urn:tracelink:mapper:sl:serial_number_manager" xmlns:cmn="urn:tracelink:mapper:sl:commontypes">
<snm:ControlFileHeader>
    <cmn:FileSenderNumber>8888884043588</cmn:FileSenderNumber>
    <cmn:FileReceiverNumber>10021144</cmn:FileReceiverNumber>
    <cmn:FileControlNumber>0000000414236887</cmn:FileControlNumber>
    <cmn:FileDate>2016-09-15</cmn:FileDate>
    <cmn:FileTime>09:09:09Z</cmn:FileTime> 
</snm:ControlFileHeader>
    <snm:MessageBody>
        <cmn:RequestId>20160201090909_08806500018314</cmn:RequestId>
        <cmn:PlantIdentifier type="GLN">CMO_System</cmn:PlantIdentifier>
        <cmn:ReferenceDocuments>
            <cmn:PONumber>4500018051</cmn:PONumber>
            <cmn:POLine>10</cmn:POLine>
            <cmn:WorkOrderNumber>1001764-00</cmn:WorkOrderNumber>
            <cmn:ReferenceIdentifier>A12345</cmn:ReferenceIdentifier>
        </cmn:ReferenceDocuments>
        <cmn:NumberEncoding>AI(01)+AI(21)</cmn:NumberEncoding>
        <cmn:RU_CryptoCodeRequest>true</cmn:RU_CryptoCodeRequest>
        <cmn:ObjectIdentifier>
            <cmn:GTIN-14>80388882930006</cmn:GTIN-14>
        </cmn:ObjectIdentifier>
        <cmn:Quantity>10</cmn:Quantity>
    </snm:MessageBody>
</snm:SNMRequestType>

Errors

Data Element	Error Message	Description
Class 1 Errors
cmn:NumberEncoding	Valid number encoding code is required !!!	The error occurs if the source is empty or null, or is not a valid value from the enumeration list.
cmn:ObjectIdentifier	Only one of CompanyPrefixObjectKey OR GTIN14ObjectKey OR CNSubtypeObjectKey OR NTINObjectKey is required !!!	The error occurs if none, or more than one, of the following are present: cmn:CNSubtypeObjectKey, cmn:CompanyPrefixObjectKey, cmn:GTIN14ObjectKey, or cmn:NTINObjectKey.
Class 2 Errors
-	-	-
Class 3 Errors
The following is thrown for all Class 3 errors: “INTERNALERROR=Internal error from server [server details].” Please contact Support if this error is encountered.

Serial Number Manager Response

Guidelines

Message Type: SNM_RESPONSE

Info Exchange Display Name: Serial Number Replenish Response

When sending an element in Date or DateTime format, a valid date must be given. "00" is not a valid day or month value and "0000" is not a valid year value.

Data Element				Occurs	Format	Length	Enums	Req	Description
CodeRequestReport				[1...1]	-	-	-	M	Root data element.
	Quantity			[1...1]	Integer	[1/*]	-	M	The total quantity of UIDs contained in the file. *19
	CompanyPrefix			[0...1]	Integer	[1/*]	-	C	The company prefix (product number value) associated with the allocated UIDs. 20 At least one, and only one, of CompanyPrefix or AssociatedProducts, or AssociatedProducts \| Value* is required. Mandatory if UID contains SSCCs.
	ExtensionDigit			[0...1]	Integer	[1/*]	-	O	This field not used.
	DateCodesWereGenerated			[1...1]	DateTime	[1/*]	-	M	The date/time the UIDs were generated in the Verify Platform. *21
	CodeRequestKey			[1...1]	String	[0/*]	-	M	The unique key associated with the UID request. *22
	AssociatedProducts			[1...1]	-	-	-	M	Request identifier fields. Populated with TraceLink and Verify Brand request identifiers. For SSCCs, an empty tag is sent. At least one, and only one, of CompanyPrefix or AssociatedProducts, or AssociatedProducts \| Value is required.
		AssociatedProduct		[0…*]	-	-	-	C	Message group header for looping group. Mandatory if UID contains SGTINs.
			Type	[1...1]	String	[0/*]	-	M	The product reference identifier type. The most common value is "GTIN". Valid values: *23 GTIN NTIN
			Value	[1...1]	String	[0/*]	-	M	The product reference identifier. The most common value is the class-level urn for GTIN, (e.g. urn:epc:id:sgtin:0369999.039801).* 24 At least one, and only one, of CompanyPrefix or AssociatedProducts, or AssociatedProducts \| Value* is required.
	SenderId			[1...1]	String	[0/*]	-	M	Identifier for the sender of the file.
	UIDs			[1...1]	-	-	-	O	Request identifier fields. Populated with TraceLink and Verify Brand request identifiers.
		UID		[1...*]	-	-	-	M	Parent element for serial numbers in urn format, crypto key, and crypto code.
			URN	[1...1]	String	[0/*]	-	M	Explicit list of UIDs (serial numbers) in urn format. This is a repeating element. *25
			CryptoKey	[1...1]	String	[0/*]	-	M	The crypto key value retrieved from the OMS owned by the pharmaceutical manufacturer. Crypto keys are alphanumeric and are 4 characters long. *26
			CryptoCode	[1...1]	String	[0/*]	-	M	The crypto key value retrieved from the OMS owned by the pharmaceutical manufacturer. Crypto codes can contain alphanumeric values as well as symbols and are either 44 or 88 characters long. AI(92) denotes this value in the serial number. The following are valid symbols: 27 ! " – (") % & – (&) ' – (') + - . / _ , : ; = < – (<) > – (>) ? TraceLink escapes the following special XML characters before sending the Serial Number Manager Response message: " – (") & – (&) ' – (') < – (<) > – (>)
	Location			[1...1]	-	-	-	M	Location group header.
		References		[1...1]	-	-	-	M	Location reference identifier.
			Reference	[1...1]	String	[0/*]	-	M	The location reference identifier type. The most common value is "SGLN". Location refers to the location the UIDs were requested for. *28
			Name	[1...1]	String	[0/*]	-	O	The location reference identifier name. *29
	BusinessTransactions			[1...1]	-	-	-	M	Business Transactions group header.
		BusinessTransaction		[0…*]	-	-	-	O	Business Transaction group header.
			Type	[1...1]	String	[0/*]	-	M	Not used.
			ID	[1...1]	String	[0/*]	-	M	Not used.

Example

<?xml version="1.0"?>
<CodeRequestReport xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <Quantity>10</Quantity>
    <DateCodesWereGenerated>2018-07-12T15:20:43-05:00</DateCodesWereGenerated>
    <CodeRequestKey>762becab-38b7-443a-8c22-9b20cc9487b4</CodeRequestKey>
    <AssociatedProducts>
        <AssociatedProduct>
            <Type>GTIN</Type>
            <Value>urn:epc:idpat:sgtin:0311111.000000.*</Value>
        </AssociatedProduct>
    </AssociatedProducts>
    <UIDs>
        <UID>
            <URN>urn:epc:id:sgtin:0311111.000000.ADEEVIUICARC</URN>
            <CryptoKey>91EyMw</CryptoKey>
            <CryptoCode>92d25lZmFvaTJoajM5NDhocjU5ODJoYXI4aDM5d2E4aGY7</CryptoCode>
        </UID>
        <UID>
            <URN>urn:epc:id:sgtin:0311111.000000.ALUIHJMLHJHF</URN>
            <CryptoKey>91dlZg</CryptoKey>
            <CryptoCode>92NTczNDk4N2FzZGl1aGZsaXd1OyxobGFnd2VmbGl1aGFs</CryptoCode>
        </UID>
    </UIDs>
    <Location>
        <References>
            <Reference>urn:epc:id:sgln:0311111.00000.0</Reference>
        </References>
        <Name>Sample CMO Location 1</Name>
    </Location>
    <BusinessTransactions/>
</CodeRequestReport>

Errors

Data Element	Error Message	Description
Class 1 Errors
CompanyPrefix	Only one of CompanyPrefixObjectKey or GTIN14ObjectKey is required !!!	The error occurs if both CompanyPrefix and AssociatedProduct are populated.
CompanyPrefix	At least one of CompanyPrefixObjectKey or either of GTIN14ObjectKey and NTINObjectKey is required !!!	The error occurs if both CompanyPrefix and AssociatedProduct are empty or null.
cmn:FileReceiverNumber	Valid FileReceiverNumber is required !!!	The error occurs if UID is empty or null.
Value	Value is required if AssociatedProduct/Type = "GTIN" is populated !!!	The error occurs if AssociatedProduct \| Type = "GTIN", but the source is empty or null.
Value	Only one AssociatedProduct group is required !!!	The error occurs if more than one AssociatedProduct group is populated.
UID	UID must be populated !!!	The error occurs if the source is empty or null.
	UID must contain an SGTIN or SSCC only !!!	The error occurs if the source does not contain an SGTIN or SSCC.
	UID must be an SSCC or an SGTIN only !!!	The error occurs if the source does not contain an SGTIN or SSCC.
	Valid SSCC or SGTIN serial number format is required !!!	The error occurs if the source is not in valid SGTIN or SSCC format.
URN	URN must contain an SGTIN or SSCC only !!!	The error occurs if the source does not equal "urn:epc:id:sgtin:".
	ExtensionDigit required for SSCCs !!!	The error occurs if the source equals "urn:epc:id:sscc:" and CodeRequestReport \| ExtensionDigit is missing.
	Valid SSCC or SGTIN serial number format is required !!!	The error occurs if the source is invalid.
CryptoKey	CryptoKey is required if URN is present !!!	The error occurs if URN is present but the source is missing.
CryptoCode	CryptoCode is required if URN is present !!!	The error occurs if URN is present but the source is missing.
Reference	Location reference identifier type must be an SGLN !!!	The error occurs if the source is not an SGLN.
Reference	Location reference identifier is required !!!	The error occurs if the source is empty or null.
Class 2 Errors
-	-	-
Class 3 Errors
The following is thrown for all Class 3 errors: “INTERNALERROR=Internal error from server [server details].” Please contact Support if this error is encountered.