# Pixevel agent guide

> Public storefront + APIs for agents. Prefer markdown over HTML.

## Product

Pixevel is a general-purpose e-commerce platform (physical goods, digital keys/gift cards/licenses, services, subscriptions). Storefront is Persian/RTL-first. Public catalog is anonymous-browseable.

## Start here

1. Read [`/llms.txt`](https://pixevel.com/llms.txt) for the site map.
2. Read [`/auth.md`](https://pixevel.com/auth.md) before any checkout or account call.
3. Read [`/errors.md`](https://pixevel.com/errors.md) and [`/rate-limits.md`](https://pixevel.com/rate-limits.md).
4. Use OpenAPI under [`/openapi/`](https://pixevel.com/openapi/auth.yaml) for edge services (auth, payments, notifications, …).

## Markdown for public pages

Public HTML pages accept content negotiation:

```bash
curl -sS -H 'Accept: text/markdown' https://pixevel.com/terms
curl -sS -H 'Accept: text/markdown' https://pixevel.com/products/SOME-SLUG
```

Stable mirrors also exist for static info pages (e.g. [`/terms.md`](https://pixevel.com/terms.md)).

**Not** auto-MD: `/account/*`, `/admin/*`, `/api/*`, `/checkout*`, `/basket`, `/payment/*`, `/login`.

## Common tasks

### Browse catalog

- HTML or markdown: `GET /products`, `GET /products/{slug}`, category routes, `GET /blog`
- JSON listing APIs live under `/api/products` (shop JSON; see errors envelope).
- Disabled / out-of-stock products may appear in discovery but cannot be added to basket.

### Basket (anonymous OK)

- Users may add variants while anonymous.
- Checkout requires phone OTP login; basket merges into the user after login.
- Do not invent add-to-cart for disabled/OOS SKUs.

### Checkout / pay

1. Authenticate (see auth.md) — session cookie from auth service.
2. Place order via shop checkout APIs (authenticated).
3. Payments run through **payments microservice** (not bank APIs from the browser). Shop creates invoice via server; provider webhooks hit payments service.

### Agent bulk ingest

- [`/llms-full.txt`](https://pixevel.com/llms-full.txt) — agent docs concatenated (not full product dump).

## Safety

- Never put service `AUTH_TOKEN` / webhook secrets in client requests or logs you publish.
- Internal routes `/api/internal/*` are server-to-server only.
- VIP images and premium prices are not shown to anonymous markdown consumers.