# پیکسول | پرداخت ایرانی، تحویل آنی — llms-full

> پیکسول؛ خرید گیفت‌کارت، سی‌دی‌کی، شارژ استیم و اشتراک دیجیتال با پرداخت بانکی و تحویل قابل پیگیری. پرداخت ایرانی. تحویل آنی.

Site: https://pixevel.com
Map: https://pixevel.com/llms.txt
Catalog links live in llms.txt only (not duplicated here).

---

# 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.

---

# Authentication

## Customer identity (humans & user-agents acting as shoppers)

Pixevel customers authenticate with **phone number + OTP** via the **auth service** (`services/auth`), not via shop `/api/auth/*` (that surface does not exist as the identity system).

- UI/entry: public `/auth/` (auth service) and storefront login flows that redirect there.
- Machine contract: [`/openapi/auth.yaml`](https://pixevel.com/openapi/auth.yaml) (JSON twin: [`/openapi/auth.json`](https://pixevel.com/openapi/auth.json)).
- Session: HTTP-only session cookie (e.g. `pixevel_session`) after successful OTP verify.
- nginx `auth_request` gates `/account` and `/admin`.
- **Anonymous** browse + basket allowed. **Checkout** requires login; after OTP, anonymous basket merges into the user basket.

### Typical flow

1. Request OTP for E.164 / normalized Iranian phone (auth service OTP request endpoint).
2. User receives SMS/call via **notifications** service (auth does not own SMS providers).
3. Verify OTP → session cookie set.
4. Call shop APIs that need the user with credentials included (cookie jar).

### Failure modes

- Invalid phone format → 4xx from auth.
- Rate limited OTP request/verify → 429-class / rate_limited (see rate-limits.md).
- Expired or wrong code → verify fails; request a new OTP.
- Missing session on `/account` → redirect or 401 depending on surface.

## Service-to-service (server only)

Edge microservices (payments, notifications, analytics, …) use **bearer tokens from server environment** (e.g. `PAYMENTS_AUTH_TOKEN`, notifications `AUTH_TOKEN`).

```bash
# Example shape only — never embed real tokens in docs or browsers
curl -sS -H "Authorization: Bearer $PAYMENTS_AUTH_TOKEN" \
  http://payments.internal/v1/...
```

- Tokens MUST stay on servers / CI secrets.
- Browser and public agent docs MUST NOT receive live service tokens.
- Shop server calls payments via `getPaymentsClient()`; browsers do not call bank gateways.

## What not to do

- Do **not** call shop `/api/auth/*` as the identity system.
- Do **not** send service bearer tokens from a browser.
- Do **not** scrape admin HTML for “auth”.

---

# Errors

## Shop JSON APIs

Most shop route handlers return a stable envelope:

### Success

```json
{ "ok": true, "data": { } }
```

### Failure

```json
{
  "ok": false,
  "error": {
    "code": "MACHINE_READABLE_CODE",
    "message": "Human-readable message (often Persian on storefront)"
  }
}
```

Helper: `apiError(code, message, status)` in the web app.

### Typical HTTP status

| Status | Meaning |
| --- | --- |
| 400 | Validation / bad input (`code` explains which) |
| 401 | Unauthenticated |
| 403 | Authenticated but not allowed (RBAC / ownership) |
| 404 | Missing resource |
| 409 | Conflict (stock, state) |
| 429 | Rate limited (when enforced) |
| 500 | Unexpected — do not retry blindly without backoff |

## Retry guidance

- **Safe to retry:** idempotent GET; network blips on read-only calls.
- **Retry with care:** POST that creates orders/payments — check idempotency keys / existing order before re-POST.
- **Do not retry as-is:** 400 validation, 403 forbidden, 404 missing.
- **Backoff:** on 429/503 use exponential backoff; honor `Retry-After` if present.

## Payments / notifications microservices

Use each service OpenAPI under `/openapi/*.yaml` (auth, payments, notifications, …) for error fields. Treat provider webhooks as server-to-server; clients watch shop order/payment status instead of bank callbacks.

---

# Rate limits

## Global shop API

There is **no single global rate limiter** on every shop `/api/*` route. Some routes use an in-memory fixed-window limiter (`rateLimit(key, max, windowMs)`) per Node process (resets on deploy; not cross-instance).

## Known limits (representative)

| Surface | Limit (approx) | Notes |
| --- | --- | --- |
| Auth OTP **request** (auth service) | per-IP `OTP_REQUEST_PER_MIN` (default **5**/min) + per-phone cooldown (~60s) | SMS/call abuse protection |
| Auth OTP **verify** | per-IP+phone `OTP_VERIFY_PER_MIN` | Brute-force protection |
| Shop account phone OTP request | **5**/min per IP+user | `/api/account/phone/request-otp` |
| Shop account phone verify | **10**/min per IP+user | `/api/account/phone/verify` |
| Keys resend | **3** / 5 min per user+order | |

Exact numbers can change with env/config — treat table as guidance; read 429 bodies/headers when present.

## Client behavior

1. On limit: stop bursting; wait window or `Retry-After` / `retryAfterMs` if exposed.
2. Do not rotate identities to bypass OTP limits.
3. Prefer one OTP request, then verify; avoid parallel request storms.