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: <field>. Expected <correct_type_field> got <wrong_type_field>	The field <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 { "h is reconciled with organizations ssage", "h-2": "Description" that all have the product "0-0": "XLSX +. Please check your reconciliation or contact the support	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.
XLSX + JSON	Invalid data: ers] { does not belong to the referential , "h-1": "Mess	The value you submitted does not belong to the referential, thus is not authorised. Please check that the value is authorised, and contact the support if you think that a value is missing.	Check that the value (the code) does belong to the referential. Contact the support if you think that a value is missing, so that the referential can be updated.
XLSX + JSON	You cannot import this data, as the product does not exist yet and you don’t have an active request for this product. If you want to request this product or pre-enrich it, please first request the product by setting “isRequested” to “true” in your import.	You are trying to import data for a product that is: not in your catalog not an active request -> You cannot enrich a product or a request that does not exist, hence the warning message.	2 solutions 1- Request the product (isRequested=true) so that the data is attached to the request and will be attached to the product once the latter will be created. 2- Wait for the product to be shared in your catalog to enrich it.