Skip to main content

Article Units

Frequency:

Article unit master data changes are required to be sent in near real-time. Any change to an interface field in the external system should trigger the interface.

Expected data:

The external system is expected to report at least two levels of article units:

  • Base unit (e.g., piece, kg)
  • Warehouse/distribution unit (e.g., block, crate, box, distribution package)
  • Layer and pallet levels are optional.

Countable articles: use piece as the base unit.

Weight articles (average or catch measure): use kg as the base unit.

For weight articles (average or catch measure), the coefficient to the warehouse/distribution unit should be equal to 1.

Technical:

The DSMDS unit hierarchy should be mapped to the external system.

The article must already exist in DSMDS.

Each unit_id must be a unit configured for the client in DSMDS.

Units are matched by article_unit_type_id. If an article unit of that type does not exist in DSMDS, it will be created; otherwise, it will be updated. Existing units whose type is not in the message are left unchanged; no units are deleted.

Only the first unit of each type in the request is saved. Validation, however, runs on all units, including further units of the same type, so an invalid duplicate still prevents the article's units from being saved.

If any unit of an article produces a warning, none of the units of that article are saved. The other articles in the request are still processed.

Default values (0 / false) apply only when a field is omitted. A number field sent explicitly as null produces a warning, and no units are saved for that article. "order_unit": null fails the whole request with 409.

If volume is 0 or omitted, a default volume is used: 1000 cm³ if the article's picking method is weight; otherwise 1000 cm³ for the base unit and 27000 cm³ for warehouse, layer and pallet units.

Numeric limits: gross_weight, net_weight, height, length, width and coefficient allow at most 7 integer digits and 3 decimal places; volume allows at most 20 integer digits and 10 decimal places. A value exceeding these limits fails the request with 409, and no units from the request are saved (the request is processed in a single transaction).

POST https://{url}/articles/units/v1​

Create or update article units.

Request Body​

The request body is a JSON array of objects. Each object contains an article_id and a units array with the unit details.

Top-level object:

NameTypeRequiredDescription
article_idstringYesArticle unique identifier in the external system
unitsarrayYesArray of unit objects for the article. Must not be empty

Unit object (inside units array):

NameTypeRequiredDescription
unit_idstringYesUnit of measure identifier in the external system
article_unit_type_idintegerYesUnit type: 1 - base unit, 2 - warehouse unit, 3 - layer unit, 4 - pallet unit
coefficientnumberYesConversion coefficient to the lower unit of measure (e.g., from warehouse unit to base unit). Max 7 integer digits, 3 decimals
gross_weightnumberNoUnit gross weight in kg. Defaults to 0 if omitted. Max 7 integer digits, 3 decimals
net_weightnumberNoUnit net weight in kg. Defaults to 0 if omitted. Max 7 integer digits, 3 decimals
heightnumberNoUnit height in cm. Defaults to 0 if omitted. Max 7 integer digits, 3 decimals
lengthnumberNoUnit length in cm. Defaults to 0 if omitted. Max 7 integer digits, 3 decimals
widthnumberNoUnit width in cm. Defaults to 0 if omitted. Max 7 integer digits, 3 decimals
volumenumberNoUnit volume in cm³. If 0 or omitted, a default volume is used. Max 20 integer digits, 10 decimals
order_unitbooleanNoWhether this unit is the order unit. Defaults to false if omitted; must not be null. At most one unit per article can be true

Request Example​

[
    {
        "article_id": "0001",
        "units": [
            {
                "unit_id": "PCS",
                "article_unit_type_id": 1,
                "coefficient": 1,
                "gross_weight": 1.1,
                "net_weight": 1.0,
                "height": 30.0,
                "length": 8.0,
                "width": 8.0,
                "volume": 1920.0,
                "order_unit": false
            },
            {
                "unit_id": "DPA",
                "article_unit_type_id": 2,
                "coefficient": 6,
                "gross_weight": 6.6,
                "net_weight": 6.0,
                "height": 31.0,
                "length": 25.0,
                "width": 17.0,
                "volume": 13175.0,
                "order_unit": true
            }
        ]
    },
    {
        "article_id": "0047",
        "units": [
            {
                "unit_id": "PCS",
                "article_unit_type_id": 1,
                "coefficient": 1,
                "gross_weight": 0.55,
                "net_weight": 0.5,
                "height": 20.0,
                "length": 6.5,
                "width": 6.5,
                "volume": 845.0
            }
        ]
    }
]

Response​

200: OK — Success​

{
    "success": true,
    "message": "",
    "data": null,
    "warnings": []
}

200: OK — Success with warnings​

{
    "success": true,
    "message": null,
    "data": null,
    "warnings": [
        "Article not found by external ID '0001' for client 20",
        "Article 0047 unit BOX is not defined for client 20 and will be ignored",
        "Received empty unit list for article '0048'",
        "Article 0049 units have more then 1 order_unit for client 20 and will be ignored"
    ]
}

200: OK — Error​

{
    "success": false,
    "message": "Failed to map JSON",
    "data": null,
    "warnings": []
}