In addition to ready-made integration with PIM class systems, it is possible to send products to the ONe platform from external systems (eg ERP or PIM).

Table of contents Glossary POST - Import single product packagings POST - Import a list of products PATCH- Import a list of products with partial changes POST - Import categories PATCH- Import categories with partial changes POST - Import a single product PATCH- Import a single product with partial changes POST - Import relations PATCH- Import relations with partial changes

Glossary

Name	Explanation
`attributes`: `type` `attributeId` `description`	These are the technical data of the product, which are displayed on the ONe platform in a special place Possible to choose from `NumericAttributeImportData` , `LogicAttributeImportData`, `AlphanumericAttributeImportData` Idenftyfier od attribute descripion attriubute
`attributes`→ `value` `code` `label`	Attribute code for filtering Attribute label displayed on product card
`categoryInformation` `canonicalCategoryId` `categoriesIds`	Information of category provide the ID of the last row of the category in which the product is located We provide all categories in which the product is. For example, if the product is in category C, which is a subcategory of category B, which in turn is a subcategory of category A, then in `categoriesIds` we first enter the ID of category A, then category B and finally category C
`labels`	Labels are used to mark products, then in the Administrator Panel we can assign graphics labels to the data. Products marked with a given label will have added graphics on their thumbnail on the product list. The label also serves as a filter that can be used when viewing the list of products. Labels can be configured in backoffice. There is possibility to define: - visibility - image on product card - label
`orderInformation`: `contentUnitCode` `orderUnitCode` `packingQuantity` `quantityInterval` `quantityMin` `orderUnitDescription contentUnitDescription`	Information related to the product order Unit of the product related to the order unit Unit in which the product can be ordered; it is only possible to order multiples of the product unit Positive Number of content units per order unit of the product. If order unit and content unit are identical, the value is always `1`. Only natural numbers. Interval of order unit, in which the product can be delivered. Number indicating the quantity steps in which the product can be ordered, e.g. `5` e.g. user can add every 5 boxes, if he has 10 boxes and after clicking plus, the number of ordered boxes will be increased by 5 to 15. Only natural numbers. Minimum order quantity with respect to the order unit e.g. minimum 5 boxes, not 4 boxes. Only natural numbers.
`overallInformation` `brandDescription` `brandName` `cableType` `description` `gtin` `gtu` `manufacturerAcronym` `manufacturerId` `manufacturerName` `manufacturerPid` `netDepth` `netDiameter` `netLength` `netVolume` `netWeight` `netWidth productName` `productSeries` `productStatus` `shippingTime` `shortDescription` `splitPayment` `surchargePriceAmount` `taxReverseCharged` `usage`	Shared description of this product brand Brand name of the product Cable type, possible to choose from "`DRUM_CABLE`" "`ROLL`” Long and detailed product description Product ID of the buying company GTU of product Short name of the manufacturer Manufacturer id of product Name of the manufacturer of the product Product ID of the manufacturer Net depth in meters Net diameter in meters Net length in meters Net volume in cubic meters Net weight in kilogram Net width in meters Product name Name of the product series Product status, default: ACTIVE. Possible to choose from "`ACTIVE`" "`DRAFT_NEW`" "`DRAFT_SENT`" "`DRAFT_REJECTED`” Product shipping time Shorter, more compact product description Split payment availability Amount of surcharge price Information on the availability of reverse charge Usage of the product
`packagingInformation` `depth` `diameter` `gtin` `length` `packagingProductId` `packagingUnitCode` `packagingUnitName` `quantityMax` `quantityMin` `volume` `weight` `width`	Depth of the packaging unit in meters Diameter of the packaging unit in meters GTIN (formerly EAN code) of packaging unit Length of the packaging unit in meters ID of the packaging Code for the packaging units Name for the packaging units Maximum order quantity with respect to the order unit Minimum quantity with respect to the order unit Volume of the packaging unit in cubic meters Gross weight of the packaging unit in kilogram Width of the packaging unit in meters
`priceInformation` `tax`	Tax rate as fraction (i.e. 0.23)
`productId`	External product ID
`relatedProducts`: `relatedProductId` `relationType` `quantity`	These are the connections between the products thanks to which we implement the cross and up selling strategy Property can be omitted: - property absence → do not update - `null` property (`”prop”: null`)→ delete/remove value Identifier of product Type of relation. Possible to choose from `ACCESSORIES`, `SIMILAR`, `OTHERS`
`relationsIds`	They are used when selling similar products that differ, for example, in color or size for faster and easier transition to the product card by the customer Property can be omitted: - property absence → do not update - `null` property (`”prop”: null`)→ delete/remove value
`searchAttributes`: `rank`	Setting a parameter causes the product to appear in a specific order Property can be omitted: - property absence → do not update - `null` property (`”prop”: null`)→ delete/remove value
`seoAttributes`: `title` `description` `h1` `follow` `index`	Basic SEO settings for the product card This is the title that appears in the web browser tab. Property can be omitted: - property absence → do not update - `null` property (`”prop”: null`)→ delete/remove value description that will be visible in the search engine at the website address. Property can be omitted: - property absence → do not update - `null` property (`”prop”: null`)→ delete/remove value One of the main attributes used for SEO optimization. Property can be omitted: - property absence → do not update - `null` property (`”prop”: null`)→ delete/remove value Attribute indicating whether search engine robots will consider the product page. to choose from `True` or `False`. Property can be omitted: - property absence → do not update - `null` property (`”prop”: null`)→ delete/remove value The attribute responsible for indexing subpages. Takes the values `True` or `False`. Property can be omitted: - property absence → do not update - `null` property (`”prop”: null`)→ delete/remove value
`urlInformation`
`urlInformation` → `certificates` `url` `fileName` `alt`	link to the document of certificates name of certificates Alternative text if the file cannot be displayed
`urlInformation` → `energyClass` `cardUrl` `labelUrl`	link to the energy label card that will be displayed after pressing the label link to the label
`urlInformation` → `photos` `url` `fileName` `alt`	link to the photo name of photo Alternative text if the photo cannot be displayed
`urlInformation` → `productCards` `url` `fileName` `alt`	link to the product card name of product card Alternative text if the file cannot be displayed
`urlInformation` → `videos` `url` `fileName` `alt`	link to the video name of photo Alternative text if the file cannot be displayed

POST - Import single product packagings

In order to import single product packagings use POST /api/v1/catalog/integrations/auth-required/products/by-sku/packagings/import. The diagram below shows the dependency of communicating with the API:

Use the parameter in query below to update selected products:

productId

Example request:

json
curl -X POST
"https://api-preprod.one.unity.pl/api/v1/catalog/integrations/auth-required/products/import-selected?ids=BUD_12414" 
-H  "accept: */*" 
-H  "one-tenant: {tenant}" 
-H  "ApiAuth: {apiKey}"
-d " [
  {
    "depth": 2,
    "diameter": 2,
    "gtin": "5901234560009",
    "length": 2,
    "packagingProductId": "test888",
    "packagingUnitCode": "22",
    "packagingUnitName": "pack",
    "quantityMax": 10,
    "quantityMin": 1,
    "volume": 2,
    "weight": 10,
    "width": 2
  }
]

Example request (import of a single product with a minimum amount of data - for testing):

json
{
   
    "categoryInformation": {
      "canonicalCategoryId": "kat3.1.1",
      "categoriesIds": [
        "kat3.1.1"
      ]},
        "labels": [ 
          "categorytest"
        ],
        "orderInformation": { 
          "contentUnitCode": "szt.", 
          "orderUnitCode": "szt.", 
          "packingQuantity": 1, 
          "quantityInterval": 1, 
          "quantityMin": 1, 
          "orderUnitDescription": "sztuka",
          "contentUnitDescription": "sztuka"
        },
        "overallInformation": {
          "brandDescription": "test brand",
          "description": "test description",
          "manufacturerName": "manufacturer", 
          "productName": "test name"
        },
        
        "productId": "prod3.1.1",
  
         "relatedProducts": [  
         
        ],
        "searchAttributes": {
          
        },
        "seoAttributes": {
        
        },
        "urlInformation": {
          "certificates": [
           
          ],
          "photos": [
           
          ],
          "productCards": [
           
          ]
        
      }
  }

POST - Import a list of products

In order to import a list of products use POST /api/v1/catalog/integrations/auth-required/products/import. The diagram below shows the dependency of communicating with the API:

Example request:

json
curl -X POST
"https://api-preprod.one.unity.pl/api/v1/catalog/integrations/auth-required/products/import-selected?ids=BUD_12414" 
-H  "accept: */*" 
-H  "one-tenant: {tenant}" 
-H  "ApiAuth: {apiKey}"
-d "[{
    "attributes":[
  {
  "attributeId":"color",
  "description":"Color",
  "type":"ALPHANUMERIC",
  "unit":{
  "longDescription":"color",
  "shortDescription":"col",
  "unitCode":"m123"
  },
  "value":{
  "code":"green",
  "label":"green"
  }
  }
  ],
  "categoryInformation": {  -- required
    "canonicalCategoryId": "kategoria1",  -- required
    "categoriesIds": [  -- required
      "kategoria1"
    ]},
      "labels": [   -- required
        "Ecommerce"
      ],
      "orderInformation": {   -- required
        "contentUnitCode": "pack",   -- required
        "orderUnitCode": "pack123",   -- required
        "packingQuantity": 2,   -- required
        "quantityInterval": 2,   -- required
        "quantityMin": 2,   -- required
        "orderUnitDescription": "pack",
        "contentUnitDescription": "pack"
      },
      "overallInformation": {
        "brandDescription": "test brand",
        "brandName": "test bran name",
        "cableType": "DRUM_CABLE",
        "description": "test description",
        "gtin": "5901234560009",
        "gtu": "5901234560009",
        "manufacturerAcronym": "manu",
        "manufacturerId": "manu123",   -- required
        "manufacturerName": "manufactura",   -- required
        "manufacturerPid": "manu123",
        "netDepth": 2,
        "netDiameter": 2,
        "netLength": 2,
        "netVolume": 2,
        "netWeight": 2,
        "netWidth": 2,
        "productName": "test name",   -- required
        "productSeries": "test series",
        "productStatus": "ACTIVE",
        "shippingTime": "24H",
        "shortDescription": "test short",
        "splitPayment": true,
        "surchargePriceAmount": 23,
        "taxReverseCharged": true,
        "usage": "test usage"
      },
      "packagingInformation": [
        {
          "depth": 2,
          "diameter": 2,
          "gtin": "5901234560009",
          "length": 2,
          "packagingProductId": "pack",
          "packagingUnitCode": "pack",
          "packagingUnitName": "pack",
          "quantityMax": 2,
          "quantityMin": 2,
          "volume": 2,
          "weight": 2,
          "width": 2
        }
      ],
      "priceInformation": {
        "tax": 0.23
      },
      "productId": "id-test",  -- required
      "relatedProducts": [  -- required
        {
          "relatedProductId": "888",  -- required
          "relationType": "ACCESSORIES",  -- required
          "quantity": 1
        }
      ],
      "relationsIds": [
        "12345"
      ],
      "searchAttributes": {  -- required
        "rank": 10
      },
      "seoAttributes": {  -- required
        "title": "test seo",
        "description": "test sero",
        "h1": "test h1",
        "follow": true,
        "index": true
      },
      "urlInformation": {  -- required
        "certificates": [
          {
            "url": "[url]",
            "fileName": "test name",
            "alt": "alt test text"
          }
        ],
        "energyClass": {
          "cardUrl": "[url]",
          "labelUrl": "alt test text"
        },
        "photos": [  -- required
          {
            "url": "[url]",
            "fileName": "test name",
            "alt": "alt test text"
          }
        ],
        "productCards": [  -- required
          {
            "url": "[url]",
            "fileName": "test name",
            "alt": "alt test text"
          }
        ],
        "videos": [
          {
            "url": "[url]",
            "fileName": "test name",
            "alt": "alt test text"
         }
       ]
     }},
     {
   
 "categoryInformation": { 
   "canonicalCategoryId": "kategoria1",  
   "categoriesIds": [  
     "kategoria1"
   ]},
     "labels": [   
       "Ecommerce"
     ],
     "orderInformation": {
       "contentUnitCode": "pack",
       "orderUnitCode": "pack123",
       "packingQuantity": 2,
       "quantityInterval": 2,
       "quantityMin": 2
     },
     "overallInformation": {
       
     
       "manufacturerId": "manu123",
       "manufacturerName": "manufactura",
      
       "productName": "new product"
       
     },
    
     
     "productId": "1255118",  
     "relatedProducts": [ 
       
     ],
     
     "searchAttributes": { 
      
     },
     "seoAttributes": {  
      
     },
     "urlInformation": { 
      
       "photos": [ 
         
       ],
       "productCards": [ 
         
       ]
     }
   }]

⚠️

Attention! There are different models depending on the type of the product attribute. for the NUMERIC type, the model looks like this:

json
{
	"type": "NUMERIC",
	"attributeId": "",
	"description": "",
	"value": 1,
	"unit": {
		"unitCode": "",
		"shortDescription": "",
		"longDescription": ""
	}
}

for the LOGIC type, the model looks like this:

json
{
	"type": "LOGIC",
	"attributeId": "",
	"description": "",
	"value": true,
	"unit": {
		"unitCode": "",
		"shortDescription": "",
		"longDescription": ""
	}
}

for the ALPHANUMERIC type, the model looks like this:

json
{
	"type": "ALPHANUMERIC",
	"attributeId": "",
	"description": "",
	"value": {
		"code": "",
		"label": ""
	},
	"unit": {
		"unitCode": "",
		"shortDescription": "",
		"longDescription": ""
	}
}

PATCH- Import a list of products with partial changes

In order to update a list of products with partial changes use PATCH /api/v1/catalog/integrations/auth-required/products/import. The diagram below shows the dependency of communicating with the API:

Example request:

json
curl -X PATCH
"https://api-preprod.one.unity.pl/api/v1/catalog/integrations/auth-required/products/import" 
-H  "accept: */*" 
-H  "one-tenant: {tenant}" 
-H  "ApiAuth: {apiKey}"
-d " [{ 
      "orderInformation": { 
        "quantityInterval": 10, 
        "quantityMin": 10
      },
      
      "productId": "id-test"
     },
     {
        "overallInformation": {
            "productName": "new name product"
         },
     "productId": "1255118"
   }]

POST - Import categories

In order to import categories use POST /api/v1/catalog/integrations/auth-required/products/import-categories. The diagram below shows the dependency of communicating with the API:

Example request:

json
[
  {
    "id": "kat1",
    "name": "Kategoria 1",
   
    "position": 1
   
  }
,
  {
    "id": "kat1.1",
    "name": "Kategoria 1.1",
    "parentId": "kat1",
    "position": 1
   
  },

  {
    "id": "kat1.1.1",
    "name": "Kategoria 1.1.1",
    "parentId": "kat1.1",
    "position": 1
   
  },

  {
    "id": "kat2",
    "name": "Kategoria 2",
    "position": 2
   
  },

  {
    "id": "kat2.1",
    "name": "Kategoria 2.1",
    "parentId": "kat2",
    "position": 1
   
  },

  {
    "id": "kat2.1.1",
    "name": "Kategoria 2.1.1",
    "parentId": "kat2.1",
    "position": 1
   
  },

  {
    "id": "kat3",
    "name": "Kategoria 3",
    "position": 3
   
  },

  {
    "id": "kat3.1",
    "name": "Kategoria 3.1",
    "parentId": "kat3",
    "position": 1
   
  },

  {
    "id": "kat3.1.1",
    "name": "Kategoria 3.1.1",
    "parentId": "kat3.1",
    "position": 1
   
  }
]

⚠️

Attention! In order to create categories tree levels (main and subcategories), first create a category using the POST method, and then add the parentId using the PATCH method

PATCH- Import categories with partial changes

In order to update categories with partial changes use PATCH /api/v1/catalog/integrations/auth-required/products/import-categories. The diagram below shows the dependency of communicating with the API:

Example request:

json
curl -X PATCH
"https://api-preprod.one.unity.pl/api/v1/catalog/integrations/auth-required/products/import-categories" 
-H  "accept: */*" 
-H  "one-tenant: {tenant}" 
-H  "ApiAuth: {apiKey}"
-d "[
  {
    "id": "kategoria1",
    "name": "best category"
 
  }
]

An example of creating a parent category:

json
[
  {
    "id": "kategoria5",
    "name": "kategoria 5",
 "parentId": "kategoria4"
 
  }
]

POST - Import a single product

In order to import single product use POST /api/v1/catalog/integrations/auth-required/products/import-one. The diagram below shows the dependency of communicating with the API:

Example request:

json
curl -X POST
"https://api-preprod.one.unity.pl/api/v1/catalog/integrations/auth-required/products/import-one" 
-H  "accept: */*" 
-H  "one-tenant: {tenant}" 
-H  "ApiAuth: {apiKey}"
-d " 
    {
     "attributes":[
  {
  "attributeId":"color",
  "description":"Color",
  "type":"ALPHANUMERIC",
  "unit":{
  "longDescription":"color",
  "shortDescription":"col",
  "unitCode":"m123"
  },
  "value":{
  "code":"green",
  "label":"green"
  }
  }
  ],
  "categoryInformation": {  -- required
    "canonicalCategoryId": "kategoria1",  -- required
    "categoriesIds": [  -- required
      "kategoria1"
    ]},
      "labels": [   -- required
        "Ecommerce"
      ],
      "orderInformation": {   -- required
        "contentUnitCode": "szt.",   -- required
        "orderUnitCode": "szt.",   -- required
        "packingQuantity": 1,   -- required
        "quantityInterval": 1,   -- required
        "quantityMin": 1,   -- required
        "orderUnitDescription": "sztuka",
        "contentUnitDescription": "sztuka"
      },
      "overallInformation": {
        "brandDescription": "test brand",
        "brandName": "test bran name",
        "cableType": "DRUM_CABLE",
        "description": "test description",
        "gtin": "5901234560009",
        "gtu": "5901234560009",
        "manufacturerAcronym": "manu",
        "manufacturerId": "manu123",  
        "manufacturerName": "manufactura",   -- required
        "manufacturerPid": "manu123",
        "netDepth": 2,
        "netDiameter": 2,
        "netLength": 2,
        "netVolume": 2,
        "netWeight": 2,
        "netWidth": 2,
        "productName": "test name",   -- required
        "productSeries": "test series",
        "productStatus": "ACTIVE",
        "shippingTime": "24H",
        "shortDescription": "test short",
        "splitPayment": true,
        "surchargePriceAmount": 23,
        "taxReverseCharged": true,
        "usage": "test usage"
      },
      "packagingInformation": [
        {
          "depth": 2,
          "diameter": 2,
          "gtin": "5901234560009",
          "length": 2,
          "packagingProductId": "szt",
          "packagingUnitCode": "szt",
          "packagingUnitName": "szt",
          "quantityMax": 1,
          "quantityMin": 1,
          "volume": 2,
          "weight": 2,
          "width": 2
        }
      ],
      "priceInformation": {
        "tax": 0.23
      },
      "productId": "id-test",  -- required
      "relatedProducts": [  -- required
        {
          "relatedProductId": "888",  -- required
          "relationType": "ACCESSORIES",  -- required
          "quantity": 1
        }
      ],
      "relationsIds": [
        "12345"
      ],
      "searchAttributes": {  -- required
        "rank": 10
      },
      "seoAttributes": {  -- required
        "title": "test seo",
        "description": "test sero",
        "h1": "test h1",
        "follow": true,
        "index": true
      },
      "urlInformation": {  -- required
        "certificates": [
          {
            "url": "[url]",
            "fileName": "test name",
            "alt": "alt test text"
          }
        ],
        "energyClass": {
          "cardUrl": "[url]",
          "labelUrl": "alt test text"
        },
        "photos": [  -- required
          {
            "url": "[url]",
            "fileName": "test name",
            "alt": "alt test text"
          }
        ],
        "productCards": [  -- required
          {
            "url": "[url]",
            "fileName": "test name",
            "alt": "alt test text"
          }
        ],
        "videos": [
          {
            "url": "[url]",
            "fileName": "test name",
            "alt": "alt test text"
          }
        ]
      }
    }

⚠️

Attention! There are different models depending on the type of the product attribute. for the NUMERIC type, the model looks like this:

json
{
	"type": "NUMERIC",
	"attributeId": "",
	"description": "",
	"value": 1,
	"unit": {
		"unitCode": "",
		"shortDescription": "",
		"longDescription": ""
	}
}

for the LOGIC type, the model looks like this:

json
{
	"type": "LOGIC",
	"attributeId": "",
	"description": "",
	"value": true,
	"unit": {
		"unitCode": "",
		"shortDescription": "",
		"longDescription": ""
	}
}

for the ALPHANUMERIC type, the model looks like this:

json
{
	"type": "ALPHANUMERIC",
	"attributeId": "",
	"description": "",
	"value": {
		"code": "",
		"label": ""
	},
	"unit": {
		"unitCode": "",
		"shortDescription": "",
		"longDescription": ""
	}
}

In addition, there can be multiple values for the ALPHANUMERIC type. Model example below:

json
{
	"type": "ALPHANUMERIC",
	"attributeId": "Color",
	"description": "Color",
	"value": {
		"code": "Black",
		"label": "Black"
	},
	"unit": {
		"unitCode": "",
		"shortDescription": "",
		"longDescription": ""
	}
},
{
	"type": "ALPHANUMERIC",
	"attributeId": "Color",
	"description": "Color",
	"value": {
		"code": "White",
		"label": "White"
	},
	"unit": {
		"unitCode": "",
		"shortDescription": "",
		"longDescription": ""
	}
},
{
	"type": "ALPHANUMERIC",
	"attributeId": "Color",
	"description": "Color",
	"value": {
		"code": "Green",
		"label": "Green"
	},
	"unit": {
		"unitCode": "",
		"shortDescription": "",
		"longDescription": ""
	}
}

PATCH- Import a single product with partial changes

In order to update a single product with partial changes use PATCH /api/v1/catalog/integrations/auth-required/products/import-one. The diagram below shows the dependency of communicating with the API:

Example request:

json
curl -X PATCH
"https://api-preprod.one.unity.pl/api/v1/catalog/integrations/auth-required/products/import-one" 
-H  "accept: */*" 
-H  "one-tenant: {tenant}" 
-H  "ApiAuth: {apiKey}"
-d " {
    
      "orderInformation": { 
        
        "quantityInterval": 50, 
        "quantityMin": 50
       
      },
      
      "productId": "id-test"
     }

POST - Import relations

In order to import relations use POST /api/v1/catalog/integrations/auth-required/products/import-relations. The diagram below shows the dependency of communicating with the API:

Example request:

json
curl -X POST
"https://api-preprod.one.unity.pl/api/v1/catalog/integrations/auth-required/products/import-relations" 
-H  "accept: */*" 
-H  "one-tenant: {tenant}" 
-H  "ApiAuth: {apiKey}"
-d " [
  {
    "attribute": "shirt_color",
    "attributeName": "Color",
    "products": [
      {
        "attributeValue": "Purple",
        "productId": 888
      }
    ],
    "relationId": 12345
  }
]

PATCH- Import relations with partial changes

In order to update relations use PATCH /api/v1/catalog/integrations/auth-required/products/import-relations. The diagram below shows the dependency of communicating with the API:

Example request:

json
curl -X PATCH
"https://api-preprod.one.unity.pl/api/v1/catalog/integrations/auth-required/products/import-relations" 
-H  "accept: */*" 
-H  "one-tenant: {tenant}" 
-H  "ApiAuth: {apiKey}"
-d " [
  {
    "attribute": "shirt_color",
    "attributeName": "Color",
    "products": [
      {
        "attributeValue": "Purple",
        "productId": 54321
      },
{
        "attributeValue": "green",
        "productId": 888
      }
    ],
    "relationId": 12345
  }
]

External Import

Table of contents

Glossary

POST - Import single product packagings

POST - Import a list of products

PATCH- Import a list of products with partial changes

POST - Import categories

PATCH- Import categories with partial changes

POST - Import a single product

PATCH- Import a single product with partial changes

POST - Import relations

PATCH- Import relations with partial changes