Bulk upsert catalogue items

Upserts up to 50 catalogue items in one call, matched within this company only.

Matching. Each row is matched by id first. Send the item’s id to update it even when its name changes. A row without an id falls back to matching on names.en, which is therefore required on those rows. A row addressed by id may leave names out, which is how you do a partial update. A match updates the item in place. No match creates it.

One row per item. An item is claimed by the first row that actually saves to it. A later row that resolves to the same item fails with duplicate_match instead of overwriting the earlier write. A row whose save failed wrote nothing, so it does not claim the item and a later row may still update it.

Per-row results. The response is always 200 with upserted and errors. upserted holds the saved rows in the read shape, in payload order, each with an action of created or updated. errors holds one envelope per failed row, carrying data (the row exactly as you sent it), errorCode, message, an optional errorField and details, and the 0-based row index. Each saved row commits in its own transaction, so a later failure cannot roll it back.

Error codes. The values are snake_case on the wire. The camelCase rendering of this API applies to keys, never to values, so you match on unknown_id, not on unknownId. All five:

• invalid_id: the id is not a UUID. An empty string counts, so an exporter that writes a missing id as "" gets an error rather than a duplicate.
• unknown_id: a well formed id that resolves to nothing in this company. Unknown, foreign and soft-deleted are the same answer on purpose.
• duplicate_match: the row resolves to an item an earlier row already saved to. details carries firstRow and itemId.
• validation_error: the write serializer rejected the row and details carries the field errors, or the row has no id and no names.en to match on, in which case errorField is names, or the save tripped a model guard such as the duplicate-name check.
• unexpected: anything else the row’s own save raised. One surprising row cannot take down a batch whose other rows are already committed.

Two id-less rows carrying the same new name are the one duplicate the claim guard cannot see, because there is nothing yet to claim. The first creates and the second fails the duplicate-name check as validation_error.

Only three failures reject the whole request with 400 and write nothing: a body that is not a JSON array, an entry that is not an object, and more than 50 rows.

Requires master-data:write.