Update commercial order shipping info

The updateCommercialOrderShippingInfo function updates the shipping information and delivery preferences for an existing commercial order. This function allows modification of shipping methods, carrier preferences, delivery timing, and other shipping-related parameters. It is essential for order customization and delivery optimization workflows.

This function is typically used when customers need to change delivery speed, specify special delivery instructions, or when logistics optimization requires different shipping configurations.

Process Flow

sequenceDiagram
    participant User as User
    participant Component as Vue Component
    participant UCO as useCommercialOrder
    participant Auth as Authentication
    participant API as Order API
    participant Shipping as Shipping Service
    participant DB as Database

    User->>Component: Update Shipping Info
    Component->>UCO: updateCommercialOrderShippingInfo(params)
    UCO->>Auth: ensureAuthenticated()

    alt Authentication Valid
        Auth-->>UCO: Authenticated
        UCO->>API: PUT /api/commercial-orders/{orderId}/shipping-information
        API->>Shipping: Validate Shipping Options
        Shipping-->>API: Shipping Valid
        API->>DB: Update Order Shipping Info
        DB-->>API: Update Successful
        API-->>UCO: Update Response
        UCO-->>Component: Success Response
        Component-->>User: Confirmation Message
    else Authentication Failed
        Auth-->>UCO: Authentication Error
        UCO-->>Component: Error Response
        Component-->>User: Redirect to Login
    else Invalid Shipping Options
        Shipping-->>API: Invalid Configuration
        API-->>UCO: 400 Error
        UCO-->>Component: Validation Error
        Component-->>User: Show Validation Message
    else Order Not Modifiable
        API-->>UCO: 412 Error
        UCO-->>Component: Precondition Failed
        Component-->>User: Show Order Status Message
    end

Call Parameters

Request Interface

interface UpdateCommercialOrderShippingInformationRequest {
  orderId: string;
  shippingAddressId: string;
  shippingType: string;
}

Parameters Detail

Example Call

const { updateCommercialOrderShippingInfo } = useCommercialOrder();

// Update to express shipping
const updateResult = await updateCommercialOrderShippingInfo({
  orderId: "co-123456",
  shippingAddressId: "addr-789012",
  shippingType: "express",
});

console.log("Shipping info updated:", updateResult.success);

Composable Returns

Response Interface

interface UpdateCommercialOrderShippingInformationResponse {
  success: boolean;
  order: CommercialOrder;
  message: string;
}

Response Structure

{
  "success": true,
  "order": {
    "id": "co-123456",
    "reference": "CO-2024-001",
    "status": "CREATED",
    "totalPrice": 1275.99,
    "totalPriceWithoutTax": 1042.49,
    "totalTaxAmount": 208.5,
    "totalShippingFees": 25.0,
    "currency": "EUR",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-16T16:15:00Z",
    "shippingInformation": {
      "type": "express",
      "addressId": "addr-789012",
      "carrier": "DHL Express",
      "estimatedDeliveryDate": "2024-01-17T18:00:00Z",
      "trackingAvailable": true,
      "insuranceIncluded": true,
      "signatureRequired": true,
      "notes": "Express delivery - signature required",
      "cost": 25.0,
      "currency": "EUR"
    },
    "customFields": [
      {
        "externalId": "shipping-change-reason",
        "value": "Customer requested faster delivery",
        "type": "text",
        "label": "Shipping Change Reason"
      }
    ]
  },
  "message": "Shipping information updated successfully"
}

Use Cases

1. Delivery Speed Modification

Allow customers to upgrade or downgrade shipping speed:

• Change from standard to express delivery
• Downgrade to economy shipping for cost savings
• Switch to overnight delivery for urgent orders
• Update delivery timeframes and costs accordingly

2. Carrier Preference Updates

Enable carrier selection for optimal delivery:

• Choose preferred shipping carrier
• Select carrier based on destination requirements
• Handle carrier-specific delivery options
• Manage carrier availability by region

3. Special Delivery Requirements

Accommodate special delivery needs:

• Add signature confirmation requirements
• Include insurance for high-value items
• Specify delivery time windows
• Add special handling instructions

4. Cost Optimization

Optimize shipping costs based on requirements:

• Balance cost vs delivery speed
• Minimize shipping expenses for budget orders
• Maximize delivery reliability for critical shipments
• Handle bulk shipping discounts

This function provides comprehensive shipping information management with proper validation, cost calculation, and delivery optimization capabilities.