Serial number syncing APIs

Producers can configure rules to determine how serial number information (i.e. serial number, packaging code, lot, and expiration date) and the relevant status of that information (i.e. serial number status, item status, and attribute) syncs from Serialized Operations Manager to Product Information Manager. This syncing helps ensure serial number information remains up to date in the Product Directory without manually maintaining serial number information.

Serialized Operations Manager sync rules can also be set in the Web UI.

Set Serialized Operations Manager Sync Rules (REST)

Producers use this call to create or update a rule for automatically syncing serial number information (i.e. serial number, packaging code, lot, and expiration date) and the relevant status of that information (i.e. serial number status, item status, and attribute) located in Serialized Operations Manager to Product Information Manager.

Guidelines

Product Information Exchange validates sync rules in the following order:

  1. If targetMarketCountryCode = ALL and there are existing rules with a different target market defined, Product Information Exchange returns a 400 HTTP response.
  2. If targetMarketCountryCode equals any target market and an existing rule has the targetMarketCountryCode set to ALL, Product Information Exchange returns a 400 HTTP response.
  3. If there is an existing rule with the given targetMarketCountryCode, Product Information Exchange updates the existing rule's item status.
  4. If validation rules 1-3 are false, Product Information Exchange creates a new sync rule.

Multiple sync rules cannot apply to the same target market. If targetMarketCountryCode = ALL, no other sync rules can be created for a specific target market.

Element Type Description
records Array Required. A list of target market country codes and item statuses that define the Serialized Operations Manager sync rules.
  targetMarketCountryCode String Required. Indicates one or all (i.e. ALL) target markets. See Country Code for valid values.

ALL is a valid value. Use this to set a sync rule for all target markets the Producer supports in Serialized Operations Manager.
  itemStatuses Array

Required. A list of one or more item statuses. The value determines which new records are sent to Product Information Manager (Product Verification) for processing and storage. Valid values:

  • AVAILABLE – Item is available for picking.
  • BLOCKED – Item is unavailable for picking.
  • PENDING_RECEIPT – Item is pending receipt confirmation at the receiving location.
  • PICKED – Item has been picked.
  • RECEIVED – Item has been received.
  • SHIPPED – Item has been shipped.
  • UNDER_INVESTIGATION – Item is under investigation, e.g. because of a suspect product investigation or for product quality or condition issue.

If a value is not specified, this element defaults to AVAILABLE.

Example

{
    "t": {
        "v": 1,
        "m": "pie--set-som-custom-sync-rules--v1",
        "app-id": "393C3176-6F7C-438D-B06F-DDCDA21C2E5C"
    },
    "p": {
        "records": [
            {
                "targetMarketCountryCode":"US",
                "itemStatuses": [
                    "AVAILABLE", 
                    "PICKED"
                ]
            },
            {
                "targetMarketCountryCode":"PR",
                "itemStatuses": [
                    "AVAILABLE"
                ]
            },
            {
                "targetMarketCountryCode":"UM",
                "itemStatuses": [
                    "SHIPPED"
                ]
            }
        ]
    }
}

Guidelines

Element Type Description
targetMarketCountryCodes Array Required. A list of target market country codes with Serialized Operations Manager sync rules. See Country Code for valid values.

ALL is a valid value and indicates a sync rule for all target markets the Producer supports in Serialized Operations Manager.

Example

{
    "t": {
        "v": 1,
        "m": "pie--set-som-custom-sync-rules-response--v1",
        "app-id": "393C3176-6F7C-438D-B06F-DDCDA21C2E5C"
    },
    "p": {
        "targetMarketCountryCodes": ["US", "PR", "UM"]
    }
}

Query Serialized Operations Manager Sync Rules (REST)

Producers use this call to query for their Serialized Operations Manager sync rules. Producers establish sync rules to facilitate the syncing of data between Serialized Operations Manager and Product Information Manager. Sync rules are set in the Set Serialized Operations Manager Sync Rule API.

Guidelines

Element Type Description
query-metadata Array Required. A list containing the maximum limit of records returned and possible fields.
  control Object Required. The set of controls determining how to return the result set.
    limit Integer Sets the maximum number of records in the query response.
    query-token String A token available in the query response. The query token can be used in a new request to return the next set of results when more than one page of results are available.
  select Object The information about the filters that can be applied to a query.
    fields Array Each field has a name and an expression that indicates the value being queried.
      name String The name of the field to retrieve.
      expression String The expression indicating the field to retrieve (e.g. $.itemStatuses).
query-filter String A list containing possible query filters.
  targetMarketCountryCodes Array A list of target market country codes identifying the Serialized Operations Manager sync rules to retrieve. See Country Code for valid values.

Example

{
    "t": {
        "v": 1,
        "m": "pie--query-som-custom-sync-rules--v1",
        "app-id": "393C3176-6F7C-438D-B06F-DDCDA21C2E5C"
    },
    "p": {
        "query-metadata": {
            "control": {
                "limit": 100
            },
            "select": {
                "name": "itemStatuses"				
            }
        },
        "query-filter": {
            "targetMarketCountryCodes": ["US"]		
        }
    }
}

Guidelines

Element Type Description
query-metadata-response Array The array containing the maximum limit of records returned and possible fields.
  control String The information about the number of records that can be returned per query.
    total-results Integer The total number of results from the query request.
    limit Integer Indicates the maximum number of records that can be returned per query.
    query-token String A token available in the query response. The query token can be used in a new request to return the next set of results when more than one page of results are available.
  results Array A list of one or more target market country codes with Serialized Operations Manager sync rules. The initial query determines the results in this response.
    targetMarketCountryCode Enum Required. target market country code. See Country Code for valid values.
    itemStatuses Array

A list of one or more item statuses. The value determines which new records are sent to Product Verification for processing and storage. Valid values:

  • AVAILABLE – Item is available for picking.
  • BLOCKED – Item is unavailable for picking.
  • PENDING_RECEIPT – Item is pending receipt confirmation at the receiving location.
  • PICKED – Item has been picked.
  • RECEIVED – Item has been received.
  • SHIPPED – Item has been shipped.
  • UNDER_INVESTIGATION – Item is under investigation, e.g. because of a suspect product investigation or for product quality or condition issue.

If a value is not specified, this element defaults to AVAILABLE.

Example

{
    "t": {
        "v": 1,
        "m": "pie--query-som-custom-sync-rules-response--v1",
        "app-id": "393C3176-6F7C-438D-B06F-DDCDA21C2E5C",
        "cid": "11d135c7-bf91-4171-95dc-cbd5afeb622c"
    },
    "p": {
        "query-metadata-response": {
            "control": {
                "total-results": 1,
                "limit": 100,
                "query-token": "lbv114"
            }
        },
        "results": [
            {
                "targetMarketCountryCode":"US",
                "itemStatuses": [
                    "AVAILABLE", 
                    "PICKED"
                ]
            }			
        ]
    }
}

Delete Serialized Operations Manager Sync Rules (REST)

Producers use this call to delete one or more existing Serialized Operations Manager sync rules, which disables the automatic synchronization of serial number information (i.e. serial number, packaging code, lot, and expiration date) and its relevant status (i.e. serial number status, item status, and attribute) located in Serialized Operations Manager with Product Information Manager for the specified target markets.

Guidelines

Element Type Description
targetMarketCountryCodes Array

Required. A list of target market country codes that define the Serialized Operations Manager sync rules. Indicates one, multiple, or all (i.e. ALL) target markets. See Country Code for valid values.

ALL is a valid value. Use this value to delete the sync rule with a target market of ALL.

Example

{
    "t": {
        "v": 1,
        "m": "pie--delete-som-custom-sync-rules--v1",
        "app-id": "393C3176-6F7C-438D-B06F-DDCDA21C2E5C"
    },
    "p": {
        "targetMarketCountryCodes": ["UM"]
    }
}

Guidelines

Element Type Description
targetMarketCountryCodes Array Required. A list of target market country codes indicating the deleted Serialized Operations Manager sync rules.

Example

{
    "t": {
        "v": 1,
        "m": "pie--delete-som-custom-sync-rules-response--v1",
        "app-id": "393C3176-6F7C-438D-B06F-DDCDA21C2E5C"
    },
    "p": {
        "targetMarketCountryCodes": ["UM"]
    }
}