Transfer serial number APIs

Serial number transfer messages allow companies to provision serial numbers for use at a new location.

Serial Number Transfer (TraceLink XML)

This message is usually used by Third Party Printers to transfer encoded serial numbers to their packaging location after they are printed onto packaging labels or cartons. After a request is sent, TraceLink sends the transferred serial numbers to the new location in a response message.

Guidelines

  • Message type: SNX_TRANSFER
  • Info Exchange Display Name: Serial Number Transfer
  • Map Version: TL_XML_SNX_SerialNumberTransfer_1_0_IB_V1_1

  Element Occurs Length Type Description
snx:SNXSerialNumberTransferMessage [1...1]
[-]		 - Required. The XML message root element.
  snx:ControlFileHeader [1...1]
[-]		 - Required. The XML file control header.
    cmn:FileSenderNumber [1...1]
[1/20]		 String Required. The unique identifier for the company sending the message (e.g. 7777776067344).
    cmn:FileReceiverNumber [1...1]
[1/20]		 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:EventDateTime [1...1]
[1/*]		 String Required. The date and time the serial number was transferred in YYYY-MM-DDTHH:MM:SSZ format (e.g. 2023-03-31T12:40:21.140Z). Milliseconds default to zero.
    cmn:EventTimeZoneOffset [1...1]
[6/6]		 String Required. The time zone offset in effect at the time and place where the event occurred (e.g. -05:00).
    choice%1 [1...1]
[-]		 -

This message supports two serial number identifier sequences:

  • To transfer a lot of encoded serial numbers, cmn:PackagingItemCode and cmn:ReferenceDocuments must be present.
  • To transfer a specific list of serial numbers, snx:SerialNumbers must be present. If parent serial numbers of aggregated items are specified, all child and sub-child serial numbers will also be transferred.
    cmn:PackagingItemCode [0...1]
[0/*]		 String Conditionally required if snx:SerialNumbers is not present. The packaging code value associated with the encoded serial numbers to identify a product at a specific packaging level (e.g. 50300694220667).
      @type [1...1]
[1/*]		 String

Required. The type of packaging code.

Valid values:

  • CN-RESCODE – A 5-digit China packaging code.
  • GTIN-14 – A 14-digit Global Trade Identification Number.
  • NTIN – A 14-digit National Trade Item Number.
    cmn:ReferenceDocuments [0...1]
[-]		 - Conditionally required if cmn:PackagingItemCode is present. The business documents associated with the commissioning event.
      cmn:PONumber [0...1]
[0/*]		 String Conditionally required if cmn:POLine is populated. The number of the purchase order (PO) issued by the manufacturer for the lot production (e.g. 1001764).
      cmn:POLine [0...1]
[0/*]		 String 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]
[0/*]		 String The internal business identifier associated with the production of this lot (e.g. A100352).
    snx:SerialNumbers [0...1]
[-]		 - Conditionally required if cmn:PackagingItemCode is not present. The list of serial numbers being transferred to a new location.
      cmn:Serial [1...1]
[1/*]		 String

The serial number being transferred. 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
        @format [0...1]
[0/*]		 String

The type of serial number encoding format.

Valid values:

  • AI(00) – A Serial Shipping Container Code (SSCC).
  • AI(01)+AI(21) – An item's Global Trade Item Number (GTIN) or National Trade Item Number (NTIN) and serial number.
  • CN-EDMC – A Chinese Electronic Data Monitoring Code.
      cmn:EventLocation [1...1]
[1/34]		 String Required. The SGLN of the location where the transfer was initiated, with the urn prefix omitted (e.g. 8888882.02867.0 instead of urn:epc:id:sgln:8888882.02867.0).
      cmn:SNTransferToLocation [0...1]
[0/*]		 String The unique identifier value for the location the serial numbers will transfer to (e.g. 8888882028644).
        @type [1...1]
[1/*]		 String

Required. The type of location identifier.

Valid values: 

  • COMPANYID – Alphanumeric internal company identifier (e.g. KENDALL).
  • COMPANYSITEID – Alphanumeric internal location, plant, or site identifier (e.g. 465MEMPHIS).
  • CPNJ – Brazil Tax ID for Legal Entities.
  • CUIT – Argentina Tax ID.
  • DEA – 9-character US Drug Enforcement Agency Number (e.g. F92547851).
  • DUNS – 9-character Dunn and Bradstreet Number (e.g. 82-759-6961).
  • DUNS4 – 13-character Dunn and Bradstreet Number, which includes a 4 digit extension (e.g. 82-759-6961-KP89).
  • GLN – 13-character Global Location Number (e.g. 8856277233311). To send and receive EPCIS messages, companies and locations need a GLN.
  • HIN – Maximum 9-alphanumeric character Health Industry Number assigned by HIBCC (e.g. 214Z65H00).

Example

Copy 
<?xml version="1.0" encoding="UTF-8"?>
<SNXSerialNumberTransferMessage xmlns="urn:tracelink:mapper:sl:serial_number_exchange"
    xmlns:cmn="urn:tracelink:mapper:sl:commontypes" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <ControlFileHeader>
        <cmn:FileSenderNumber>8779891013658</cmn:FileSenderNumber>
        <cmn:FileReceiverNumber>8888884043540</cmn:FileReceiverNumber>
        <cmn:FileControlNumber>0000000002</cmn:FileControlNumber>
        <cmn:FileDate>2020-08-14</cmn:FileDate>
        <cmn:FileTime>06:30:32Z</cmn:FileTime>
    </ControlFileHeader>
    <MessageBody>
        <cmn:EventDateTime>2020-08-14T06:30:32Z</cmn:EventDateTime>
        <cmn:EventTimeZoneOffset>+00:00</cmn:EventTimeZoneOffset>
        <cmn:PackagingItemCode type="GTIN-14">00992326050107</cmn:PackagingItemCode>
        <cmn:ReferenceDocuments>
            <cmn:ReferenceIdentifier>A1013453</cmn:ReferenceIdentifier>
        </cmn:ReferenceDocuments>
        <cmn:EventLocation>9997777.01994.0</cmn:EventLocation>
        <cmn:SNTransferToLocation type="GLN">8779891024769</cmn:SNTransferToLocation>
    </MessageBody>
</SNXSerialNumberTransferMessage>            
Copy 
<?xml version="1.0" encoding="UTF-8"?>
<SNXSerialNumberTransferMessage xmlns="urn:tracelink:mapper:sl:serial_number_exchange"
    xmlns:cmn="urn:tracelink:mapper:sl:commontypes" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <ControlFileHeader>
        <cmn:FileSenderNumber>8779891013658</cmn:FileSenderNumber>
        <cmn:FileReceiverNumber>8888884043540</cmn:FileReceiverNumber>
        <cmn:FileControlNumber>0000000002</cmn:FileControlNumber>
        <cmn:FileDate>2020-08-14</cmn:FileDate>
        <cmn:FileTime>06:30:32Z</cmn:FileTime>
    </ControlFileHeader>
    <MessageBody>
        <cmn:EventDateTime>2020-08-14T06:30:32Z</cmn:EventDateTime>
        <cmn:EventTimeZoneOffset>+00:00</cmn:EventTimeZoneOffset>
        <SerialNumbers>
            <cmn:Serial>00008820210000260003</cmn:Serial>
            <cmn:Serial>00008820210000260010</cmn:Serial>
            <cmn:Serial>00008820210000260027</cmn:Serial>
            <cmn:Serial>00008820210000260034</cmn:Serial>
            <cmn:Serial>00008820210000260041</cmn:Serial>
        </SerialNumbers>
        <cmn:EventLocation>9997777.01994.0</cmn:EventLocation>
        <cmn:SNTransferToLocation type="GLN">8779891024769</cmn:SNTransferToLocation>
    </MessageBody>
</SNXSerialNumberTransferMessage>

Errors

Element Error message Description
Class 1
choice%1 Only one of either PackagingItemCode / ReferenceDocuments or SerialNumbers must be present in source !!! Either the packaging code and reference documents or the list of serial numbers must be specified, but not both.
cmn:PackagingItemCode PackagingItemcode is required when source PackagingItemcode type is populated !!! This element must have a value specified.
cmn:PackagingItemCode | @type PackagingItemcode type attribute is required when source PackagingItemcode is populated !!! This element must have a value specified.
cmn:PackagingItemcode is not one of the allowed enumeration values!!! This element must be specified as one of the valid values.
cmn:ReferenceDocuments A PONumber, WorkOrderNumber or ReferenceIdentifier is required when PackagingItemcode is provided!!! This element must have a value specified.
cmn:POLine PONumber is required when POLine is provided!!! If cmn:POLine is present, then a purchase order number must be specified.
cmn:Serial | @format Serial format attribute is not one of the allowed enumeration values!!! This element must be specified as one of the valid values.
cmn:SNTransferToLocation SNTransferToLocation is required when source SNTransferToLocation type is populated !!! If cmn:SNTransferToLocation | @type is present, then this element must have a value specified.
cmn:SNTransferToLocation | @type SNTransferToLocation type attribute is required when source SNTransferToLocation is populated !!! This element must have a value specified.
Value [source] is not on the restriction list of the field. This element must be specified as one of the valid values.
Class 2
N/A Original snx transfer [request identifier] not found. The corresponding request for transfer cannot be found.

cmn:FileSenderNumber or cmn:FileReceiverNumber

 Unable to find product entry record for pool id [pool ID]. TraceLink cannot find the pool of serial numbers at this company for the packaging code entered.
Unable to find profile for serviceId [service ID] and subscriber company [Partner company ID]. The sender or receiver identifier, or the alternate identifier configured on the Link between them, does not have a Serial Number Exchange profile associated with it.
Unable to find active product pool for serviceId [app ID], snType [ packaging code type], packagingCode [packagingcode value], filtervalue [filter value]. TraceLink cannot find the pool of serial numbers at this company for the packaging code or filter value entered.
cmn:PackagingItemCode Transfer to Recipient [transfer to location] does not have Serial Number Profile configured for [packaging code type] [packaging code value]. The packaging code must be configured in the recipient's Serial Number Exchange profile.
Serial Number Transfer failed. No serial numbers in [valid state (i.e. "encoded")] state were found for Packaging Item Code [packaging code] and Reference Document [reference document]. Serial numbers must be in the encoded state in order to be transferred by packaging code and reference documents.
No SNX Messages found for Packaging Item Code [packaging code type] [packaging code value] and Reference Document [reference documents]. Perhaps the upstream operation has not yet completed. There are no previous events associated with the specified packaging code and reference documents.
cmn:SNTransferToLocation serviceDestinationCompanyID not specified. This element must have a value specified.
cmn:PackagingItemCode and cmn:ReferenceDocuments Serial Number Transfer for encoding serial numbers by Packaging Item Code [packaging code] and Reference Document [reference documents] did not find the expected number of serial numbers. Perhaps the encoding has not yet completed. The total number of serial numbers identified by the specified packaging code and reference documents are not available for transfer from the original location.
@codeLevel Master Data Code Level is invalid value! This element must be specified as one of the valid values.
cmn:PackagingItemCode PackagingItemCode value cannot be empty. This element must have a value specified.
PackagingItemCode type must have a valid value. This element must have a value specified.
cmn:SNTransferToLocation Unable to find Recipient Company [recipient location identifier]. The error occurs if unable to find the specified receipt company or location.
cmn:Serial No serial numbers specified. This element must have a value specified.
cmn:SNTransferToLocation Transfer to recipient [message recipient] does not have Serial Number Profile configured for [packaging code type] [packaging code value]. The error occurs if the transfer to recipient specified does not have a Serial Number profile configured for the specified packaging code.
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.

Guidelines

  • Message type: SNX_TRANSFER
  • Info Exchange Display Name: Serial Number Transfer
  • Map Version: TL_XML_SNX_SerialNumberTransferResponse_1_0_OB_V1_1

Element Occurs
Length		 Type Description
snx:SNXSerialNumberTransferResponseMessage [1...1]
[-]		 - Required. The XML message root element.
  snx:ControlFileHeader [1...1]
[-]		 - Required. The XML file control header.
    cmn:FileSenderNumber [1...1]
[1/20]		 String Required. The unique identifier for the company sending the message (e.g. 7777776067344).
    cmn:FileReceiverNumber [1...1]
[1/20]		 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:NumberEncoding [0...1]
[0/*]		 String

Required. The encoding format type for serial numbers being transferred.

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:GTIN14ObjectKey or cmn:NTINObjectKey must be present.
  • CN-EDMC – A Chinese Electronic Data Monitoring Code. cmn:CNSubtypeObjectKey must be present.
    cmn:ObjectIdentifier [0...1]
[-]		 Choice

Conditionally required to transfer encoded serial numbers at the same packaging level. The identifier associated with the cmn:PackagingItemCode in the transfer request. 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 for the serial numbers, assigned and administered by GS1 Global (e.g. 0388882).
      cmn:GTIN14ObjectKey [0...1]
[14/14]		 String Conditionally required if cmn:NumberEncoding is set to 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 subtype for the serial numbers (e.g. 7022014170).
        @codeLevel [0...1]
[0/*]		 String 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 set to AI(01)+AI(21) and cmn:GTIN14ObjectKey is not present. The NTIN for the serial numbers (e.g. 70021050441007).
    cmn:Quantity [1...1]
[1/*]		 Integer Required. The quantity of transferred serial numbers.
    cmn:SerialNumberList [1...1]
[-]		 - Required. The list of transferred serial numbers.
      cmn:SerialNumber [1...1]
[1/*]		 String

Required. The transferred 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

Example

Copy 
<?xml version="1.0" encoding="UTF-8"?>
<SNXSerialNumberTransferResponseMessage xmlns="urn:tracelink:mapper:sl:serial_number_exchange"
    xmlns:cmn="urn:tracelink:mapper:sl:commontypes" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <ControlFileHeader>
        <cmn:FileSenderNumber>8779891013658</cmn:FileSenderNumber>
        <cmn:FileReceiverNumber>8888884043540</cmn:FileReceiverNumber>
        <cmn:FileControlNumber>20200814063032014</cmn:FileControlNumber>
        <cmn:FileDate>2020-08-14</cmn:FileDate>
        <cmn:FileTime>06:32:32Z</cmn:FileTime>
    </ControlFileHeader>
    <MessageBody>
        <cmn:NumberEncoding>AI(01)+AI(21)</cmn:NumberEncoding>
        <cmn:ObjectIdentifier>
            <cmn:GTIN14ObjectKey>00992326050107</cmn:GTIN14ObjectKey>
        </cmn:ObjectIdentifier>
        <cmn:Quantity>10</cmn:Quantity>
        <cmn:SerialNumberList>
            <cmn:SerialNumber>010088202501033821100011946933</cmn:SerialNumber>
            <cmn:SerialNumber>010088202501033821100015310495</cmn:SerialNumber>
            <cmn:SerialNumber>010088202501033821100018139350</cmn:SerialNumber>
            <cmn:SerialNumber>010088202501033821100012121992</cmn:SerialNumber>
            <cmn:SerialNumber>010088202501033821100016483276</cmn:SerialNumber>
            <cmn:SerialNumber>010088202501033821100012414042</cmn:SerialNumber>
            <cmn:SerialNumber>010088202501033821100011320392</cmn:SerialNumber>
            <cmn:SerialNumber>010088202501033821100016102891</cmn:SerialNumber>
            <cmn:SerialNumber>010088202501033821100013578725</cmn:SerialNumber>
            <cmn:SerialNumber>010088202501033821100018119185</cmn:SerialNumber>
        </cmn:SerialNumberList>
    </MessageBody>
</SNXSerialNumberTransferResponseMessage>
Copy 
<?xml version="1.0" encoding="UTF-8"?>
<SNXSerialNumberTransferResponseMessage xmlns="urn:tracelink:mapper:sl:serial_number_exchange"
    xmlns:cmn="urn:tracelink:mapper:sl:commontypes" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <ControlFileHeader>
        <cmn:FileSenderNumber>8779891013658</cmn:FileSenderNumber>
        <cmn:FileReceiverNumber>8888884043540</cmn:FileReceiverNumber>
        <cmn:FileControlNumber>20200814063032014</cmn:FileControlNumber>
        <cmn:FileDate>2020-08-14</cmn:FileDate>
        <cmn:FileTime>06:32:32Z</cmn:FileTime>
    </ControlFileHeader>
    <MessageBody>
        <cmn:Quantity>5</cmn:Quantity>
        <cmn:SerialNumberList>
            <cmn:SerialNumber>00008820210000260003</cmn:SerialNumber>
            <cmn:SerialNumber>00008820210000260010</cmn:SerialNumber>
            <cmn:SerialNumber>00008820210000260027</cmn:SerialNumber>
            <cmn:SerialNumber>00008820210000260034</cmn:SerialNumber>
            <cmn:SerialNumber>00008820210000260041</cmn:SerialNumber>
        </cmn:SerialNumberList>
    </MessageBody>
</SNXSerialNumberTransferResponseMessage>

Errors

Element Error message Description
Class 1
cmn:NumberEncoding NumberEncoding is not one of the allowed enumeration values!!! This element must be specified as one of the valid values.
cmn:ObjectIdentifier Only one choice element must be populated: CompanyPrefixObjectKey or GTIN-14 or cmn:CNSubtypeObjectKey or cmn:NTINObjectKey !!! Exactly one of the company prefix, GTIN-14, CN-Subtype, or NTIN must be 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.
cmn:SerialNumberList Only SerialNumberList should be populated !!! This element must have a value specified.
At least one SerialNumber must be present in SerialNumberList !!! This element must have a value specified.
Class 2
N/A Original snx transfer [request ID] not found. The error occurs if the message body request ID for the original Serial Number Exchange  transfer is not found.
N/A processTransferResponse: Expected [expected quantity of serial numbers] serial numbers but found [actual quantity of serial numbers] ...perhaps they are still being persisted to the SOM repo. The total number of serial numbers identified by in the request are not available for transfer from the original location.
cmn:FileSenderNumber or cmn:FileReceiverNumber Unable to find product entry record for pool id [pool ID]. TraceLink cannot find the pool of serial numbers at this company for the packaging code entered.
Unable to find active product pool for serviceId [app ID], snType [packaging code type], packagingCode [packaging code value], filtervalue [filter value]. TraceLink cannot find the pool of serial numbers at this company or the Partner company for the packaging code or filter value entered.
cmn:FileReceiverNumber serviceDestinationCompanyID not specified. This element must have a value specified.
cmn:PackagingItemCode Serial Number Transfer failed. No serial numbers in [valid state (i.e. "encoded")] state were found for Packaging Item Code [packaging code] and Reference Document [reference document]. Serial numbers must be in the encoded state to successfully transfer by packaging code and reference documents.
Transfer to Recipient [transfer to location] does not have Serial Number Profile configured for [packaging code type] [packaging code value]. The packaging code must be configured in the recipient's Serial Number Exchange Profile.
PackagingItemCode value cannot be empty. This element must have a value specified.
PackagingItemCode type must have a valid value. This element must be specified as one of the valid values.
Serial Number Transfer for encoding serial numbers by Packaging Item Code [packaging code] and Reference Document [reference documents] did not find the expected number of serial numbers. Perhaps the encoding has not yet completed. The total number of serial numbers provisioned at the current location and identified by the specified packaging code and reference documents are not available for transfer.
No SNX Messages found for Packaging Item Code [value] [type] and Reference Document [reference ID]. Perhaps the upstream operation has not yet completed. No request exists yet to transfer the specified packaging code and reference document.
@codeLevel Master Data Code Level is invalid value! This element must be specified as a valid value in Product Master Data.
cmn:Serial Cannot perform operation on serial number [serial number] with serial number state [invalid serial number state]. This operation can only be performed when the serial number is [reserved or encoded]. The serial number must be in a reserved or encoded state.
No serial numbers specified. This element must have a value specified.
cmn:SNTransferToLocation Unable to find Recipient Company [company ID]. TraceLink cannot find the transfer to company or location based on the identifier provided.
Transfer to recipient [company ID] does not have Serial Number Profile configured for [packaging code type] [packaging code value]. The transfer to company or location does not have a Serial Number Exchange profile configured for the specified packaging code.
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.