Market release APIs

Why do I use these messages?

Use the following messages to set the status for a full or partial lot to Market Released to indicate that the items are ready for circulation in Russian market.

Which report do these messages generate?

These messages generate the 342 - Release in Circulation report in the Russia Compliance application if their contents meet the report conditions.

Market Release (XML)

Message Type: SOM_MARKET_RELEASE

Info Exchange Display Name: Market Release

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
som:SOMMarketReleaseMessage [1...1]
[-]		 - Required. Root element of message
  som:ControlFileHeader [1...1]
[-]		 - Required. The message document's header information.
    cmn:FileSenderNumber [1...1]
[1/20]		 String Required. The company identifier of the file’s sender. *1
    cmn:FileReceiverNumber [1...1]
[1/20]		 String Required. The company identifier of the file’s recipient. *2
    cmn:FileControlNumber [1...1]
[1/*]		 String Required. The message’s unique file control ID number. A file control ID number is mandatory for all messages. *3
    cmn:FileDate [1...1]
[10/10]		 Date Required. The date that the message is sent in YYYY-MM-DD format. Date and times must be in GMT. *4
    cmn:FileTime [1...1]
[8/8]		 Time Required. Time file generated in XML in HH:MM:SSZ format. The system expects the Z to be appended; however, if it is not included, the system assumes that the time is GMT and therefore appends the Z. *5
  som:MessageBody [1...1]
[-]		 - Required. The message document's header information.
    cmn:EventLocation [0...1]
[0/*]		 String

Business or location identifier for the facility or warehouse scoping the Market Release status update for the serial numbers matching the specified item code and lot number. *6

If the location is omitted, the Market Release status update is applied globally to all matching serial numbers in TraceLink.
    cmn:EventLocationType [0...1]
[0/*]		 String Conditionally required if cmn:EventLocation is present. Business or location type for the entity scoping the Market Release status. *7

See the BusinessAndLocationId enumeration list for valid values.
    choice%1 [-]
[-]		 Choice

Required. One and only one of the following item code data elements may be present at a time:

  • cmn:InternalMaterialCode
  • cmn:PackagingItemCode
  • cmn:CountryDrugCode
    cmn:InternalMaterialCode [0...1]
[0/*]		 String Conditionally required if both cmn:PackagingItemCode and cmn:CountryDrugCode are empty or null. Updates the status of the serialized items with the associated internal material code to Market Release. *8

Specifying an internal material code updates all serial numbers at all packaging levels (e.g. item, case) that are linked to the internal material number and the specified lot number.
    cmn:PackagingItemCode [0...1]
[0/*]		 String Conditionally required if both cmn:InternalMaterialCode and cmn:CountryDrugCode are empty or null. Updates the status of the serialized items with the associated packaging level item code to Market Release. *9

Specifying a packaging item code updates all serial numbers that are linked to only the specified packaging item code and lot number.
      @type [0...1]
[0/*]		 String Required. Packaging item code type. *10

See the ItemCode enumeration list for valid values.
    cmn:CountryDrugCode [0...1]
[1/*]		 String Conditionally required if both cmn:InternalMaterialCode and cmn:PackagingItemCode are empty or null. Updates the status of the serialized items with the associated national drug code to Market Release. *11

Specifying a country drug code updates all serial numbers at all packaging levels that are linked to the country drug code and the specified lot number.
      @type [1...1]
[1/*]		 String Required. The country drug code type. *12

See the CountryDrugCode enumeration list for valid values.
    cmn:LotNumber [1...1]
[1/*]		 String Required. The lot number associated with cmn:InternalMaterialCode, cmn:PackagingItemCode, or cmn:CountryDrugCode used to identify the serial numbers to be updated. *13
    cmn:NumberList [0...1]
[-]		 - Groups list of serial numbers.
      cmn:Serial [1...*]
[1/*]		 String Required. Serial number expressed in the GS1 Application Identifier format without parentheses for the AI keys. AI(01)(21) formatted serial number for GTINs or AI(00) formatted serial number for SSCCs. Express non-GS1 serial numbers (e.g. CN-EDMC) in native format. *14
    cmn:TransactionIdentifier [0...*]
[0/*]		 String The transaction identifier associated with the released product. This may be a certificate or declaration of conformity. *15
      @type [1...1]
[1/*]		 String Required. The transaction identifier type for the market release.

Valid values: *16

  • CIVILCIRCULATION
  • STATECONFIRMATION
      @date [0...1]
[0/*]		 Date The transaction identifier date attribute. *17
    cmn:EventDateTime [0...1]
[0/*]		 DateTime Timestamp of the date and time of the product release with the UTC time zone indicator in YYYY-MM-DDThh:mm:ss.ssZ format. *18
    cmn:MarketCountryCode [1...1]
[1/*]		 String Required. The 2 character ISO code for the market country. *19

See the ISOCountryCode enumeration list for valid values.
    cmn:ProductionQuantity [0...*]
[-]		 - Looping production quantity group.
      choice%1 [1...1] Choice Required. Either cmn:PackagingItemCode or cmn:CompanyPrefix must be present.
      cmn:PackagingItemCode [0...1]
[0/*]		 String Conditionally required if cmn:CompanyPrefix is empty or null. Identifies the product using the packaging level item code configured in Product Master Data. *20
        @type [0...1]
[0/*]		 String Required. Packaging item code type.

Valid values: *21

  • CN-RESCODE
  • GTIN-14
      cmn:CompanyPrefix [0...1]
[0/*]		 String Conditionally required if cmn:PackagingItemCode is empty or null. The GS1 company prefix for the released product. *22
      cmn:PackagingLevel [1...1]
[1/*]		 String Required. The packaging level of the commissioned item. *23

See the PackagingLevel enumeration list for valid values.
      cmn:QuantityReported [1...1]
[-]		 Integer Required. Quantity reported for the released product. *24 

<?xml version="1.0" encoding="UTF-8"?>
<som:SOMMarketReleaseMessage xmlns:som="urn:tracelink:mapper:sl:serialized_operations_manager" xmlns:cmn="urn:tracelink:mapper:sl:commontypes">
  <som:ControlFileHeader>
    <cmn:FileSenderNumber>8888882028644</cmn:FileSenderNumber>
    <cmn:FileReceiverNumber>8888882028677</cmn:FileReceiverNumber>
    <cmn:FileControlNumber>20200121065245</cmn:FileControlNumber>
    <cmn:FileDate>2020-03-31</cmn:FileDate>
    <cmn:FileTime>06:52:45.02Z</cmn:FileTime>
  </som:ControlFileHeader>
  <som:MessageBody>
    <cmn:EventLocation>0333331013655</cmn:EventLocation>
    <cmn:EventLocationType>GLN</cmn:EventLocationType>
    <!-- <cmn:InternalMaterialCode>100253</cmn:InternalMaterialCode> -->
    <cmn:PackagingItemCode type="GTIN-14">50300694220667</cmn:PackagingItemCode>    
    <!-- <cmn:CountryDrugCode type="DE_PPN">123451234009</cmn:CountryDrugCode> -->
    <cmn:LotNumber>B234567</cmn:LotNumber>
    <cmn:NumberList>
      <cmn:Serial companyPrefix="50882025" format="AI(01)+AI(21)">015088202501033321100000060001</cmn:Serial>
      <cmn:Serial companyPrefix="50882025" format="AI(01)+AI(21)">015088202501033321100000060002</cmn:Serial>
      <cmn:Serial companyPrefix="50882025" format="AI(01)+AI(21)">015088202501033321100000060003</cmn:Serial>
      <cmn:Serial companyPrefix="50882025" format="AI(01)+AI(21)">015088202501033321100000060004</cmn:Serial>
    </cmn:NumberList>
    <cmn:TransactionIdentifier type="CIVILCIRCULATION" date="2020-03-30">9857462156</cmn:TransactionIdentifier>
    <cmn:EventDateTime>2020-03-31T06:30:32.12Z</cmn:EventDateTime>
    <cmn:MarketCountryCode>RU</cmn:MarketCountryCode>
    <cmn:ProductionQuantity>
      <cmn:PackagingItemCode type="GTIN-14">50300694220667</cmn:PackagingItemCode>      
      <!-- <cmn:CompanyPrefix>503006</cmn:CompanyPrefix> -->      
      <cmn:PackagingLevel>EA</cmn:PackagingLevel>
      <cmn:QuantityReported>1000</cmn:QuantityReported>
    </cmn:ProductionQuantity>
  </som:MessageBody>
</som:SOMMarketReleaseMessage>

Data Element Error Message Description
Class 1
cmn:InternalMaterialCode Only one of either InternalMaterialCode or PackagingItemCode or CountryDrugCode must be present in source !!! The error occurs if cmn:PackagingItemCode, cmn:CountryDrugCode, and the source are all empty or null, or if more than one is present.
cmn:PackagingItemCode Only one of either InternalMaterialCode or PackagingItemCode or CountryDrugCode must be present in source !!! The error occurs if cmn:InternalMaterialCode, cmn:CountryDrugCode, and the source are all empty or null, or if more than one is present.
cmn:CountryDrugCode Only one of either InternalMaterialCode or PackagingItemCode or CountryDrugCode must be present in source !!! The error occurs if cmn:InternalMaterialCode, cmn:PackagingItemCode, and the source are all empty or null, or if more than one is present.
cmn:PackagingItemCode | @type Valid packaging item code type is required !!! The error occurs if cmn:PackagingItemCode is present but the source is empty or null, or is not a valid value from the enumeration list
cmn:CountryDrugCode | @type Country drug code type is required !!! The error occurs if cmn:CountryDrugCode is present but the source is empty or null, or is not a valid value from the enumeration list.
cmn:LotNumber Lot number is required !!! The error occurs if the source is empty or null.
cmn:TransationIdentifier | @type Valid transaction identifier type is required if TransactionIdentifier is populated !!! The error occurs if the source is empty or null, or does not equal CIVILCIRCULATION or STATECONFIRMATION.
cmn:MarketCountryCode Valid ISO market country code is required !!! The error occurs if the source is empty or null, or is not a valid value from the enumeration list.
cmn:PackagingItemCode Only one of either packaging item code or company prefix may be present !!! The error occurs if both cmn:CompanyPrefix and the source are empty or null, or if both are present.
cmn:PackagingItemCode | @type Valid packaging item code type is required !!! The error occurs ifcmn:PackagingItemCode is present but the source is empty or null, or is not a valid value from the enumeration list
cmn:CompanyPrefix Only one of either packaging item code or company prefix may be present !!! The error occurs if both cmn:PackagingItemCode and the source are empty or null, or if both are present.
cmn:PackagingLevel Valid packaging level code required !!! The error occurs if the source is empty or null, or is not a valid value from the enumeration list.
Class 2
cmn:LotNumber Lot [LotNumber] for item <item code type> <item code value> does not contain any serial numbers. The error occurs if no serial numbers exist in the specified lot.
Lot [LotNumber] for item [item code type] [item code value] does not exist. The error occurs if TraceLink cannot find the specified lot number associated with the specified item.
cmn:MarketCountryCode [TargetMarket] is not a defined target market for this product. The error occurs if the source is not defined for the specified product.
cmn:QuantityReported Market Release transaction processing failed due to serial number quantity verification failure. [quantity of commissioned serial number] at [packaging level] level found in the system but Market Release message reported lower quantity [QuantityReported] for [country drug code/Internal Material Number ] [Product name in English if English is not available use the first language available alphabetically by language code] [packaging code /type] at [location]. The error occurs if there are more serial numbers in the lot than were specified in the source.
Market Release transaction processing failed due to serial number quantity verification failure. [quantity of commissioned serial number] at [packaging level] level found in the system but Market Release message reported higher quantity [QuantityReported] for [country drug code/Internal Material Number ] [Product name in English if English is not available use the first language available alphabetically by language code] [packaging code /type] at [location]. The error occurs if there are fewer serial numbers in the lot than were specified in the source.
cmn:Serial Serial Number [SerialNumber] does not exist. The error occurs if the specified serial number does not exist within TraceLink.
Serial number [SerialNumber] is not commissioned. The error occurs if the specified serial number is not commissioned.
Serial Number [SerialNumber] is not associated with Item Code [SerialNumber] and Lot Number [SerialNumber]. The error occurs if the specified serial number is not associated with the specified item code or lot number.
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.

Market Release (SOAP)

Guidelines

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.

The following data is sent in the request to TraceLink:

Data Element Occurs
Length		 Type Description
soapenv:Envelope [1...1]
[-]		 - Required. SOAP envelope root element.
  soapenv:Header [1...1]
[-]		 - Required. Not used.
  soapenv:Body [1...1]
[-]		 - Required. SOAP message body.
    urn:MarketRelease [1...1]
[-]		 - Required. Queries the status of the specified lot.
      PackagingCode [0...1]
[1/*]		 String Conditionally required if both InternalMaterialCode and CountryDrugCode are empty or null. Packaging level item code. *25
      PackagingType [0...1]
[1/*]		 String Conditionally required if PackagingCode is present. Identifies the packaging level item code type. *26

See the PackagingItemCodeType enumeration list for valid values.
      InternalMaterialCode [0...1]
[1/*]		 String Conditionally required if both PackagingCodeand CountryDrugCode are empty or null. Identifies the product using the internal item code configured in Product Master Data. *27
      CountryDrugCode [0...1]
[1/*]		 String

Conditionally required if both PackagingCodeand InternalMaterialCode are empty or null. Country drug code associated with the specified lot. *28
      CountryDrugCodeType [0...1]
[1/*]		 String Conditionally required if CountryDrugCode is present. Country drug code type. *29

See the CountryDrugCode enumeration list for valid values.
      Lot [1...1]
[1/*]		 String Required. Lot number for the market release. *30
      Items [0...1]
[-]		 - List of one or more serial numbers to release. Use for only a partial lot market release.
        Item [1...*]
[-]		 - Required. The serial number to release into circulation.
          @sn [1...1]
[1/*]		 String

Required. Serial number in one of the following formats:

AI(01)+AI(21)

  • Format: 01 + [GTIN_14] + 21 + [serial number]
  • Example: 015088202503022521100000090109

AI(00)

  • Format: 00 + [SSCC18]
  • Example: 00008820200000047506

CN-EDMC

  • Format: 20-digit China EDMC code
  • Example: 81530070000022519351
      TargetMarketCountryCode [1...1]
[1/*]		 String Required. The two character ISO country code for the market country. *31

See the ISOCountryCode enumeration list for valid values.
      EventDateTime [0...1]
[-]		 Date Date and time of the market release, in GMT YYYY-MM-DDTHH:MM:SSZ format. *32

If omitted, TraceLink uses the current date and time.
      EventLocation [0...1]
[1/*]		 String Site level location where the event occurs. Defaults to company level SGLN. SGLN format is numeric component only, with urn prefix stripped (e.g. 8888882.02867.0 instead of urn:epc:id:sgln:8888882.02867.0 typically found in EPCIS events). *33
        @identifierType [1...1]
[1/*]		 String Required. The event location identifier type. *34

See the BusinessAndLocationId enumeration list for valid values.
        @identifierValue [1...1]
[1/*]		 String Required. The event location value.
      Transactions [0...1]
[-]		 - List of one or more transaction identifiers.
        Transaction [1...*]
[-]		 - Required. The transaction identifier associated with the market release.
          ItemID [0...1]
[1/*]		 String Required. The transaction identifier associated with the status update, for regulatory reporting and business tracking purposes. *35
          ItemType [0...1]
[1/*]		 String Required. The transaction identifier type. *36

Valid values:

  • CIVILCIRCULATION – Number of the document from a government agency for introduction of medicine into circulation used for immunobiological medicine only.
  • STATECONFIRMATION – Number of the document confirming the medicine compliance with state registration requirements.
          Date [0...1]
[1/*]		 String The date of the transaction in YYYY-MM-DD format. *37
      ProductionQuantities [0...1]
[-]		 - Group of ProductionQuantity values for each packaging level in the hierarchy. Use to optionally validate serial number quantities.
        ProductionQuantity [0...*]
[-]		 - List of each aggregation hierarchy level.
          ItemType [0...1]
[-]		 - Conditionally required if CompanyPrefix is empty or null. Identifies the product using the packaging level item code (e.g. GTIN-14) configured in Product Master Data.
            ItemCodeType [1...1]
[1/*]		 String

Required. Packaging item code type. *38

Valid values:

  • CN_SUB_TYPE
  • GTIN_14
  • NTIN
            ItemCode [1...1]
[1/*]		 String Required. Packaging level item code value. *39
          CompanyPrefix [0...1]
[0/*]		 String

Conditionally required if PackagingItemCode is empty or null. GS1 company prefix. *40
          PackagingLevel [1...1]
[1/*]		 String Required. The packaging level of the commissioned item. *41

See the PackLevel enumeration list for valid values.
          QuantityReported [1...1]
[1/*]		 Integer Required. Quantity report for the released product. *42

Example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:tracelink:soap">				
    <soapenv:Header/>				
    <soapenv:Body>				
        <urn:MarketRelease>				
            <CountryDrugCode>08620081794</CountryDrugCode>		
            <CountryDrugCodeType>US_NDC542</CountryDrugCodeType>		
            <LotNumber>GO3612OCNQX2</LotNumber><SerialNumberList/>		
            <Transactions>		
                <Transaction>	
                    <ItemType>CIVILCIRCULATION</ItemType>	
                    <ItemID>1234</ItemID>	
                    <Date>2020-03-27</Date>	
                </Transaction>	
                <Transaction>	
                    <ItemType>STATECONFIRMATION</ItemType>	
                    <ItemID>4321</ItemID>	
                    <Date>2020-03-27</Date>	
                </Transaction>	
            </Transactions>		
            <MarketCountryCode>RU</MarketCountryCode>		
            <ProductionQuantities>		
                <ProductionQuantity>	
                    <ItemType>	
                        <ItemCodeType>GTIN_14</ItemCodeType>
                        <ItemCode>78708865247189</ItemCode>
                    </ItemType>	
                    <PackagingLevel>EA</PackagingLevel>	
                    <QuantityReported>5</QuantityReported>	
                </ProductionQuantity>	
                <ProductionQuantity>	
                    <CompanyPrefix>9876</CompanyPrefix>	
                    <PackagingLevel>CA</PackagingLevel>	
                    <QuantityReported>1</QuantityReported>	
                </ProductionQuantity>	
            </ProductionQuantities>		
        </urn:MarketRelease>		
    </soapenv:Body>
</soapenv:Envelope>

Errors

Exception Code Exception Message
VALIDATION Serial Number <SerialNumber> does not exist.
VALIDATION Serial number <SerialNumber> is not commissioned.
VALIDATION Serial Number <SerialNumber> is not associated with Item Code <ItemCode> and Lot Number <LotNumber>
VALIDATION Lot <LotNumber> for item <item code type> <item code value> does not contain any serial numbers.
VALIDATION Lot <LotNumber> for item <item code type> <item code value> does not exist.
VALIDATION <TargetMarket> is not a defined target market for this product
VALIDATION Market Release transaction processing failed due to serial number quantity verification failure. [quantity of commissioned serial number] at [packaging level] level found in the system but Market Release message reported lower quantity [QuantityReported] for [country drug code/Internal Material Number ] [Product name in English if English is not available use the first language available alphabetically by language code] [packaging code /type] at [location].
VALIDATION Market Release transaction processing failed due to serial number quantity verification failure. [Quantity of commissioned serial number] at [packaging level] level found in the system but Market Release message reported higher quantity [QuantityReported] for [country drug code/Internal Material Number ] [Product name in English if English is not available use the first language available alphabetically by language code] [packaging code /type] at [location].

Guidelines

The following data is included in the message response:

Data Element Occurs
Length		 Type Description
S:Envelope [1...1]
[-]		 - Required. SOAP envelope root element.
  S:Body [1...1]
[-]		 - Required. SOAP message body.
    ns2:MarketReleaseResponse [1...1]
[-]		 - Required. Market Release response message.
      TLResponse [0...1]
[-]		 - Required. Response.
        Success [0...1]
[-]		 Boolean Required. Indicates if the Market Release request message was processed successfully. *43
        ExceptionReturn [0...1]
[-]		 - Conditionally required if Success = false. Error information if the request failed.
          CallException [1...*]
[-]		 - Required. Contains error details.
            ExceptionCode [0...1]
[0/*]		 String Required. Error Code.
            ExceptionMessage [0...1]
[0/*]		 String Message that further describes the error condition, if available.

Example

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
    <S:Body>
        <ns2:MarketReleaseResponse xmlns:ns2="urn:tracelink:soap" xmlns:ns3="http://tracelink.com/som">
            <TLResponse>
                <Success>true</Success>
            </TLResponse>
        </ns2:MarketReleaseResponse>
    </S:Body>
</S:Envelope>