About integration with fmcgProducts and fmcgProductsIntegrator
Methods.
fmcgProducts supports integration of product data with other systems using a web services API (JSON/XML), FTP and mail-in.
File types.
In addition to JSON/XML, fmcgProducts can process text files (comma separated or column formatted) and Excel files.
Field types.
fmcgProducts can send and receive the following field types.
- GDSN 3.1 fields "Dxxxx", e.g. EAN/GTIN (D8165), Product name (D8258) etc.
- Own fields "Exxxx", e.g. assortment, product category fields etc. that you want to "control" in fmcgProducts, e.g. in relation to assortment overviews, product category overviews, Excel extracts, integration with other systems, etc.
- System fields "Xxxxx", e.g. X9000 "Ready for GS1" which makes it possible to control synchronization of product data with GS1 (should the product be synchronized with GS1 if it is "GS1 valid" or not).
- Other fields that are "mapped" to known fields in fmcgProducts.
History.
Regardless of the method used to integrate and update fmcgProducts, all transactions and changes will be recorded on the individual product unit. The specific history for the individual product unit can be viewed by selecting "Show product history" from the user interface on the individual product.
Mail-In.
fmcgProducts can receive text files (comma separated or column formatted) as well as Excel files via mail-in. fmcgProducts can be configured so that only specific sender addresses are allowed to email files to fmcgProducts for updating.
Integration without "mapping".
fmcgProducts can load an MS Excel spreadsheet directly (without mapping) provided the Excel import syntax is followed. Correct syntax is field type/number in the first row and that the GDSN 3.1 standard is used in relation to keywords - example:
If the product unit already exists in fmcgProducts (the unique key is "EAN/GTIN + target market (country code)), the product unit is updated in fmcgProducts. If "EAN/GTIN + target market" is not found in fmcgProducts, a new product unit is created in fmcgProducts.
If the syntax is not respected, e.g. in case of missing Ean/GTIN in column A, the field indicated in the first row does not exist fmcgProducts, use of an invalid keyword etc., the relevant row is skipped (product) and an attempt is made to load the next row (product).
For every loading of product data into fmcgProducts, a loading report is generated which shows exactly which rows (products) have been loaded correctly and which rows (products) have not been loaded due to syntax errors. The exact cause of syntax errors is indicated in the loading report (field does not exist, invalid keyword etc.).
It is possible to set up fmcgProducts so that the loading report is emailed to one or more email addresses in continuation of a loading to fmcgProducts.
Integration with "mapping".
fmcgProducts contains a "mapping module" which makes it possible to import and export files (comma-separated or column-formatted text file) to/from fmcgProducts.
Provided that "EAN/GTIN + target market" is specified correctly anywhere in the import file, it is possible to map all fields from the import file, i.e. position in the load file, to the corresponding fields in fmcgProducts.
If mapping, a number of functions can be performed at the same time - examples:
- Conversion (eg from KG to GRAM)
- Default fields (e.g. units of measurement, country codes, fixed values in fields, etc.)
- "one to several units" e.g. can one row be loaded from a text file, which subsequently forms the basis for updating/creating several product units (base-box-pallet)
Web services API (JSON)
The API has support for the following calls/end points.
General:
GET /api/: return system status on fmcgProducts.
GET /api/openapi: return documentation in OpenAPI format.
GET /api/openapi.json: return documentation in OpenAPI format as JSON.
One product/GTIN:
GET /api/status/<product id>: return the status of the product where the product id is GTIN.TargetMarket. Example: https://<customer instance>.fmcgproducts.dk/api/status/04005514026085.752
GET /api/details/<product id>?fields=D8256,D8258,D8245: return status and specific fields (the example returns the supplier's product number, the supplier's product name and GPC code).
GET /api/details/<product id>/<export profile>: return status and specific fields defined in the export profile.
POST /api/: creates/updates a product. The key is GTIN via field D8165 and target market via field D8255. Return response corresponds to /api/status/<product id>. In this way validation errors (GDSN and specific rules for the individual target markets) are returned.
With the field "test" set to true, testing can be done without creating/updating products, and the correct response will still be returned.
Input is case sensitive, so Dxxxx fields must be entered in uppercase letters.
Additional parameters:
- ?displayValues=true: Displays keyword value as translated value rather than as "technical" value.
Note: when using the export profile, this is determined based on the settings on the export profile itself.
Multiple products/GTINs.
GET /api/products/status: return the status of all products with the option to limit the number of products with fromdate, limit and offset.
GET /api/products/status?fromdate=01-01-2022: return the status of all products sent to GS1 since 1/1-2022.
GET /api/products/status?fromdate=01-01-2022&offset=25&limit=25: return the status of all products sent to GS1 since 1/1-2022, but use offset and limit to retrieve a subset (paging) .
A selection of multiple products/GTINs.
One or more selections can be defined based on some given criteria. The selection is saved in the customer instance under a "viewname", which is specified in the web API call. The API returns all the products that meet the given criteria. This allows you to define a number of selections, e.g. on selected suppliers (GLN = ??? OR GLN = ??? etc.), on GPC code and so on, which returns exactly the product data that is needed.
Examples:
GET /api/view/<view id>: Returns all products from the specified selection/view in JSON format.
GET /api/view/<view id>/xml: Returns all products from the specified selection/view in XML format.
GET /excel.xsp?request=view&viewname=<view id>&template=<excel template>: With "excel.xsp" and "&template=Excel" an Excel file is returned (with fields as specified in the Excel template <excel template> )
Additional parameters:
- &fieldnames: "gs1" can be specified, which returns gs1 field names, or other field names by agreement (corresponding to the field names used by the receiving system)
- &gridsToArray=true: Collects fields from the same grid in one JSON array rather than displaying the fields in a flat structure
- &allergensToBold=true: Indicates allergens in ingredient description D8179 in bold (with <b> and </b>) based on the allergen filter for the language in question for the product's target market
- &displayValues=true: Displays keyword value as translated value rather than as "technical" value
- &limit=<number>&offset<start from number>: Returns a number of products from the specified "offset" (paging)
- &modifiedsince=<minutes>: Returns the products in the relevant view/selection that have been modified within XXX minutes. It requires that the first column in the corresponding overview is either D8260 ("Last modified" date for GS1 fields) or X9101 ("Last modified" date for GS1 and own fields)
PDF.
GET /api/pdf/<product id>: retrieves product sheet as PDF for the product where product id is GTIN.TargetMarket. As a PDF template, the default for the device type in question is used.
GET /api/pdf/<product id>/<PDF template>: retrieves product sheet as PDF for the product where the product id is GTIN.TargetMarket.
GET /api/pdf/<item id>/<country>/<PDF template>: retrieves product sheet as PDF for the product with the specified item number (item id) from the specified target market.
GET /api/web/<product id>/<PDF template>: retrieves the product sheet as HTML for display directly in the browser for the product where the product id is GTIN.TargetMarket.
GET /api/web/<item id>/<country>/<PDF template>: retrieves the product sheet as HTML for display directly in the browser for the product with the specified item number (item id) from the specified target market.
In all cases "PDF template" is the name of the template or the ID of the template. If the name does not match, the PDF template which is the default for the device type in question is used.
Security.
The API is accessed with basic authentication.
fmcgProducts and fmcgProductsIntegrator are run in a duplicated server environment consisting of a cluster with servers distributed over 2 physical locations.
Nginx is used for distribution of HTTPS traffic and redirection in the event of a server failure.
As an alternative to basic authentication, all services can be locked to one or more IP addresses, and thus only the specified IP addresses have access to call the API.
Caching.
All calls to /api/ return an ETag HTTP header. The value in the ETag HTTP header must be sent back in subsequent calls to the API on the same request in an If-None-Match HTTP header in order to utilize caching and thus get faster responses if the data has not changed since the last call (conditional GET).
Limits/throttling.
The API has a limit of 90 requests/minute to limit the load on the backend servers. If the limit is exceeded, the API returns HTTP 429 "Too Many Requests".