# Splitting & Combining Consignments

## Objective

Split a large consignment into smaller parts for separate delivery, or combine multiple consignments into one consolidated shipment.

## Scenario: Splitting

You have a consignment of 120 pallets that needs to be split across two trucks because a single vehicle can only carry 66 pallets.

### Step 1: Create the Transport Order


```bash
curl -X POST https://api.otms.transportial.com/api/transportOrder \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Bulk delivery - 120 pallets",
    "status": "requested",
    "consignments": [
      {
        "name": "Full consignment",
        "status": "requested",
        "goods": [
          {
            "type": "items",
            "description": "Packaged food products",
            "quantity": 120,
            "weight": { "value": 24000, "unit": "kg" }
          }
        ]
      }
    ]
  }'
```

Note the `consignment.id` and `goods.id` from the response.

### Step 2: Split the Consignment


```bash
curl -X POST https://api.otms.transportial.com/api/consignments/split \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "consignmentId": "original-consignment-uuid",
    "splits": [
      {
        "goods": [
          {
            "id": "goods-uuid",
            "quantity": 66
          }
        ]
      },
      {
        "goods": [
          {
            "id": "goods-uuid",
            "quantity": 54
          }
        ]
      }
    ]
  }'
```

This creates two new consignments from the original — one with 66 pallets and one with 54.

### Step 3: Plan Separate Trips

Now plan a trip for each split consignment:


```bash
# Trip for first part (66 pallets)
curl -X POST https://api.otms.transportial.com/api/trip:route \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Delivery part 1 - 66 pallets",
    "type": "road",
    "vehicle": { "id": "truck-1-uuid" },
    "actions": [
      { "type": "load", "location": { "id": "warehouse-uuid" } },
      { "type": "move" },
      { "type": "unload", "location": { "id": "destination-uuid" } }
    ]
  }'

# Trip for second part (54 pallets)
curl -X POST https://api.otms.transportial.com/api/trip:route \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Delivery part 2 - 54 pallets",
    "type": "road",
    "vehicle": { "id": "truck-2-uuid" },
    "actions": [
      { "type": "load", "location": { "id": "warehouse-uuid" } },
      { "type": "move" },
      { "type": "unload", "location": { "id": "destination-uuid" } }
    ]
  }'
```

## Scenario: Combining

You have three small consignments going to the same destination. Combine them into one for a single trip.

### Step 1: Identify the Consignments


```bash
# Search for consignments going to the same destination
curl -X POST "https://api.otms.transportial.com/api/consignments/0/20" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "status": "requested"
  }'
```

### Step 2: Combine the Consignments


```bash
curl -X POST https://api.otms.transportial.com/api/consignments/combine \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "consignmentIds": [
      "consignment-uuid-1",
      "consignment-uuid-2",
      "consignment-uuid-3"
    ]
  }'
```

This merges the goods from all three consignments into a single consignment.

### Step 3: Plan One Trip


```bash
curl -X POST https://api.otms.transportial.com/api/trip:route \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Consolidated delivery",
    "type": "road",
    "vehicle": { "id": "truck-uuid" },
    "actions": [
      { "type": "load", "location": { "id": "warehouse-uuid" } },
      { "type": "move" },
      { "type": "unload", "location": { "id": "destination-uuid" } }
    ]
  }'
```

## Partial Status Tracking

After splitting, consignments can be in partial states:

| Status | Meaning |
|  --- | --- |
| `partially_planned` | Some splits have trips, others don't |
| `partially_in_transit` | Some splits are moving, others aren't |
| `partially_completed` | Some splits are delivered |


The transport order reflects the aggregate status of all its consignments.

## Key Takeaways

- **Split** when goods need separate vehicles, routes, or delivery windows
- **Combine** to consolidate small shipments for efficiency
- Partial statuses track progress across split consignments
- Each split can have its own trip, vehicle, and chauffeur assignment