- Four Way Shop API
- Before start develop
- Why we use Resource-oriented design
- Technical Prerequisites
- Concepts
- Best Practices
- Data management
- Authentication
- Rate Limits
- Paginated Responses
- Getting Started
- API Changelog
- Use cases
- API
- Login
- Product
- Brand
- Season
- Attribute
- Hierarchy
- Dimension groups
- Dimension
- Product
- Activate dimensions on products
- Barcode
- Prices
- Price dimension groupings
- Assortment
- Image
- Supplier
- Custom category
- Vat
- Stock
- Price lists
- Supplier
- Entities
- Miscellaneous
- Catalog
- Export
- Documents
- Authentication
- Paginated responses
- Managing API Callbacks
- Document notifications
- Customer promo data notifications
- Use cases
- Updating External System Stock
- E-commerce Recipt Processing
- E-commerce Return Receipt Processing
- E-commerce Order sale Processing
- E-commerce Return Order Processing
- E-commerce Order Handling and Internal Stock Transfer
- E-commerce & Gift Card
- Creating a free entry
- Retrieving a Document by Identifier
- Cart Validation Service
- Sale and Shipping costs
- Handling Line Item Discounts
- Managing Price Forcing in Cart Items
- Purchase Order Registration
- Supplier Goods Entry From Purchase Order
- Update an Orchestrated Order
- New Orchestrated Return Orders
- API
- 🚫 KeepIT
- Authentication
- Use cases
- Articles (deprecated)
- Get Articles
- Insert/Update dimensional groups
- Insert/Update price groupings
- Insert/Update dimensions
- Insert/Update attributes
- Insert/Update hieararchies
- Insert/Update seasons
- Insert/Update articles
- Insert/Update Articles Master data
- Insert/Update Lists
- Insert/Update Dimensions Groups
- Create EAN13 barcode
- Insert/Update Barcode
- Assign dimensions to groupings
- Price Lists (deprecated)
- Stock (deprecated)
- Sales (deprecated)
- Deposit (deprecated)
- Services
- Points
- Subjects
- Giftcards & Vouchers
- Missed Opportunity
- Documents (deprecated)
- Catalogs
- Suppliers (deprecated)
- Export (deprecated)
- Configuration Mobile Shop (deprecated)
- Mappings
Insert product
POST
/api/v1/products
Last modified:2025-02-07 14:43:36
Create a New Product in 4WS Trade System#
prog_id) and the product code (item_code) once the product is successfully created.Auto generated code
item_code is not passed in the JSON body of the request and auto_generate_code is set to true, the system will automatically generate the product code following the rules configured for the tenant.Actors#
Languages#
Preconditions#
auto_generate_code flag set to true, and the item_code field can be omitted.Main Success Scenario#
prog_id and item_code.{
"product": {
"prog_id": 90941,
"item_code": "MININTSAB-52311090940"
}
}Alternate Flows#
1.
If the tenant is configured to auto-generate product codes, the
auto_generate_code parameter must be set to true, and the item_code field can be omitted. The 4WS Trade system will automatically generate the product code.{
"auto_generate_code": true,
"description_it": "Product description",
"description_en": "Product description",
"brand_code": "SAB",
"season_code": "231"
}2.
If a product with the same
item_code already exists, the system will return an HTTP 422 error.{
"message": "Unique constraint error"
}Best Practices
Sequence Diagram#
Code Examples in Node.js#
POST request with product data. It handles both successful and error responses (e.g., unique constraint errors).Request
Body Params application/json
Example
{
"type": "object",
"properties": {
"item_code": {
"type": "string",
"description": "Codice prodotto"
},
"description_it": {
"type": "string",
"description": "Descrizione It"
},
"description_en": {
"type": "string",
"description": "Descrizione En"
},
"season_code": {
"type": [
"string",
"null"
],
"description": "Codice stagione del prodotto"
},
"brand_code": {
"type": [
"string",
"null"
],
"description": "Codice marchio prodotto"
},
"made_in": {
"type": [
"string",
"null"
],
"description": "Codice made in del prodotto ISO 2 codice nazione"
},
"hierarchy_level1": {
"type": [
"string",
"null"
],
"description": "Gerarchia"
},
"hierarchy_level2": {
"type": [
"string",
"null"
],
"description": "Gerarchia"
},
"attribute_level1": {
"type": [
"string",
"null"
],
"description": "Attributo"
},
"dimension_group1": {
"type": [
"string",
"null"
],
"description": "Gruppo dimensionale"
},
"dimension_group2": {
"type": [
"string",
"null"
],
"description": "Gruppo dimensionale"
},
"item_supplier_code": {
"type": [
"string",
"null"
],
"description": "Codice prodotto fornitore"
},
"composition": {
"type": [
"string",
"null"
]
},
"customs_category": {
"type": [
"string",
"null"
]
},
"enabled_sale": {
"type": [
"boolean",
"null"
]
},
"exposition_type": {
"type": [
"string",
"null"
],
"description": "Tipologia di esposizione"
},
"free_promotion": {
"type": [
"boolean",
"null"
],
"description": "Possibilità di essere omaggiato durante le promozioni"
},
"free_sale": {
"type": [
"boolean",
"null"
],
"description": "Possibilità di essere omaggiato"
},
"item_depth": {
"type": [
"number",
"null"
],
"description": "Profondità",
"minimum": 0
},
"item_heigth": {
"type": [
"number",
"null"
],
"description": "Altezza",
"minimum": 0
},
"item_width": {
"type": [
"number",
"null"
],
"description": "Larghezza",
"minimum": 0
},
"manual_cost": {
"type": [
"boolean",
"null"
],
"description": "Possibilità di applicare un costo manuale"
},
"measure_unit": {
"type": [
"string",
"null"
],
"description": "Unità di misura"
},
"minimum_pack": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"pack_depth": {
"type": [
"integer",
"null"
],
"description": "Profondità pacco",
"minimum": 0
},
"pack_heigth": {
"type": [
"integer",
"null"
],
"description": "Altezza pacco",
"minimum": 0
},
"pack_width": {
"type": [
"integer",
"null"
],
"description": "Larghezza pacco",
"examples": [
0
],
"minimum": 0
},
"shop_description_it": {
"type": "string",
"description": "Descrizione scontrino It"
},
"shop_description_en": {
"type": "string",
"description": "Descrizione scontrino En"
},
"sartorial_code": {
"type": [
"string",
"null"
]
},
"set_item": {
"type": [
"boolean",
"null"
],
"description": "Indica se un prodotto è un set"
},
"set_quantity": {
"type": [
"integer",
"null"
],
"description": "Quantità set",
"minimum": 0
},
"weight": {
"type": [
"integer",
"null"
],
"description": "Peso netto del prodotto in grammi",
"minimum": 0
},
"tailor_selection": {
"type": [
"string",
"null"
]
},
"vat_code": {
"type": [
"string",
"null"
],
"description": "Codice aliquota IVA"
},
"season": {
"type": [
"string",
"null"
],
"description": "Stagione"
},
"year": {
"type": [
"integer",
"null"
],
"description": "Anno",
"minimum": 1000,
"examples": [
2024
]
},
"brand": {
"type": [
"string",
"null"
],
"description": "Descrizione brand"
},
"main_supplier": {
"type": "string",
"description": "Descrizione fornitore"
},
"hierarchy_level3": {
"type": [
"string",
"null"
],
"description": "Gerarchia"
},
"hierarchy_level4": {
"type": [
"string",
"null"
],
"description": "Gerarchia"
},
"hierarchy_level5": {
"type": [
"string",
"null"
],
"description": "Gerarchia"
},
"hierarchy_level6": {
"type": [
"string",
"null"
],
"description": "Gerarchia"
},
"hierarchy_level7": {
"type": [
"string",
"null"
],
"description": "Gerarchia"
},
"hierarchy_level8": {
"type": [
"string",
"null"
],
"description": "Gerarchia"
},
"hierarchy_level9": {
"type": [
"string",
"null"
],
"description": "Gerarchia"
},
"hierarchy_level10": {
"type": [
"string",
"null"
],
"description": "Gerarchia"
},
"attribute_level2": {
"type": [
"string",
"null"
],
"description": "Attributo"
},
"attribute_level3": {
"type": [
"string",
"null"
],
"description": "Attributo"
},
"attribute_level4": {
"type": [
"string",
"null"
],
"description": "Attributo"
},
"attribute_level5": {
"type": [
"string",
"null"
],
"description": "Attributo"
},
"attribute_level6": {
"type": [
"string",
"null"
],
"description": "Attributo"
},
"attribute_level7": {
"type": [
"string",
"null"
],
"description": "Attributo"
},
"attribute_level8": {
"type": [
"string",
"null"
],
"description": "Attributo"
},
"attribute_level9": {
"type": [
"string",
"null"
],
"description": "Attributo"
},
"attribute_level10": {
"type": [
"string",
"null"
],
"description": "Attributo"
},
"dimension_group3": {
"type": [
"string",
"null"
],
"description": "Gruppo dimensionale"
},
"dimension_group4": {
"type": [
"string",
"null"
],
"description": "Gruppo dimensionale"
},
"dimension_group5": {
"type": [
"string",
"null"
],
"description": "Gruppo dimensionale"
},
"enabled_discount": {
"type": [
"boolean",
"null"
],
"description": "Possibilità di applicargli sconti"
},
"packages": {
"type": [
"string",
"null"
],
"description": "Numero di pacchi"
},
"packages_hanging": {
"type": [
"string",
"null"
],
"description": "Numero di pacchi appesi"
},
"item_type": {
"type": "string",
"description": "Tipologia prodotto",
"enum": [
"PRODUCT"
],
"x-apidog": {
"enumDescriptions": {
"PRODUCT": "Prodotto"
}
}
},
"item_subtype": {
"type": "string",
"description": "Sottotipo prodotto",
"enum": [
"ITEM"
],
"x-apidog": {
"enumDescriptions": {
"ITEM": "Prodotto"
}
}
},
"price_management_type": {
"type": "string",
"enum": [
"ITEM",
"SIZE"
],
"x-apidog": {
"enumDescriptions": {
"ITEM": "Prodotto",
"SIZE": "Fascia"
}
},
"description": "Gestione prezzo"
},
"vat_department": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 999
},
"tax_rate": {
"type": [
"string",
"null"
],
"description": "Aliquota IVA %"
},
"main_supplier_code": {
"type": "string",
"description": "Codice fornitore"
},
"prog_id": {
"type": "integer",
"description": "Identificativo interno",
"minimum": 0
},
"season_sale_code": {
"type": [
"string",
"null"
],
"description": "Codice stagione di vendita"
},
"season_sale": {
"type": [
"string",
"null"
],
"description": "Stagione di vendita"
},
"season_sale_year": {
"type": [
"integer",
"null"
],
"description": "Anno stagione di vendita",
"examples": [
2024
],
"minimum": 1000
}
},
"required": [
"item_code",
"description_it",
"description_en",
"item_type",
"item_subtype",
"price_management_type",
"prog_id"
],
"x-apidog-orders": [
"prog_id",
"item_code",
"item_type",
"item_subtype",
"price_management_type",
"vat_code",
"vat_department",
"tax_rate",
"description_it",
"description_en",
"shop_description_it",
"shop_description_en",
"season_code",
"season",
"year",
"season_sale_code",
"season_sale",
"season_sale_year",
"brand_code",
"brand",
"made_in",
"main_supplier_code",
"main_supplier",
"item_supplier_code",
"hierarchy_type1",
"hierarchy_type2",
"hierarchy_type3",
"hierarchy_type4",
"hierarchy_type5",
"hierarchy_type6",
"hierarchy_type7",
"hierarchy_type8",
"hierarchy_type9",
"hierarchy_type10",
"hierarchy_level1",
"hierarchy_level2",
"hierarchy_level3",
"hierarchy_level4",
"hierarchy_level5",
"hierarchy_level6",
"hierarchy_level7",
"hierarchy_level8",
"hierarchy_level9",
"hierarchy_level10",
"attribute_type1",
"attribute_type2",
"attribute_type3",
"attribute_type4",
"attribute_type5",
"attribute_type6",
"attribute_type7",
"attribute_type8",
"attribute_type9",
"attribute_type10",
"attribute_level1",
"attribute_level2",
"attribute_level3",
"attribute_level4",
"attribute_level5",
"attribute_level6",
"attribute_level7",
"attribute_level8",
"attribute_level9",
"attribute_level10",
"dimension_group1",
"dimension_group2",
"dimension_group3",
"dimension_group4",
"dimension_group5",
"minimum_pack",
"measure_unit",
"item_heigth",
"item_width",
"item_depth",
"pack_heigth",
"pack_width",
"pack_depth",
"set_item",
"set_quantity",
"exposition_type",
"enabled_discount",
"enabled_sale",
"free_promotion",
"free_sale",
"manual_cost",
"tailor_selection",
"packages",
"packages_hanging",
"weight",
"composition",
"customs_category",
"sartorial_code"
]
}Request Code Samples
Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST '/api/v1/products' \
--header 'Content-Type: application/json' \
--data-raw '{
"type": "object",
"properties": {
"item_code": {
"type": "string",
"description": "Codice prodotto"
},
"description_it": {
"type": "string",
"description": "Descrizione It"
},
"description_en": {
"type": "string",
"description": "Descrizione En"
},
"season_code": {
"type": [
"string",
"null"
],
"description": "Codice stagione del prodotto"
},
"brand_code": {
"type": [
"string",
"null"
],
"description": "Codice marchio prodotto"
},
"made_in": {
"type": [
"string",
"null"
],
"description": "Codice made in del prodotto ISO 2 codice nazione"
},
"hierarchy_level1": {
"type": [
"string",
"null"
],
"description": "Gerarchia"
},
"hierarchy_level2": {
"type": [
"string",
"null"
],
"description": "Gerarchia"
},
"attribute_level1": {
"type": [
"string",
"null"
],
"description": "Attributo"
},
"dimension_group1": {
"type": [
"string",
"null"
],
"description": "Gruppo dimensionale"
},
"dimension_group2": {
"type": [
"string",
"null"
],
"description": "Gruppo dimensionale"
},
"item_supplier_code": {
"type": [
"string",
"null"
],
"description": "Codice prodotto fornitore"
},
"composition": {
"type": [
"string",
"null"
]
},
"customs_category": {
"type": [
"string",
"null"
]
},
"enabled_sale": {
"type": [
"boolean",
"null"
]
},
"exposition_type": {
"type": [
"string",
"null"
],
"description": "Tipologia di esposizione"
},
"free_promotion": {
"type": [
"boolean",
"null"
],
"description": "Possibilità di essere omaggiato durante le promozioni"
},
"free_sale": {
"type": [
"boolean",
"null"
],
"description": "Possibilità di essere omaggiato"
},
"item_depth": {
"type": [
"number",
"null"
],
"description": "Profondità",
"minimum": 0
},
"item_heigth": {
"type": [
"number",
"null"
],
"description": "Altezza",
"minimum": 0
},
"item_width": {
"type": [
"number",
"null"
],
"description": "Larghezza",
"minimum": 0
},
"manual_cost": {
"type": [
"boolean",
"null"
],
"description": "Possibilità di applicare un costo manuale"
},
"measure_unit": {
"type": [
"string",
"null"
],
"description": "Unità di misura"
},
"minimum_pack": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"pack_depth": {
"type": [
"integer",
"null"
],
"description": "Profondità pacco",
"minimum": 0
},
"pack_heigth": {
"type": [
"integer",
"null"
],
"description": "Altezza pacco",
"minimum": 0
},
"pack_width": {
"type": [
"integer",
"null"
],
"description": "Larghezza pacco",
"examples": [
0
],
"minimum": 0
},
"shop_description_it": {
"type": "string",
"description": "Descrizione scontrino It"
},
"shop_description_en": {
"type": "string",
"description": "Descrizione scontrino En"
},
"sartorial_code": {
"type": [
"string",
"null"
]
},
"set_item": {
"type": [
"boolean",
"null"
],
"description": "Indica se un prodotto è un set"
},
"set_quantity": {
"type": [
"integer",
"null"
],
"description": "Quantità set",
"minimum": 0
},
"weight": {
"type": [
"integer",
"null"
],
"description": "Peso netto del prodotto in grammi",
"minimum": 0
},
"tailor_selection": {
"type": [
"string",
"null"
]
},
"vat_code": {
"type": [
"string",
"null"
],
"description": "Codice aliquota IVA"
},
"season": {
"type": [
"string",
"null"
],
"description": "Stagione"
},
"year": {
"type": [
"integer",
"null"
],
"description": "Anno",
"minimum": 1000,
"examples": [
2024
]
},
"brand": {
"type": [
"string",
"null"
],
"description": "Descrizione brand"
},
"main_supplier": {
"type": "string",
"description": "Descrizione fornitore"
},
"hierarchy_level3": {
"type": [
"string",
"null"
],
"description": "Gerarchia"
},
"hierarchy_level4": {
"type": [
"string",
"null"
],
"description": "Gerarchia"
},
"hierarchy_level5": {
"type": [
"string",
"null"
],
"description": "Gerarchia"
},
"hierarchy_level6": {
"type": [
"string",
"null"
],
"description": "Gerarchia"
},
"hierarchy_level7": {
"type": [
"string",
"null"
],
"description": "Gerarchia"
},
"hierarchy_level8": {
"type": [
"string",
"null"
],
"description": "Gerarchia"
},
"hierarchy_level9": {
"type": [
"string",
"null"
],
"description": "Gerarchia"
},
"hierarchy_level10": {
"type": [
"string",
"null"
],
"description": "Gerarchia"
},
"attribute_level2": {
"type": [
"string",
"null"
],
"description": "Attributo"
},
"attribute_level3": {
"type": [
"string",
"null"
],
"description": "Attributo"
},
"attribute_level4": {
"type": [
"string",
"null"
],
"description": "Attributo"
},
"attribute_level5": {
"type": [
"string",
"null"
],
"description": "Attributo"
},
"attribute_level6": {
"type": [
"string",
"null"
],
"description": "Attributo"
},
"attribute_level7": {
"type": [
"string",
"null"
],
"description": "Attributo"
},
"attribute_level8": {
"type": [
"string",
"null"
],
"description": "Attributo"
},
"attribute_level9": {
"type": [
"string",
"null"
],
"description": "Attributo"
},
"attribute_level10": {
"type": [
"string",
"null"
],
"description": "Attributo"
},
"dimension_group3": {
"type": [
"string",
"null"
],
"description": "Gruppo dimensionale"
},
"dimension_group4": {
"type": [
"string",
"null"
],
"description": "Gruppo dimensionale"
},
"dimension_group5": {
"type": [
"string",
"null"
],
"description": "Gruppo dimensionale"
},
"enabled_discount": {
"type": [
"boolean",
"null"
],
"description": "Possibilità di applicargli sconti"
},
"packages": {
"type": [
"string",
"null"
],
"description": "Numero di pacchi"
},
"packages_hanging": {
"type": [
"string",
"null"
],
"description": "Numero di pacchi appesi"
},
"item_type": {
"type": "string",
"description": "Tipologia prodotto",
"enum": [
"PRODUCT"
],
"x-apidog": {
"enumDescriptions": {
"PRODUCT": "Prodotto"
}
}
},
"item_subtype": {
"type": "string",
"description": "Sottotipo prodotto",
"enum": [
"ITEM"
],
"x-apidog": {
"enumDescriptions": {
"ITEM": "Prodotto"
}
}
},
"price_management_type": {
"type": "string",
"enum": [
"ITEM",
"SIZE"
],
"x-apidog": {
"enumDescriptions": {
"ITEM": "Prodotto",
"SIZE": "Fascia"
}
},
"description": "Gestione prezzo"
},
"vat_department": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 999
},
"tax_rate": {
"type": [
"string",
"null"
],
"description": "Aliquota IVA %"
},
"main_supplier_code": {
"type": "string",
"description": "Codice fornitore"
},
"prog_id": {
"type": "integer",
"description": "Identificativo interno",
"minimum": 0
},
"season_sale_code": {
"type": [
"string",
"null"
],
"description": "Codice stagione di vendita"
},
"season_sale": {
"type": [
"string",
"null"
],
"description": "Stagione di vendita"
},
"season_sale_year": {
"type": [
"integer",
"null"
],
"description": "Anno stagione di vendita",
"examples": [
2024
],
"minimum": 1000
}
},
"required": [
"item_code",
"description_it",
"description_en",
"item_type",
"item_subtype",
"price_management_type",
"prog_id"
],
"x-apidog-orders": [
"prog_id",
"item_code",
"item_type",
"item_subtype",
"price_management_type",
"vat_code",
"vat_department",
"tax_rate",
"description_it",
"description_en",
"shop_description_it",
"shop_description_en",
"season_code",
"season",
"year",
"season_sale_code",
"season_sale",
"season_sale_year",
"brand_code",
"brand",
"made_in",
"main_supplier_code",
"main_supplier",
"item_supplier_code",
"hierarchy_type1",
"hierarchy_type2",
"hierarchy_type3",
"hierarchy_type4",
"hierarchy_type5",
"hierarchy_type6",
"hierarchy_type7",
"hierarchy_type8",
"hierarchy_type9",
"hierarchy_type10",
"hierarchy_level1",
"hierarchy_level2",
"hierarchy_level3",
"hierarchy_level4",
"hierarchy_level5",
"hierarchy_level6",
"hierarchy_level7",
"hierarchy_level8",
"hierarchy_level9",
"hierarchy_level10",
"attribute_type1",
"attribute_type2",
"attribute_type3",
"attribute_type4",
"attribute_type5",
"attribute_type6",
"attribute_type7",
"attribute_type8",
"attribute_type9",
"attribute_type10",
"attribute_level1",
"attribute_level2",
"attribute_level3",
"attribute_level4",
"attribute_level5",
"attribute_level6",
"attribute_level7",
"attribute_level8",
"attribute_level9",
"attribute_level10",
"dimension_group1",
"dimension_group2",
"dimension_group3",
"dimension_group4",
"dimension_group5",
"minimum_pack",
"measure_unit",
"item_heigth",
"item_width",
"item_depth",
"pack_heigth",
"pack_width",
"pack_depth",
"set_item",
"set_quantity",
"exposition_type",
"enabled_discount",
"enabled_sale",
"free_promotion",
"free_sale",
"manual_cost",
"tailor_selection",
"packages",
"packages_hanging",
"weight",
"composition",
"customs_category",
"sartorial_code"
]
}'Responses
🟢200Success
application/json
Body
Example
{
"product": {
"prog_id": 90941,
"item_code": "MININTSAB-52311090940"
}
}🟠401Authentication failed
🟠403Operation not allowed
🟠422Unique constraint error
Modified at 2025-02-07 14:43:36