WooNooW/.agent/plans/shipping-label.md

Shipping Label Plan

Overview

Standardized waybill data structure for shipping label generation.

Problem

• Different shipping carrier addons (JNE, JNT, SiCepat, etc.) store data differently
• No standard structure for label generation
• Label button needs waybill data to function

Proposed Solution

1. Standardized Meta Key

Order meta: _shipping_waybill

2. Data Structure

{
  "tracking_number": "JNE123456789",
  "carrier": "jne",
  "carrier_name": "JNE Express",
  "service": "REG",
  "estimated_days": 3,
  "sender": {
    "name": "Store Name",
    "address": "Full address line 1",
    "city": "Jakarta",
    "postcode": "12345",
    "phone": "08123456789"
  },
  "recipient": {
    "name": "Customer Name", 
    "address": "Full address line 1",
    "city": "Bandung",
    "postcode": "40123",
    "phone": "08987654321"
  },
  "package": {
    "weight": "1.5",
    "weight_unit": "kg",
    "dimensions": "20x15x10",
    "dimensions_unit": "cm"
  },
  "label_url": null,
  "barcode": "JNE123456789",
  "barcode_type": "128",
  "created_at": "2026-01-05T12:00:00+07:00"
}

3. Addon Integration Contract

Shipping addons MUST:

1. Call update_post_meta($order_id, '_shipping_waybill', $waybill_data)
2. Use the standard structure above
3. Set label_url if carrier provides downloadable PDF
4. Set barcode for local label generation

4. Label Button Behavior

1. Check if _shipping_waybill meta exists on order
2. If label_url → open carrier's PDF
3. Otherwise → generate printable label from meta data

5. UI Behavior

• Label button hidden if order is virtual-only
• Label button shows "Generate Label" if no waybill yet
• Label button shows "Print Label" if waybill exists

API Endpoint (Future)

POST /woonoow/v1/orders/{id}/generate-waybill
- Calls shipping carrier API
- Stores waybill in standardized format
- Returns waybill data

GET /woonoow/v1/orders/{id}/waybill
- Returns current waybill data

Implementation Priority

1. Define standard structure (this document)
2. Implement Label UI conditional logic
3. Create waybill API endpoint
4. Document for addon developers