Sale and Shipping costs

Use Case Description

This use case describes the process of validating an e-commerce shopping cart, with api Cart Validation ,that includes both products and shipping costs. Before proceeding with the sale, the e-commerce system needs to validate the cart to ensure that all items, including shipping charges, are correctly accounted for.

Scenario Overview

When customers purchase products from the e-commerce platform, the platform must calculate the total cost, including shipping. The shipping cost is treated as a product of type SERVICE with the subtype DELIVERY. This allows the e-commerce system to apply the shipping cost as a line item in the cart. Once validated, the cart can then be processed for sale using the Save sale service.

Actors

External System: The external system (ERP,WMS ecc...) initiating the order processing and stock transfer.

Cart Validation: The service that processes the cart and applies the relevant promotions.

Save sale or Save Order: The service that saves the validated cart as a sale.

Promotion Engine: The system that evaluates and applies promotions to the cart items.

Preconditions

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

The shopping cart is populated with the products and shipping costs.

The item representing the shipping cost is added to the cart with itemType: "SERVICE" and itemSubType: "DELIVERY".

APIs Used

Cart Validation: Validates the shopping cart, ensuring that all items, including shipping, are correctly included.

Save sale or Save Order: Saves the validated cart as a sale.

Main Success Scenario

Cart Preparation: The e-commerce platform adds items to the cart, including a shipping cost item.

Cart Validation: The platform invokes the Cart Validation API to validate the cart.

The API checks all items, including the shipping cost.

If the validation is successful, the cart is marked as ready for sale.

Sale Processing: The platform calls the Save sale or Save Order API to process the sale.

The sale is finalized, and payment is processed.

Alternate Flows

Validation Failure: If the cart validation fails, the API returns an error indicating the issue (e.g., invalid item type, missing product information).

Item Unavailability: If any item in the cart, including the shipping cost item, is no longer available, the platform must notify the customer and possibly revalidate the cart after adjustments.

JSON Structure for Sale Order Document

{
    "entityCode": "501",
    "branchCode": "1003",
    "currency": "EUR",
    "currencySymbol": "€",
    "discountsManualCumulative": "N",
    "filling": "FIRST",
    "registerCode": "1",
    "rounding": 2,
    "onlineValidation": "Y",
    "seller": "F**K",
    "sellerId": "333",
    "items": [
        {
            "rowId": "1313241694800",
            "rowType": "ITEM",
            "barcode": "8053289813603",
            "barcodeType": "BARCODE_ARTICOLO",
            "qty": 1,
            "qtyType": "N",
            "seller": "F**K",
            "sellerId": "333",
            "rowOrder": 1,
            "movementType": "V",
            "itemType": "PRODUCT",
            "itemSubType": "ITEM",
            "unitPrice": 85,
            "discount": 0,
            "channel": "IN_STORE"
        },
        {
            "rowId": "1313241697801",
            "rowType": "ITEM",
            "barcode": "8053289771224",
            "barcodeType": "BARCODE_ARTICOLO",
            "qty": 1,
            "qtyType": "N",
            "seller": "F**K",
            "sellerId": "333",
            "rowOrder": 2,
            "movementType": "V",
            "itemType": "PRODUCT",
            "itemSubType": "ITEM",
            "unitPrice": 79,
            "discount": 0,
            "channel": "IN_STORE"
        },
        {
            "rowId": "131324169749802",
            "rowType": "ITEM",
            "barcode": "9999821995668",
            "barcodeType": "BARCODE_ARTICOLO",
            "qty": 1,
            "rowOrder": 3,
            "movementType": "V",
            "itemType": "SERVICE",
            "itemSubType": "DELIVERY",
            "itemCode": "SPEDIZIONE",
            "unitPrice": 10,
            "discount": 0,
            "channel": "IN_STORE",
            "alreadyValidate": "Y"
        }
    ],
    "totals": {
        "total": 174
    },
    "payments": [
        {
            "channel": "IN_STORE",
            "paymentType": "E",
            "paymentAmount": 174,
            "paymentCode": "CC",
            "paymentDescription": "Carta di credito",
            "paymentProgr": "69e601812de7620f34b11bccc0400ahh",
            "paymentRoundingAmount": 0,
            "paymentDone": "Y"
        }
    ]
}

Callback Response

The response from the Cart Validation API will indicate whether the cart is valid and can be processed for sale, please refer to Cart Validation Service uses case.

Sequence Diagram

Code Examples in Node.js

Validate Cart Example

Save Sale Example

INFO

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

Sale and Shipping costs