Updating External System Stock

Updating External System Stock with 4ws Suite Data

This documentation outlines the process of updating an external system's stock information based on daily CSV exports provided by the 4ws suite. The CSV file, which contains detailed stock information for various entities, is generated every day at 3 AM. Additionally, a service to retrieve delta stock updates every 15 minutes is available.

Actors

API Client: The system or user initiating the request.

4ws.trade: The backend system that processes the request.

Preconditions

The external system must have the necessary permissions and access to the document creation service, please refer to Authentication.

Pagination parameters cursor and nextCursor must be correctly configured in the request.

Sure! Here's the use case description in English, followed by the Mermaid process diagram representing the flow.

Daily and Incremental Stock Update for an E-commerce Platform

Objective

Ensure that the product stock repository of an e-commerce platform stays synchronized with the supplier’s inventory data by combining a full daily update with incremental updates throughout the day.

Workflow

1. Full Stock Sync (Daily)

Once per day, at a precise time when no order processing is ongoing (e.g., shortly after midnight), the e-commerce system downloads a full stock snapshot from the supplier. This is typically provided as a CSV file (you can retrive CSV file on FTP or by this API Get bulk CSV Export) and includes the current stock levels for all products in the catalog. The platform uses this file to:

Overwrite or reconcile the local stock repository,

Ensure a clean base state for the day,

Sanitize any previous mismatches or gaps.

Alternatively, the e-commerce platform may use the Get stock to pull the current stock for the full catalog or a specific subset (e.g., by category, brand, or SKU range). This method is flexible and supports structured, parameterized queries.

2. Incremental Stock Updates (Every 15 minutes)

To keep inventory updated in near real-time, the platform invokes the Get last stock every 15 minutes (or a custom interval). This API returns only the products whose stock levels changed since the last call.

It is critical that this call runs at regular intervals without gaps. Any missed invocation could result in lost stock change events, leading to inconsistencies.

Fallback for Recovery

In case of issues (e.g., network errors, missed updates, etc.), the platform can trigger a one-time call to the Get stock to fetch up-to-date stock data for the affected SKUs and correct any discrepancies.

Daily CSV File Format

The CSV file is exported daily at 3 AM and contains the following fields:

CSV Field	Description/Format
ENTITY_CODE	Entity code identifying the store or warehouse
ENTITY_DESCRIPTION	Description of the entity (store or warehouse)
ENTITY_TYPE	Type of entity: warehouse or store
ENTITY_CITY	Descriptive data of the entity
ENTITY_COUNTRY	ISO 2 code of the country
ENTITY_PROVINCE	ISO 2 code of the province
ENTITY_REGION	ISO 3 code of the region
ENTITY_ZIP_CODE
ITEM_CODE	Product code to which the stock level refers
ITEM_DESCRIPTION	Identifying description of the product to which the stock level refers
DIMENSION_TYPE1	Type 1 of the dimensional group that specifies the product (e.g., Size grid for the dimensional group related to sizes)
DIMENSION_LEVEL1	Identifying code of level 1 assigned to identify the product variant (e.g., the identifying code of the valid size for the dimensional group related to sizes)
DIMENSION_DESCRIPTION1	Descriptive description of level 1 assigned to identify the product variant (e.g., description of the valid size - S,M ... 36,37,..- for the dimensional group related to sizes)
DIMENSION_TYPE2	Type 2 of the dimensional group that specifies the product (e.g., Color palette for the dimensional group related to colors)
DIMENSION_LEVEL2	Identifying code of level 2 assigned to identify the product variant (e.g., identifying code of the valid color for the dimensional group related to colors)
DIMENSION_DESCRIPTION2	Descriptive description of level 2 assigned to identify the product variant (e.g., description of the valid color - Black, Red...- for the dimensional group related to colors)
DIMENSION_TYPE3	Type 3 of the dimensional group that specifies the product (e.g., Drop for the dimensional group related to drop)
DIMENSION_LEVEL3	Identifying code of level 3 assigned to identify the product variant (e.g., identifying code of the valid drop for the dimensional group)
DIMENSION_DESCRIPTION3	Descriptive description of level 3 assigned to identify the product variant (e.g., description of the valid drop - R, L... - for the dimensional group)
DIMENSION_TYPE4	Type 4 of the dimensional group that specifies the product (e.g., Stature for the dimensional group related to stature)
DIMENSION_LEVEL4	Identifying code of level 4 assigned to identify the product variant (e.g., identifying code of the valid stature for the dimensional group)
DIMENSION_DESCRIPTION4	Descriptive description of level 4 assigned to identify the product variant (e.g., description of the valid stature - 6,7,... - for the dimensional group)
DIMENSION_TYPE5	Type 5 of the dimensional group that specifies the product (e.g., Heel for the dimensional group related to heel)
DIMENSION_LEVEL5	Identifying code of level 5 assigned to identify the product variant (e.g., identifying code of the valid heel for the dimensional group)
DIMENSION_DESCRIPTION5	Descriptive description of level 5 assigned to identify the product variant (e.g., description of the valid heel - 70,100,... - for the dimensional group)
QUANTITY_STOCK	Final stock quantity at warehouse/store
QUANTITY_AVAILABLE	Available quantity
CREATE_DATE	Creation date of the information Format YYYY-MM-DD HH:MM:SS
LAST_UPDATE	Update date of the information Format YYYY-MM-DD HH:MM:SS
QUANTITY_RESERVED	SKU quantity reserved only for the entity

INFO

To activate the CSV export, we invite you to open a ticket by accessing the Jira portal.

For more details on CSV fields refere to STOCK_EXPORT

Delta Stock Update Service

Every 15 minutes, the service Get last stock can be invoked to retrieve the stock delta updated since the last request. The request requires a fromDateTime parameter, which is a datetime starting point (maximum of 24 hours ago).

INFO

The service is paginated to handle large sets of data efficiently.
For detailed information on how to handle pagination, refer to our Paginated Responses

Example Request

curl --location -g --request GET '/api?cmd=getLastStocks_v1&applicationId={{APPLICATION_ID}}&appId={{APPLICATION_ID}}&loadRoles=Y&fromDateTime=2022-05-03 10:10:00&channel=ECOMMERCE' \
--header 'applicationId: {{APPLICATION_ID}}' \
--header 'appId: {{APPLICATION_ID}}' \
--header 'namespace: {{NAMESPACE}}' \
--header 'languageId: {{LANGUAGE}}' \
--header 'username: {{USERNAME}}' \
--header 'password: {{PASSWORD}}' \
--header 'companyId: {{COMPANY_ID}}' \
--header 'siteId: {{SITE_ID}}' \
--header 'loadRoles: Y' \
--header 'User-Agent: Apidog/1.0.0 (https://apidog.com)' \
--header 'Content-Type: application/json'

Example Response

{
    "success": true,
    "valueObjectList": [
        {
            "entityCode": "1150",
            "entityDescription": "Negozio Mobile shop (Michele)",
            "entityType": "",
            "entityCity": "",
            "entityCountry": "",
            "entityProvince": "",
            "entityRegion": "",
            "entityZipCode": "",
            "parentEntityCode": 440,
            "itemCode": "191MP2311",
            "itemDescription": "GIACCA MY",
            "dimensionType1": "TAGLIA",
            "dimensionLevel1": "4",
            "dimensionDescription1": "L",
            "dimensionType2": "COLORE",
            "dimensionLevel2": "2138",
            "dimensionDescription2": "NERO/WHITE 03459",
            "dimensionType3": null,
            "dimensionLevel3": null,
            "dimensionType4": null,
            "dimensionLevel4": null,
            "dimensionType5": null,
            "dimensionLevel5": null,
            "quantityStock": 3,
            "quantityAvailable": 2,
            "quantityReservated": 1
        },
        {
            "entityCode": "1150",
            "entityDescription": "Negozio Mobile shop (Michele)",
            "entityType": "",
            "entityCity": "",
            "entityCountry": "",
            "entityProvince": "",
            "entityRegion": "",
            "entityZipCode": "",
            "parentEntityCode": 440,
            "itemCode": "AB70791",
            "itemDescription": "VESTITO ELISABETTA",
            "dimensionType1": "TAGLIA",
            "dimensionLevel1": "3",
            "dimensionDescription1": "40",
            "dimensionType2": "COLORE",
            "dimensionLevel2": "441",
            "dimensionDescription2": "Nero",
            "dimensionType3": null,
            "dimensionLevel3": null,
            "dimensionType4": null,
            "dimensionLevel4": null,
            "dimensionType5": null,
            "dimensionLevel5": null,
            "quantityStock": 2,
            "quantityAvailable": 2,
            "quantityReservated": 1
        },
        {
            "entityCode": "10",
            "entityDescription": "Negozio 10",
            "entityType": "SHOP",
            "entityCity": "MILANO",
            "entityCountry": "IT",
            "entityProvince": "MI",
            "entityRegion": "LOMBARDIA",
            "entityZipCode": "20124",
            "parentEntityCode": 440,
            "itemCode": "011 N",
            "itemDescription": "SCARPA DONNA REBECCA WHITE",
            "dimensionType1": "TAGLIA",
            "dimensionLevel1": "24",
            "dimensionDescription1": "46½",
            "dimensionType2": "COLORE",
            "dimensionLevel2": "125",
            "dimensionDescription2": "Black",
            "dimensionType3": null,
            "dimensionLevel3": null,
            "dimensionType4": null,
            "dimensionLevel4": null,
            "dimensionType5": null,
            "dimensionLevel5": null,
            "quantityStock": 5,
            "quantityAvailable": -1,
            "quantityReservated": 1
        }
    ],
    "moreRows": false
}

Example Sequence Diagram (Mermaid)

Implementation Steps

Daily Stock Update:

At 3 AM, the 4ws suite exports a CSV file containing the latest stock information.

The external system reads and processes this CSV file to update its stock records.

Delta Stock Updates:

Every 15 minutes, the external system calls the Get last stock service, providing the fromDateTime parameter.

The 4ws suite returns the stock updates that have occurred since the provided fromDateTime.

The external system processes these updates to keep its stock records current.

Detailed Process

Step 1: Daily Stock Update

CSV Export:

The 4ws suite generates and exports a CSV file every day at 3 AM.

The CSV file contains comprehensive stock information for all entities.

Read CSV File:

The external system reads the exported CSV file.

Parses the file and extracts stock information.

Update Stock Records:

The external system updates its stock records based on the information from the CSV file.

Step 2: Delta Stock Updates

Invoke Service:

Every 15 minutes, the external system invokes the Get last stock service with the fromDateTime parameter.

Process Response:

The 4ws suite returns the stock updates since the provided fromDateTime.

The external system processes these updates to keep its stock records accurate.

Update Stock Records:

The external system updates its stock records based on the delta updates received from the 4ws suite.

INFO

Please refer to Best Practices for Error Handling in External System for best practices on implementation.

Conclusion

By following this documentation, the external system can effectively synchronize its stock information with the 4ws suite, ensuring accurate and up-to-date stock records. The daily CSV export provides a comprehensive update, while the 15-minute delta updates keep the records current throughout the day.

Example Node.js

Here are the Node.js code snippets for processing the daily CSV file and requesting stock updates every 15 minutes. These snippets include error handling, retry mechanisms, and monitoring using winston for logging.

Dependencies

First, ensure you have the necessary dependencies installed:

Step 1: Processing the Daily CSV File

Step 2: Requesting Delta Stock Updates Every 15 Minutes

Monitoring and Error Handling with Retry

Conclusion

These Node.js snippets cover:

Processing the Daily CSV File: Reads and processes the CSV file generated daily at 3 AM.

Requesting Delta Stock Updates: Requests delta stock updates every 15 minutes using the fromDateTime parameter.

Error Handling and Retry Mechanisms: Includes retry mechanisms for both CSV processing and delta stock update requests, with logging for monitoring purposes.

These code examples should provide a robust starting point for integrating with the 4ws suite, ensuring that stock records are updated accurately and efficiently.

Updating External System Stock