# COLORJET Import/Warranty/Logistics — Node.js API Routes

Base URL:

```text
https://api.colorjetbd.com/api/v1/import-logistics
```

All routes require:

```http
Authorization: Bearer JWT_TOKEN
Content-Type: application/json
```

## 1. Summary KPI

```http
GET /api/v1/import-logistics/summary
```

Returns:

- open warranty RMA
- RMA at supplier
- shipments in transit
- customs pending
- pending receipts
- delayed shipments
- approved landed cost
- open claim amount
- recent RMA and shipments

## 2. Warranty RMA

### List

```http
GET /api/v1/import-logistics/rmas?status=draft&search=mainboard
```

### Create

```http
POST /api/v1/import-logistics/rmas
```

```json
{
  "customer_name": "ABC Printing House",
  "customer_phone": "01700000000",
  "supplier_id": 1,
  "machine_model": "Eco Solvent 3.2m",
  "machine_serial_number": "CJ-2026-0001",
  "board_type": "Mainboard",
  "board_serial_number": "MB-001",
  "fault_description": "Board not responding",
  "quantity": 1,
  "unit": "pcs",
  "currency": "USD"
}
```

### Update status

```http
PATCH /api/v1/import-logistics/rmas/1/status
```

```json
{
  "status": "sent_to_supplier",
  "note": "Sent by air courier"
}
```

Allowed RMA statuses:

```text
draft, received_from_customer, warranty_verified, ready_to_send_supplier, sent_to_supplier, supplier_received, under_repair, replacement_approved, return_in_transit, received_back, delivered_to_customer, closed, cancelled
```

## 3. Import Shipment

### List

```http
GET /api/v1/import-logistics/shipments?status=in_transit
```

### Create shipment with items

```http
POST /api/v1/import-logistics/shipments
```

```json
{
  "supplier_id": 1,
  "shipment_type": "new_purchase",
  "shipment_mode": "sea_cargo",
  "tracking_number": "TRACK-001",
  "eta_chittagong": "2026-08-10",
  "warehouse_name": "Dhaka Warehouse",
  "currency": "USD",
  "exchange_rate": 127,
  "items": [
    {
      "product_name": "Printer Mainboard",
      "sku": "MB-001",
      "ordered_qty": 5,
      "shipped_qty": 5,
      "unit": "pcs",
      "purchase_value": 350
    }
  ]
}
```

### Status update

```http
PATCH /api/v1/import-logistics/shipments/1/status
```

```json
{
  "status": "customs_clearance_pending",
  "note": "Documents submitted to C&F"
}
```

Allowed shipment statuses:

```text
draft, booking_confirmed, air_sea_departure, in_transit, chittagong_port_arrival, customs_clearance_pending, customs_cleared, local_transport, warehouse_received, qc_pending, received, closed, cancelled
```

### Add shipment item

```http
POST /api/v1/import-logistics/shipments/1/items
```

### Add shipment cost

```http
POST /api/v1/import-logistics/shipments/1/costs
```

```json
{
  "cost_head": "customs_duty",
  "amount": 1975000,
  "currency": "BDT",
  "exchange_rate": 1,
  "allocation_method": "by_value",
  "entry_date": "2026-07-10"
}
```

## 4. Import Receipt + Stock Posting

### Create receipt

```http
POST /api/v1/import-logistics/receipts
```

```json
{
  "shipment_id": 1,
  "warehouse_name": "Dhaka Warehouse",
  "received_date": "2026-07-10",
  "items": [
    {
      "shipment_item_id": 1,
      "product_id": 1,
      "received_qty": 5,
      "accepted_qty": 5,
      "bin_location": "A-01"
    }
  ]
}
```

### Approve receipt

```http
PATCH /api/v1/import-logistics/receipts/1/approve
```

### Post receipt to stock

```http
POST /api/v1/import-logistics/receipts/1/post-stock
```

This creates `stock_movements` rows and updates `products.stock_qty`.

## 5. Supplier Ledger

```http
GET /api/v1/import-logistics/supplier-ledger?supplier_id=1
POST /api/v1/import-logistics/supplier-ledger
```

```json
{
  "supplier_id": 1,
  "entry_date": "2026-07-10",
  "entry_type": "import_purchase_payable",
  "particulars": "PI value payable",
  "credit": 250000,
  "debit": 0,
  "currency": "BDT",
  "exchange_rate": 1
}
```

Rule:

- `credit` increases supplier payable.
- `debit` decreases supplier payable/payment.
- Enter exactly one: debit or credit.

## 6. Discrepancy / Claim

```http
GET /api/v1/import-logistics/discrepancies?status=open
POST /api/v1/import-logistics/discrepancies
PATCH /api/v1/import-logistics/discrepancies/1/resolve
```

```json
{
  "shipment_id": 1,
  "shipment_item_id": 1,
  "supplier_id": 1,
  "discrepancy_type": "short_qty",
  "quantity": 1,
  "estimated_value": 5000,
  "currency": "BDT",
  "note": "One board short received"
}
```