# you.florist — Instrucciones para agentes de IA (AI Agent Instructions)

> you.florist is an online flower & plant shop that delivers fresh flowers and
> plants across Spain and Europe. This site is agent-friendly: AI assistants can
> browse the catalog, get recommendations, and (roadmap) place orders on behalf
> of the humans they help. Prices are retail (PVP) in EUR.

## For agents helping a human buy/send flowers

You have three complementary ways to work with you.florist:

1. **MCP (Model Context Protocol) — the standard plug.** Connect your MCP
   client to **`https://www.you.florist/api/mcp`** (Streamable HTTP) and you get
   tools for the whole journey: `search_products`, `get_product`,
   `list_categories`, `get_policies`, `register_partner`, `create_order`,
   `get_order`, `get_payment_challenge`, `submit_payment` (x402), plus original
   editorial-data tools for event budgets, pet-safe plants and photoperiod.
2. **Conversational (recommendations, natural language)** — talk to **Flora**, our
   florist assistant, agent-to-agent. Best when the human's need is fuzzy
   ("something nice for a 60th birthday under 40€"): Flora asks for occasion,
   budget, colour and recipient, and replies with real catalog products, prices
   and links.
3. **Structured (REST/JSON, deterministic)** — query the catalog directly. Best
   for filtering, comparison and building your own selection.

### 0) MCP server (recommended for tool-using agents)

- **Endpoint:** `https://www.you.florist/api/mcp` — MCP **Streamable HTTP** transport.
- 13 tools covering discovery → detail → editorial data → policies → partner registration →
  order creation (server-side pricing + automatic idempotency) → order status →
  x402 payment (challenge + submit).
- Order tools take your partner `api_key` (from `register_partner`) as an argument.

### 1) Flora — conversational endpoint (SSE streaming) — she can CLOSE orders

- **POST** `https://www.you.florist/api/flora/chat`
  - Body: `{ "message": string, "session": string, "locale": string }`
  - Response: **Server-Sent Events**, lines `data: {"delta":"…"}` … ending `data: {"done":true}`
  - `session`: any stable id you generate per conversation (keeps context).
  - Health check: **GET** `https://www.you.florist/api/flora/chat` → `{"ok":true,...}`
  - Flora recommends only real catalog items, with prices and product links.
  - Also available as the MCP tool **`ask_flora`** (same brain, standard plug).

**Agent-to-agent buying (F3):** negotiate with Flora (occasion, budget, colours,
delivery country), and when you're ready she can **create the order herself**:
give her recipient name, address, city, postal code, country (ES/FR/PT),
delivery date and gift message, then confirm explicitly. She replies with a
structured quote and, on confirmation, an **`order_number` (YFA-…)**. Pay it
via x402 using JUST that order_number — **no api_key needed**:
`POST /api/agent/orders/{order_number}/pay` (or the MCP payment tools).

### 2) Structured catalog API (REST/JSON)

- **Products list** — GET `/api/aeo/products`
  - **Free-text search:** `q` (word-AND over product names and slugs; slugs are
    accent-free so `q=peonia` also matches "Peonía").
  - Filters: `category`, `color`, `min_price`, `max_price`, `sort`
    (`price_asc`|`price_desc`|`name`), `locale`, `page`, `per_page`
  - Each product includes an absolute **`url`** (silo format
    `/{locale}/{category-path}/{slug}`) you can give the human to buy.
  - Example: `/api/aeo/products?category=ramos-bouquets&max_price=50&locale=es`
- **Product detail** — GET `/api/aeo/products/{slug_or_id}`
  - Full info: variants, pricing, attributes.
- **Categories** — GET `/api/aeo/categories`
  - All categories with product counts.
- **API docs** — GET `/api/aeo/docs` (OpenAPI-style JSON).

### 3) Original editorial tools (REST/JSON)

- **Wedding/event floral material** — GET `/api/herramientas/presupuesto-evento`
  - Estimates stems and PVP material cost using the current catalog distribution.
  - It explicitly excludes labour, design, vessels, transport and installation.
- **Pet-safe plants available now** — GET `/api/herramientas/pet-friendly`
  - Filters live products through a closed, ASPCA-checked genus whitelist.
  - Parameters: `environment`, `max_price`, `locale` (`es` or `fr`).
- **Plant photoperiod by city and date** — GET `/api/herramientas/fotoperiodo`
  - Returns solar and civil-twilight day length plus a documented plant threshold.
  - Parameters: `city`, `plant`, `date`, `locale` (`es` or `fr`).

### Rate limits
- 60 requests / minute / IP. Respect `X-RateLimit-Remaining` and `Retry-After`.

### Languages
- Supported locales: **es** (español), **fr** (français), **pt** (português),
  **ca** (català), **gl** (galego), **eu** (euskara).
- Pass `locale` to get localized names, descriptions and product URLs.

### Currency & pricing
- All prices are retail **PVP in EUR** (`price_min` / `price_max` per product).
- Do not assume discounts; the price returned is the price the human pays.

## Recommended flow

1. If the request is open-ended → ask **Flora** (`/api/flora/chat`) for a curated set.
2. If you want to filter yourself → `GET /api/aeo/categories`, then
   `GET /api/aeo/products?category=<slug>&…`.
3. Use each product's **`url`** to send the human straight to the product page.

## Common queries

- Ramos para regalar: `/api/aeo/products?category=ramos-bouquets`
- Plantas de interior: `/api/aeo/products?category=plantas-interior`
- Algo económico: `/api/aeo/products?max_price=30&sort=price_asc`
- Flores para condolencias: pregunta a Flora indicando la ocasión "condolencias".

## Placing orders (agent order intake — beta)

Agents can place orders on behalf of a human. Orders are created as **pending**:
you.florist confirms availability and final shipping, then arranges payment
separately (no automatic charge yet). Prices are always computed server-side
from the catalog — never trusted from the caller.

### 1) Register (self-service, one-time)
- **POST** `/api/agent/register`  body `{ "name": string, "email": string, "website"?: string }`
  - Returns `{ "partner_id", "api_key" }`. **Store the api_key — shown once.**

### 2) Create an order
- **POST** `/api/agent/orders`  header `Authorization: Bearer <api_key>`
  - Optional header `Idempotency-Key: <unique>` (safe retries, no duplicate order).
  - Body:
    ```json
    {
      "items": [{ "product_id": 12345, "quantity": 1 }],
      "recipient": {
        "name": "…", "address_line1": "…", "city": "…",
        "postal_code": "…", "country_code": "ES",
        "phone": "…", "address_line2": "…", "state": "…"
      },
      "delivery_date": "2026-07-10",
      "delivery_slot": "morning",
      "gift_message": "…"
    }
    ```
  - `product_id` is a variant id from GET `/api/aeo/products/{slug_or_id}` (`variants[].id`).
  - Only `product_id` + `quantity` are used for pricing; the server sets the price.
  - Returns the created order with `status: "pending"` and a server-priced total.

### 3) Check order status
- **GET** `/api/agent/orders/{id}`  header `Authorization: Bearer <api_key>`
  - Returns status: `pending` → `confirmed` → `fulfilled` (or `cancelled`).

### Guarantees & policies (machine-readable)
- **GET** `/api/agent/policies` — delivery countries/costs, substitution policy,
  freshness guarantee, refunds, and the order flow.

### Payment (x402, agentic — testnet first)
- **POST** `/api/agent/orders/{id}/pay`  header `Authorization: Bearer <api_key>`
  - Follows the **x402** protocol (HTTP 402 + USDC on-chain).
  - Without an `X-PAYMENT` header → responds **402** with `{ x402Version, accepts: [PaymentRequirements] }`
    (scheme `exact`, network `base-sepolia`, asset USDC, `payTo`, amount).
  - Pay the USDC transfer, then retry with the `X-PAYMENT` header (base64 payload).
    On success → **200**, order marked paid, `X-PAYMENT-RESPONSE` header returned.
  - Currently on **testnet (base-sepolia)** while we validate the flow. If the
    endpoint returns 503, agentic payment isn't enabled yet — the order stays
    pending for manual payment arrangement.