Understanding the Request Engine

The Request Engine* enables you to ask for a specific set of products from your suppliers.
A request is a couple of product info + supplier Info: what do you ask and to whom do you ask.

Sending a request to a supplier will invite him to share with you the product -if already created on SupplierXM- or will invite him to create then share the product - if not created yet.

An up-to-date supplier reconciliation (via the supplier directory module) is the pre-requisite for sending requests. It is used to send your request to the adequate SupplierXM supplier organization.

You can import your data from your system to SupplierXM via a payload in JSON with the following format.

Please note that you need admin credentials to use this feature.

*formerly known as "Information Request"

Import format

Example of a payload:

{
  "products": [
    {
      "gtin": "03037494555003",
      "primaryInternalReference": "123abc",
      "supplierInternalId": "33223",
      "categoryId": "PS_1234_12345_xxx",
      "isRequested": true,
      "namePublicLong": [
        {
          "expressedIn": { "code": "fra-FR" },
          "data": "Hello, this is a requests!"
        }
      ]
    },
    {
      "gtin": "03149170388000",
      "primaryInternalReference": "456def",
      "supplierInternalId": "33223",
      "categoryId": "PS_1234_12345_xxx",
      "isRequested": false,
      "namePublicLong": [
        {
          "expressedIn": { "code": "fra-FR" },
          "data": "I am not requested"
        }
      ]
    }
  ]
}

Attributes

Attribute

Type

Comment

gtin

string - compulsory

The GTIN of the requested product.

supplierInternalId

string- compulsory

Your internal id for the supplier to whom you are requesting the product.

NB: corresponds to the internalID of one of your suppliers imported via the supplier directory.

primaryInternalReference

string - optional

Your internal reference for this product.

categoryId

string - optional

The short id of the category to which you want to link your product, if you are using a custom product hierarchy - also called retailer categories.

namePublicLong

string - optional

The name of the product.

isRequested

boolean - optional

true by default

Can be used to remove a product from your catalog:

  • True, your product is flagged as requested.
  • False, your product is not flagged as requested.

NB: a request should always be created with the attribute set to true.

Import results

The import results give both statuses of the entire import and of each product imported.

Some products can be imported onto SupplierXM successfully while some others will be KO for reasons detailed below.

status

Comment

SUCCESS

A product is considered as imported successfully when both GTIN and supplierInternalId where valid

EMPTY

Equals to SUCCESS. It means that every product imported was already existing. Nothing changed with the payload.

ERROR

See the troubleshooting section for error details

Maximum import size & API calls

Maximum number of requests imported per day: 50000

Maximum size of the body payload for API calls: 10Mo

It is strongly recommended to make batches of your payload in one call (or a few), rather than make one call for each request.
Making one call for several requests will ease your platform import dashboard readability and the management of the error report files.

Troubleshooting

Import error messages

Import type

Message

Description

Action

XLSX + JSON

Invalid check key

Importing a file with a GTIN not valid. The invalidity of a GTIN can come from many factors. (For instance, a character instead of a number or a GTIN with a size greater than 14).
GTIN cell is not in text format and is not interpreted well.

Check that the cell is in “text” format
Re-import the file with the corrected GTIN

XLSX + JSON

Missing key: <name_key>

The supplier has a mandatory field missing: <name_key>.

Fill it and re-import the file.

XLSX + JSON

Invalid type for key: . Expected <correct_type_field> got <wrong_type_field>

The field is not filled properly.

Change the type of this field to the one precised in the message: <correct_type_field>.

XLSX + JSON

Invalid data {} does not belong to the available attribute

A dynamic field is in the payload but this field is not available or not created for this organization.

Check the columns and their "attributes" names.

XLSX + JSON

Invalid data <name_field>. <error_msg>

A dynamic field cannot be casted. This is a type error, for example a string instead of an integer

Correct the value accordingly

XLSX + JSON

Invalid data <name_field>. {} is not a valid date expected format YYYY-MM-DD

a date field does not have the good format. This is a “cast” error.

Correct the value accordingly

XLSX + JSON

The token is not yet valid (nbf)

It is a technical problem caused by a desynchronization between the services clocks.

Contact support

XLSX + JSON

missing gtin

No gtin is given (and the row contains information for XLSX).

Add the missing GTINs

XLSX + JSON

GTIN-14 of a consumer unit or display unit must start with a '0'

Importing an IR with a GTIN-14 valid but not starting with 0.

XLSX + JSON

Invalid data: target market <tm_given> does not belong to the organization's target markets

The Target Market is not valid.

Put the Target Market set for the retailer organization (e.g. "250" for French Target Market)

XLSX + JSON

the type for attribute <name_dynamic_field> is not allowed

The field's type of <name_dynamic_field> is not available

Check that you are importing the good field. If you are, contact support

XLSX + JSON

attribute <name_dynamic_field> is not scoped as private for the retailer

<name_dynamic_field> is not configured for your retailer organization

Check that you are importing the good field. If you are, contact support

XLSX + JSON

some errors occured: supplier [name+ID] is reconciled with organizations [list of organization names+IDs] that all have the product [product GTIN]. Please check your reconciliation or contact SupplierXM

If one request sent to one supplier points towards several reconciled SupplierXM organizations that share the requested product.

As 1 product is requested, this error aims to warn the retailer to verify the reconciliation instead of sending back 2 products in the catalog.

This error can be solved on the retailer side by changing the Supplier Directory reconciliation so that the request is sent to a supplier that is only linked to one of the SupplierXM organizations that share the product.

This way the retailer will be able to request one, or all the duplicated products, through different Information Requests to different suppliers.

XLSX

Invalid file, mandatory columns are missing: <list_columns_missing>

Global error. It means that there is at least one mandatory column missing in the sheet.

Check the columns

JSON

JSONDecodeError('Expecting property % enclosed in double quotes:)

The imported JSON is not well formatted.

Check your file for example with a tool like the JSONFormatter online to correct the file

JSON

JSONDecodeError('Extra data: line 1 column 3 (char 2)',)

The imported JSON is not well formatted.

Check your file for example with a tool like the JSONFormatter online to correct the file

JSON

Invalid data: <name_key> missing language code

The key language code has no value for the key <name_key>

Check that the language code is valid, for example EN and not ZZ.

JSON

Invalid file format, missing key: products

The root key products is missing in the json file

Add the root key at the beginning of the file

JSON

Invalid data: <name_key> element is not a valid dict

<name_key> contains an element which is not a valid dict.

Check that every pair name/value is valid. The name must belong to the authorized list.