Move a Barcode from One Product to Another

Description

This use case describes the process of transferring a barcode from one product (source SKU) to another (target SKU) through external API calls.
The process is composed of two main API invocations:

Delete barcode — to remove the barcode from the original product.

Insert barcode — to associate the barcode with the new product.

The operation ensures data integrity and prevents duplicate or inconsistent barcode assignments across products.

Actors

API Client: The system or user initiating the request.

4ws.trade: The backend system that processes the request.

Preconditions

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

Monitoring / Alerting System: Handling integration errors and retries logs and warnings, as reported inBest Practices for Error Handling in External System.

The barcode specified in {BARCODE} must exist in the system.

Restrictions on Barcode Removal

Barcodes that have been included in warehouse or sales documents cannot be removed. This restriction ensures data consistency since these barcodes have already been used to manage inventory movements. However, it is possible to force deletion by bypassing this check using the ignore_movements=false parameter.

Barcodes in Documents

Deleting barcodes that are referenced in documents is a critical operation. It disrupts the alignment between products, SKUs/barcodes, documents, inventory, and warehouse movements.

Impact on Documents and Inventory: After removal, affected documents and inventory will still reflect the removed barcode. This discrepancy is further complicated if the barcode is later assigned to another product.

Warehouse Movements: Historical warehouse movements will show operations related to both the previous and current product assignments for the barcode.

Main Success Scenario

The external system identifies the barcode to move and the new target SKU.

The external system invokes the Delete barcode endpoint to remove the barcode from the current product.

The API validates that the barcode is not linked to any stock movements.

Upon success, the external system invokes Insert barcode to associate the barcode with the new SKU.

The system confirms the operation and logs it for audit purposes.

Alternate Flows

Barcode already moved: The Delete barcode call returns "This SKU/barcode has been already moved". The process should stop or retry with ignore_movements=true.

Target SKU not found: The The Delete barcode or Insert barcode call fails because the SKU or one of its variants does not exist. The system should log the error and stop the operation.

Barcode already associated: The Insert barcode call fails because the barcode was not properly deleted or is still linked to another SKU. The external system should check deletion status and retry later.

Sequence Diagram

Best Practices

Please refer to Best Practices for Error Handling in External System for best practices on implementation.

Move a Barcode from One Product to Another