Retriving a product details

Use case: Retriving a product details

This document outlines the API endpoints required for retrieving detailed information about products, including their barcodes, SKUs, and prices.
The use case involves accessing a list of products or a specific product by its unique ITEM_CODE.
Additionally, it details how to retrieve all associated barcodes and SKUs, as well as the various price types applicable to the product.
This comprehensive retrieval process ensures that users can access all necessary information related to the products in their inventory, making it easier to manage and utilize this data for various business operations.

Preconditions

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

Use Case: Retrieve Products, Barcodes, and Prices

Retrieve a List of Products: Use the GET /api/v1/products Get products endpoint to get a list of available products.

Retrieve a Specific Product: Use the GET /api/v1/products/{ITEM_CODE} Get product endpoint to get detailed information about a specific product using its ITEM_CODE.

Retrieve Barcodes and SKUs for a Product: Use the GET /api/v1/products/{ITEM_CODE}/barcodes Get SKU's barcodes endpoint to get all barcodes and SKUs associated with the specified product.

Retrieve Prices for a Product: Use the GET /api/v1/products/{ITEM_CODE}/prices Get prices endpoint to get various prices (sale, invoice, purchase, retail, etc.) for the specified product, including any applicable discounts.

Endpoints Overview

1. Get List of Products

Endpoint: GET /api/v1/products Get products

Description: Retrieves a list of products.

2. Get Product by ITEM_CODE

Endpoint: GET /api/v1/products/{ITEM_CODE} Get product

Description: Retrieves details of a specific product using its ITEM_CODE.

3. Get Product Barcodes and SKUs

Endpoint: GET /api/v1/products/{ITEM_CODE}/barcodes Get SKU's barcodes

Description: Retrieves all barcodes and SKUs for a specific product using its ITEM_CODE.

4. Get Product Prices

Endpoint: GET /api/v1/products/{ITEM_CODE}/prices Get prices

Description: Retrieves prices for a specific product using its ITEM_CODE, including any applicable discounts.

Definitions

SKU or Stock Keeping Unit, identified by the tuple (item_code, dimension1, dimension2, dimension3, dimension4, dimension5)

ITEM_CODE: The unique code identifying a product.

Price Types:

V: Sale

F: Invoice

A: Purchase

R: Retail

SALE: Sale

1 - Get List of Products

Endpoint

GET /api/v1/products Get products

Response

Success Response

Status Code: 200 OK

Response Body: JSON array of products

Example Success Response

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

{
  "products": [
    {
      "prog_id": 27975001,
      "item_code": "ITM12345","description_it": "Product description",
    "description_en": "Product 1 description",
    "shop_description_it": "Product 1 description for receipt",
    "shop_description_en": "Product 1 description for receipt",
    },{
      "prog_id": 27975002,
      "item_code": "ITM12346","description_it": "Product description",
    "description_en": "Product 2 description",
    "shop_description_it": "Product 2 description for receipt",
    "shop_description_en": "Product 2 description for receipt",
    }
  ],
  "moreRows": false
}

2 - Get Product by ITEM_CODE

Endpoint

GET /api/v1/products/{ITEM_CODE} Get product

Path Parameters

Parameter	Type	Description	Required
`ITEM_CODE`	String	The unique code of the product	Yes

Response

Success Response

Status Code: 200 OK

Response Body: JSON object containing product details

Example Success Response

{
  "product": {
    "prog_id": 10726794,
    "item_code": "ITM12345",
    "item_type": "PRODUCT",
    "item_subtype": "ITEM",
    "price_management_type": "ITEM",
    "vat_code": "4",
    "vat_department": 1,
    "tax_rate": "22",
    "description_it": "Product description",
    "description_en": "Product description",
    "shop_description_it": "Product description for receipt",
    "shop_description_en": "Product description for receipt",
    "season": "AI24",
    "brand_code": "XYZ",
    "brand": "Cillum Bran 001",
    "main_supplier_code": "ITM12345_SUP1",
    "main_supplier": "SUP1",
    "hierarchy_level1": "MALE",
    "attribute_level1": "YES",
    "dimension_group1": "TAGLIE_UE",
    "enabled_discount": false,
    "free_promotion": true,
    "weight": 335,
  }
}

3 - Get Product Barcodes and SKUs

Endpoint

GET /api/v1/products/{ITEM_CODE}/barcodes Get SKU's barcodes

Path Parameters

Parameter	Type	Description	Required
`ITEM_CODE`	String	The unique code of the product	Yes

Response

Success Response

Status Code: 200 OK

Response Body: JSON object containing product details

Example Success Response

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

{
  "barcodes": [
    {
      "barcode": "9780201379624",
      "barcode_type": "EAN13",
      "dimension_level1": "XL",
      "dimension_level2": "RED"
    }
  ],
  "moreRows": false
}

4 - Get Product Prices

Endpoint

GET /api/v1/products/{ITEM_CODE}/prices Get prices

Headers

Optional: price_list_type to specify a single price type

Optional: start_date to specify a reference date (format: YYYY-MM-DD)

Path Parameters

Parameter	Type	Description	Required
`ITEM_CODE`	String	The unique code of the product	Yes

Response

Success Response

Status Code: 200 OK

Response Body: JSON array of prices

Example Success Response

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

{
  "item_code": "quis",
  "price_management_type": "ITEM",
  "item_prices": [
    {
      "start_date": "2024-05-02",
      "end_date": "2024-05-01",
      "price": 33,
      "price_list_type": "V",
      "currency": "EUR",
      "price_list": "P_01",
      "price_list_entities": [
        "1"
      ]
    }
  ]
}

Sequence Diagram: API Invocation Flow

This sequence diagram illustrates the flow of invoking the four APIs to retrieve product details, barcodes, SKUs, and prices.

Retriving a product details

Use case: Retriving a product details#

Preconditions#

Use Case: Retrieve Products, Barcodes, and Prices#

Endpoints Overview#

1. Get List of Products#

2. Get Product by ITEM_CODE#

3. Get Product Barcodes and SKUs#

4. Get Product Prices#

1 - Get List of Products#

Endpoint#

Response#

Success Response#

Example Success Response#

2 - Get Product by ITEM_CODE#

Endpoint#

Path Parameters#

Response#

Success Response#

Example Success Response#

3 - Get Product Barcodes and SKUs#

Endpoint#

Path Parameters#

Response#

Success Response#

Example Success Response#

4 - Get Product Prices#

Endpoint#

Headers#

Path Parameters#

Response#

Success Response#

Example Success Response#

Sequence Diagram: API Invocation Flow#

Use case: Retriving a product details

Preconditions

Use Case: Retrieve Products, Barcodes, and Prices

Endpoints Overview

1. Get List of Products

2. Get Product by ITEM_CODE

3. Get Product Barcodes and SKUs

4. Get Product Prices

1 - Get List of Products

Endpoint

Response

Success Response

Example Success Response

2 - Get Product by ITEM_CODE

Endpoint

Path Parameters

Response

Success Response

Example Success Response

3 - Get Product Barcodes and SKUs

Endpoint

Path Parameters

Response

Success Response

Example Success Response

4 - Get Product Prices

Endpoint

Headers

Path Parameters

Response

Success Response

Example Success Response

Sequence Diagram: API Invocation Flow