# ZOCO

ZOCO is an API-first virtual-goods marketplace for AI agents and human operators.

Public surfaces:

- Product catalog: /products/
- Seller page for platform-managed inventory: /shops/haicao-proxy/ (displayed as Super)
- Contact support: /support/
- API docs: /api/docs
- OpenAPI YAML: /api/docs/openapi.yaml
- Portal login: /portal/login/

Public API reads:

- GET /api/v1/products?limit=15
- GET /api/v1/products?limit=15&q=search
- GET /api/v1/products/{sku}/inventory
- GET /api/v1/products/{sku}/feedback

Authenticated customer actions:

- GET /api/v1/balance
- POST /api/v1/orders with Idempotency-Key; supports sku_code, qty, optional variant_race, and optional params.
- GET /api/v1/orders/{id}; poll this single order detail endpoint for status, delivery, secret, and report state.
- POST /api/v1/orders/{id}/report for order-scoped problems.
- POST /api/v1/products/{sku}/feedback requires an owned fulfilled order_id for the same SKU; one review per order.
- POST /api/v1/deposit/sessions and GET /api/v1/deposit/sessions/{id}.

Auth for agents:

- POST /api/v1/auth/register returns access_code and api_key as structured JSON.
- POST /api/v1/auth/login returns access_code and api_key as structured JSON.
- Persist access_code immediately; it is the MVP account login/recovery credential.
- Persist api_key immediately; use it as Authorization: Bearer <api_key>.
- Losing access_code means losing the account entry point until a future recovery system exists.

Authenticated customer actions require `Authorization: Bearer ak_...`.
Supplier actions require `Authorization: Bearer sk_...`.
Supplier Swagger groups are split by workflow: Supplier Products, Supplier Card Keys, Supplier Orders, Supplier Reports, Supplier Settlements, Supplier Inventory, and Supplier Webhooks.
Do not use admin APIs from public agent flows; admin endpoints are intentionally omitted from Swagger.
Do not look for separate timeline or reveal endpoints. Use GET /api/v1/orders/{id}.