# Use Case: Real-Time Manifest Creation

## Overview

Real-time manifest synchronization with WMS allocation data. The integration
creates manifests in Zimark when orders reach "fully allocated" status in the
WMS, extracting pallet IDs from order allocations. Subsequent allocation
changes in the WMS trigger manifest updates, ensuring Zimark reflects the
current state of assets ready for loading.

## Business Context

### Setting

A 3PL warehouse handles inbound shipments from multiple clients. During inbound
receiving, Zimark markers are printed and scanned, creating tracks that link
WMS pallet IDs to Zimark markers. This use case focuses on outbound shipments:
orders leaving the 3PL warehouse to supply client locations.

### Order Flow

Clients place orders directly into the 3PL's WMS. These orders progress through
allocation, picking, and loading stages before shipment.

## Integration Requirements

The integration must:

- ✅ Create manifests only when orders are fully allocated in the WMS
- ✅ Process allocation changes in real-time and update Zimark manifests
- ✅ Include customer name in manifest metadata
- ✅ Handle pallet substitutions during picking (see step 4 below)


## Warehouse Process Flow

### 1. Order Creation

**Action:** Client creates order in WMS

**WMS Order Status:** `CREATED`

**Trigger:** WMS sends webhook/event with status `CREATED`

**Zimark Action:** None (too early - not allocated yet)

### 2. Order Updates

**Action:** Warehouse staff add/modify order details

**WMS Order Status:** `IN_PROGRESS`

**Trigger:** WMS sends webhook/event with status `UPDATED`

**Zimark Action:** None (wait for full allocation)

### 3. Inventory Allocation

**Action:** WMS allocates specific pallet IDs to the order

**WMS Order Status:** `IN_PROGRESS`

**Trigger:** WMS sends webhook/event when status changes to `FULLY_ALLOCATED`

**Zimark Action:** ✅ **CREATE MANIFEST** with allocated pallet IDs

### 4. Picking (Pallet Substitution)

**Action:** Warehouse operators pick pallets. Sometimes they substitute pallets:

- Original allocation: Pallet A (damaged or inaccessible)
- Actually picked: Pallet B (same SKU, same quantity)


**WMS Order Status:** `PICKING`

**Example:**

- Allocated: `LPN00012345` (SKU: WIDGET-A, Qty: 100)
- Picked: `LPN00067890` (SKU: WIDGET-A, Qty: 100)


**Trigger:** WMS sends webhook/event with status `UPDATED`

**Zimark Action:** ✅ **UPDATE MANIFEST** - remove old pallet, add new pallet

### 5. Staging & Loading

**Action:** Pallets staged at dock, ready for loading

**WMS Status:** `READY_TO_LOAD`

**Zimark Action:** Gate scans pallets, validates against manifest

### 6. Loading Complete

**WMS Status:** `SHIPPED`
**Action:** All pallets loaded, truck departs
**Zimark Action:** Manifest status → `COMPLETED`, proof of load captured

## Key Integration Points

### Integration Point 1: Manifest Check

**Trigger:** WMS order status → `UPDATED`

**API Call:** `GET /manifest/11391`

**Data Required:**

- Order ID (becomes manifest external ID)


cURL

```bash
curl -X GET "https://api.zimark.link/integration/rest/api/v1/manifest/11391" \
  -H "X-AUTH-KEY: ZIM.your-api-key-here" \
  -H "Content-Type: application/json"
```

JavaScript

```javascript
const response = await fetch(
  'https://api.zimark.link/integration/rest/api/v1/manifest/11391',
  {
    headers: {
      'X-AUTH-KEY': 'ZIM.your-api-key-here',
      'Content-Type': 'application/json'
    }
  }
);

const data = await response.json();
console.log(data);
```

Python

```python
import requests

headers = {
    'X-AUTH-KEY': 'ZIM.your-api-key-here',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.zimark.link/integration/rest/api/v1/manifest/11391',
    headers=headers
   
)

print(response.json())
```

### Response


```json
[
  {
    "uuid": "6a7132c4-a035-4602-a1af-baa0b5569e17",
    "createDate": 1761075979161,
    "updateDate": 1761680381300,
    "externalIdentifier": "11391",
    "manifestStatus": "PLANNED",
    "closeDate": 1761680381204,
    "tracksCount": 2,
    "gate": {
      "uuid": "b1298231-0725-4a73-9840-d15fa49acc5e",
      "name": "Gate1",
      "externalIdentifier": "Gate1"
    },
    "customFields": [
      {
        "fieldKey": "customerName",
        "fieldValue": "ACME"
      }
    ],
    "deleted": false
  }
]
```

### Integration Point 2: Manifest Creation

**Trigger:** WMS order status → `FULLY_ALLOCATED`

**API Call:** `POST /manifests`

**Data Required:**

- Order ID (becomes manifest external ID)
- Customer name
- List of allocated pallet IDs


cURL

```bash
curl -X POST "https://api.zimark.link/integration/rest/api/v1/manifest" \
  -H "X-AUTH-KEY: ZIM.your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": 11391,
    "assets": ["LPN00012345","LPN000123456"],
    "customFields": [
      {
        "fieldKey": "customerName",
        "fieldValue": "ACME"
      }
    ]
  }'
```

JavaScript

```javascript
const headers = {
  'X-AUTH-KEY': 'ZIM.your-api-key-here',
  'Content-Type': 'application/json'
};

const body = {
  identifier: 11391,
  assets: ['LPN00012345', 'LPN000123456'],
  customFields: [
    { fieldKey: 'customerName', fieldValue: 'ACME' }
  ]
};

const response = await fetch(
  'https://api.zimark.link/integration/rest/api/v1/manifest',
  {
    method: 'POST',
    headers,
    body: JSON.stringify(body)
  }
);

console.log(await response.json());
```

Python

```python
import requests

headers = {
    'X-AUTH-KEY': 'ZIM.your-api-key-here',
    'Content-Type': 'application/json'
}

payload = {
    "identifier": 11391,
    "assets": ["LPN00012345","LPN000123456"],
    "customFields": [
        {"fieldKey": "customerName", "fieldValue": "ACME"}
    ]
}

response = requests.post(
    'https://api.zimark.link/integration/rest/api/v1/manifest',
    headers=headers,
    json=payload
)

print(response.json())
```

### Integration Point 3: Manifest Update (Pallet Substitution)

**Trigger:** WMS allocation modified (pallet substitution during picking)

**API Call:**
/manifest/11391

cURL

```bash
curl -X PUT "https://api.zimark.link/integration/rest/api/v1/manifest/11391" \
  -H "X-AUTH-KEY: ZIM.your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "assets": ["LPN00012345","LPN111222"]
  }'
```

JavaScript

```javascript
const headers = {
  'X-AUTH-KEY': 'ZIM.your-api-key-here',
  'Content-Type': 'application/json'
};

const body = {
  assets: ["LPN00012345","LPN111222"],
};

const response = await fetch(
  'https://api.zimark.link/integration/rest/api/v1/manifest/11391',
  {
    method: 'PUT',
    headers,
    body: JSON.stringify(body)
  }
);

console.log(await response.json());
```

Python

```python
import requests

headers = {
    'X-AUTH-KEY': 'ZIM.your-api-key-here',
    'Content-Type': 'application/json'
}

payload = {
   "assets": ["LPN00012345","LPN111222"]  
}

response = requests.put(
    'https://api.zimark.link/integration/rest/api/v1/manifest/11391',
    headers=headers,
    json=payload
)

print(response.json())
```

## Success Criteria

- ✅ Manifests created within 5 seconds of WMS reaching `FULLY_ALLOCATED`
- ✅ Pallet substitutions reflected in Zimark within 10 seconds
- ✅ Zero manifests created for incomplete allocations
- ✅ Customer name correctly populated in 100% of manifests