Get products by Catalog Code

Retrieve Products by Catalog Code

This API allows clients to retrieve a paginated list of the products updated in a specific catalog after a specified date (fromDate).
The fromDate value cannot be more than 24 hours before the request. The response contains only the product code and its status: to retrieve product details, barcodes or prices, additional API endpoints are required.

The API supports pagination to navigate through large lists of entities.

Paginated Responses

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

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 service, please refer to Authentication.

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

The fromDate parameter must be within the last 24 hours.

The catalog code (e.g., ECOMMERCE) must exist and be active.

APIs Used

Retrieve updated products: Get products by Catalog Code

Retrieve product details: Get product

Retrieve product barcodes: Get SKU's barcodes

Retrieve product prices: Get product prices or Get prices from price list

Main Success Scenario

The external system sends a GET request with CATALOG_CODE and a valid fromDate.

If the request is successful, the system returns an HTTP 200 response with the paginated list of products of the requested catalog and a nextCursor indicating whether there are more products to retrieve. If nextCursor is set, the external system must call this service again, setting cursor to the nextCursor value.

Response Example

How to get enabled and disabled products with the `returnDisabled` param

The returnDisabled query param specifies that deactivated products (status: false) must also be returned in the response, so that the external system can remove them from its catalog.
If the value is not specified, the default is false.

How to get the latest modified products with the `fromDate` param

The fromDate parameter is used to retrieve the products of a catalog modified after the specified date.
It filters results by last modification date, so that only products updated after the given value are returned.
The date provided via fromDate cannot be earlier than yesterday: the minimum acceptable value is always "now minus 24 hours".
This constraint keeps data retrieval focused on recent updates and prevents requests over excessively long time periods. If more than 24 hours have passed since the last synchronization, the external system must perform a full import again (see Updating External System Product Catalog).

Alternate Flows

Authentication Error: If the client does not provide valid credentials, an error response is returned.

Error Example

Invalid fromDate: If fromDate is more than 24 hours old, the API returns an error.

Empty response: If no products have been updated after the specified fromDate, the API returns an empty products list.

Pagination Error: If an invalid cursor is provided, an error response is returned.

Rate Limiting: If the API rate limits are exceeded, the client must respect the retry interval indicated in the response headers, see Rate Limits.

Sequence Diagram

Best Practices

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

Code Examples in Node.js

Fetching Updated Products:

Fetching Product Details:

Fetching Product Prices:

Responses

🟢200POST/PATCH/DELETE Errore record non trovato

application/json

Bodyapplication/json

Example

{
    "catalog_code": "33",
    "products": [
        {
            "item_code": "ITEM_123",
            "status": false
        },
        {
            "item_code": "ITEM_123",
            "status": false
        },
        {
            "item_code": "ITEM_123",
            "status": false
        }
    ],
    "nextCursor": "eyJwYWdlIjoyLCJwYWdlU2l6ZSI6MTB2"
}

Get products by Catalog Code

Retrieve Products by Catalog Code

Actors

Preconditions

APIs Used

Main Success Scenario

How to get enabled and disabled products with the `returnDisabled` param

How to get the latest modified products with the `fromDate` param

Alternate Flows

Sequence Diagram

Code Examples in Node.js

Request

Request Code Samples

Responses

Get products by Catalog Code

Retrieve Products by Catalog Code#

Actors#

Preconditions#

APIs Used#

Main Success Scenario#

How to get enabled and disabled products with the returnDisabled param#

How to get the latest modified products with the fromDate param#

Alternate Flows#

Sequence Diagram#

Code Examples in Node.js#

Request

Request Code Samples

Responses

Retrieve Products by Catalog Code

Actors

Preconditions

APIs Used

Main Success Scenario

How to get enabled and disabled products with the `returnDisabled` param

How to get the latest modified products with the `fromDate` param

Alternate Flows

Sequence Diagram

Code Examples in Node.js