# FlowerAdvisor China - Agent Instructions

> This file describes how AI agents and LLMs should interact with FlowerAdvisor China.
> It follows the emerging `agents.md` convention for agentic web interoperability.
> Base URL: https://www.floweradvisor.cn

## About

FlowerAdvisor China is an online flower and gift delivery platform serving China.
Customers can browse arrangements, place orders, and track deliveries entirely online.

- **Website**: https://www.floweradvisor.cn
- **Primary country code**: CN
- **Currency**: CNY (Chinese Yuan)
- **Delivery areas**: Shanghai, Beijing, Guangzhou, Shenzhen, Chengdu, and more

---

## Key Capabilities for Agents

| Capability | How to access |
|---|---|
| Browse products | `GET /collections/{category_slug}` |
| Fetch product feed | `GET /product_feeds/www-floweradvisor-cn-CN-CNY/products` |
| Search products | `GET /search/{keyword}` or `GET /api/getsearchsuggestion?keyword={q}` |
| View product detail | `GET /product/{product_slug}` |
| Same-day delivery | `GET /sameday-china` |
| Add to cart | `POST /cart` |
| View cart | `GET /cart` |
| Checkout | `GET /checkout` then `POST /checkout` |
| Track order | `GET /tracking-order/{order_id}` or `GET /api/trackorder?order_id={id}` |
| Sign in | `POST /api/signin` |
| Register | `POST /api/account/register` |
| Browse promotions | `GET /promotion` or `GET /promotion/{slug}` |
| Contact support | `GET /contact-us` or `POST /api/contact` |
| Read blog | `GET /blog` or `GET /blog/{slug}` |
| Get delivery cities | `POST /api/getcitylist` |
| Get product price | `POST /api/getprice` or `GET /api/getproductprice` |

---

## API Reference

Base URL: `https://www.floweradvisor.cn`

All API endpoints are under the `/api` prefix and return JSON.

### Product Search
```
GET /api/getsearchsuggestion?keyword={keyword}
```
Returns a list of matching product suggestions.

### Browse Collections
```
GET /collections/{category_slug}
POST /api/collections/{category_slug}
```
Returns paginated product listings. Supports filters:
- `/collections/{category_slug}/delivery_city_{city}`
- `/collections/{category_slug}/color_{color}`
- `/collections/{category_slug}/size_{size}`
- `/collections/{category_slug}/{type}_day`

### Get Cities
```
POST /api/getcitylist
```
Returns available delivery cities.

### Get Product Price
```
POST /api/getprice
GET  /api/getproductprice
```
Returns current price and variant data for a product.

### Track Order
```
GET /api/trackorder?order_id={id}
```
Returns current order status and delivery information.

### Contact / Enquiry
```
POST /api/contact
POST /api/corporate
POST /api/enquiry/order
```

### Authentication
```
POST /api/signin           - Login with email/password
POST /api/account/register - Create new account
POST /api/signup           - Check email availability
```
Sessions are cookie-based. Include `XSRF-TOKEN` header for POST requests.

### System Status
```
GET /api/system/status
```
Returns current system health status.

---

## Product Data Mapping

### Product Object Schema

When fetching a product (via `GET /product/{slug}` or `POST /api/getprice`), the response includes the following fields:

| Field | Type | Description |
|---|---|---|
| `code` | string | Unique product code (e.g. `FA1234`) |
| `title` | string | Product display name |
| `description` | string | Short description / subtitle |
| `full_description` | string | Full HTML product description |
| `title_id` | string | Product title in Bahasa Indonesia |
| `description_id` | string | Short description in Bahasa Indonesia |
| `full_description_id` | string | Full description in Bahasa Indonesia |
| `imageurl` | string | Main product image URL |
| `price` | number | Current selling price (numeric) |
| `price_text` | string | Formatted price string (e.g. `"CNY 99.00"`) |
| `price_before` | number | Original price before discount |
| `price_before_text` | string | Formatted original price string |
| `price_discount` | number | Discount amount |
| `price_increased` | number | Surcharge applied for selected delivery date |
| `price_increased_percentage` | number | Surcharge as percentage |
| `currency` | string | ISO currency code (e.g. `CNY`) |
| `category` | string | Category name |
| `categoryid` | integer | Category ID |
| `categoryurl` | string | Category URL slug |
| `parent_category` | string | Parent category name (e.g. `Flowers`, `Gifts`) |
| `country_code` | string | ISO country code for delivery (e.g. `MY`, `SG`, `ID`) |
| `important_note` | string | Delivery or product important notes |
| `detail` | string | Additional product details |
| `product_care_id` | integer | Product care instruction ID |
| `addon_category` | string | Add-on category code (for extras like vases, chocolates) |
| `id` | integer | Internal product database ID |
| `revision` | integer | Image revision number, used for cache-busting image URLs |

---

### Price Endpoint Response

```
POST /api/getprice
GET  /api/getproductprice
```

**Request parameters:**

| Parameter | Type | Description |
|---|---|---|
| `productid` | string | Product code or ID |
| `country_code` | string | Destination country (e.g. `MY`, `SG`) |
| `currency` | string | Currency code (e.g. `CNY`) |
| `deliverycity` | string | Delivery city alias |
| `delivery_date` | string | Date `YYYY-MM-DD`; triggers date-based surcharge |

**Response fields (`productprice` object):**

```json
{
  "productprice": {
    "code": "FA1234",
    "title": "Radiant Roses Bouquet",
    "price": 99.00,
    "price_text": "CNY 99.00",
    "price_before": 129.00,
    "price_before_text": "CNY 129.00",
    "price_discount": 30.00,
    "price_increased": 10.00,
    "price_increased_percentage": 10,
    "currency": "CNY",
    "url": "/malaysia/flowers/fresh-flowers/radiant-roses-fa1234"
  }
}
```

---

### Real-Time Price Endpoint

```
POST /api/get-real-price-product
```

**Request parameters:**

| Parameter | Type | Description |
|---|---|---|
| `productcode` | string | Product code |
| `country_code` | string | Destination country |
| `currency` | string | Currency code |
| `delivery_date` | string | Date `YYYY-MM-DD` (optional) |

**Response:**

```json
{
  "price": 99.00,
  "price_before": 129.00,
  "price_before_text": "CNY 129.00",
  "price_discount": 30.00,
  "price_text": "CNY 99.00",
  "price_increased": 10.00,
  "price_increased_percentage": 10,
  "currency": "CNY",
  "product_code": "FA1234"
}
```

---

### Product Catalog Endpoint

```
GET /api/products
```

Returns a flat array of all active products for the current site. Useful for indexing or catalog browsing.

**Response (array of objects):**

```json
[
  {
    "title": "Radiant Roses Bouquet",
    "price": "CNY 99.00",
    "image_url": "https://cdn.floweradvisor.com/assets/product/fa1234.jpg",
    "url": "https://www.floweradvisor.cn/malaysia/flowers/fresh-flowers/radiant-roses-fa1234"
  }
]
```

---

### Product Feed

```
GET /product_feeds/www-floweradvisor-cn-CN-CNY/products
```

Returns structured catalog data for AI shopping and product discovery integrations. This follows the OpenAI Commerce API product feed path format. Prices use the current domain's default currency (`CNY` for this host), and product URLs stay on the current FlowerAdvisor domain.

**Response:**

```json
{
  "merchant": {
    "name": "FlowerAdvisor",
    "domain": "https://www.floweradvisor.cn",
    "country_code": "CN",
    "currency": "CNY"
  },
  "feed_id": "www-floweradvisor-cn-CN-CNY",
  "schema": "floweradvisor.ai_commerce.product_feed.v1",
  "generated_at": "2026-06-11T00:00:00+00:00",
  "products": [
    {
      "id": "FA1234",
      "title": "Radiant Roses Bouquet",
      "description": "Radiant Roses Bouquet",
      "url": "https://www.floweradvisor.cn/malaysia/flowers/fresh-flowers/radiant-roses-fa1234",
      "canonical_url": "https://www.floweradvisor.cn/malaysia/flowers/fresh-flowers/radiant-roses-fa1234",
      "image_url": "https://cdn.floweradvisor.com/assets/product/fa1234.jpg",
      "availability": "in_stock",
      "price": {
        "amount": 9900,
        "display_amount": "CNY 99.00",
        "currency": "CNY"
      }
    }
  ]
}
```

Use `price.amount` as the minor-unit integer amount for commerce ingestion, and `price.display_amount` for human-readable output.

---

### Product Image URLs

Images follow this pattern:

```
Original:   /assets/product/{slug}
Thumbnail:  /assets/product/t/{slug}
Mobile:     /assets/product/m/{slug}
Large:      /assets/product/l/{slug}
```

Where `{slug}` is derived from the product `code` and `description`.

---

### Product URL Scheme

Product URLs follow this pattern:

```
/{country_alias}/{parent_category_slug}/{category_slug}/{description_slug}-{product_code}
```

Example:
```
/malaysia/flowers/fresh-flowers/radiant-roses-bouquet-fa1234
```

---

### Product Reviews Schema

```
GET /product/{slug}   - reviews embedded in page data
```

Each review object contains:

| Field | Type | Description |
|---|---|---|
| `customer_name` | string | Reviewer name (or anonymous) |
| `rating` | integer | Star rating 1-5 |
| `review` | string | Review text |
| `createdon` | string | Review date |
| `origin_country_code` | string | Sender country |
| `country_code` | string | Recipient country |
| `imageurl` | string | Reviewer uploaded image (if any) |

---

### Add-On Products

Some products support add-ons (e.g., vases, chocolates, balloons). Fetch them with:

```
GET /api/getprice?productid={code}&addon_category={addon_category_code}
```

Add-ons are returned in the `addon` array within the product detail response. Each add-on has:
`code`, `title`, `price`, `imageurl`.

---

## Product Categories

Common category slugs include:
- `fresh-flowers` - fresh bouquets and arrangements
- `roses` - rose arrangements
- `birthday-flowers` - birthday gifts
- `anniversary-flowers` - anniversary arrangements
- `condolence-flowers` - condolence wreaths
- `wedding-flowers` - wedding bouquets
- `corporate-flowers` - corporate gifts
- `fruit-baskets` - hampers and baskets
- `plants` - potted plants

Browse all categories at `/category-list`.

---

## Policies

- **FAQ**: `/faq`
- **How to order**: `/how-to-order`
- **Terms & Conditions**: `/terms-and-conditions`
- **Privacy Policy**: `/privacy-policy`
- **Refund Policy**: `/refund-policy`

---

## Notes for Agents

- Prices are in CNY (Chinese Yuan).
- Same-day delivery is available for orders placed before the cut-off time. Check `https://www.floweradvisor.cn/sameday-china` for current availability.
- Authentication is required to place orders. Use `/api/signin` before attempting checkout.
- For bulk or corporate orders, use `POST /api/corporate` or visit `/corporate`.
- Stay on the current host when generating links or instructions; do not switch users to another FlowerAdvisor domain unless the current site redirects there.


---

*Last updated: 2026-06-11*