CHI 开发者平台

v1.0.0 • OAS 3.0 • 预发布环境

快速入门

此 API 提供用于管理活动、门票、组织、支付和用户账户的端点。将 CHI 服务集成到您的应用中，在 CHI 生态系统之上构建。

Staging 环境

Base URL: https://api.chi.app

Pagination

GET /events?page=1&limit=20

{
  "data": [...],
  "total": 156,
  "page": 1,
  "lastPage": 8
}

身份认证

大多数端点需要 Bearer 令牌认证。请在 Authorization 请求头中包含 JWT 令牌：

Authentication

Authorization: Bearer <your-token>

# Example request
curl -X GET https://api.chi.app/events \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json"

Webhooks

通过API注册webhook端点，接收票据扫描、支付和签到的实时事件通知。

Webhook Payload

POST https://your-server.com/webhook

{
  "event": "ticket.scanned",
  "timestamp": "2025-06-15T14:30:00Z",
  "data": {
    "ticketId": "tkt_abc123",
    "eventId": "evt_xyz789",
    "visitorId": "vis_456def"
  }
}

SDK

使用我们的官方包，以您首选的语言集成CHI平台。

MCP服务器

即将推出

尚未推出 — CHI MCP 服务器仍在开发中。

REST API

OpenAPI 3.0

尚未发布 — API 访问目前仅限受邀用户。

React Storefront SDK

Beta · @chi-ecosystem/storefront-react

Build a full event storefront — live ticket pricing, cart and checkout — without touching REST endpoints, auth, retries, rate limits or data normalization. CHI owns the commerce behavior; you own the visual experience. Ships as headless React hooks plus optional components with zero CSS, so your design system stays yours. Lineup hooks arrive together with the public lineup API.

Install (GitHub Packages registry required for the @chi-ecosystem scope)

npm install @chi-ecosystem/storefront-react @tanstack/react-query

# .npmrc - GitHub Packages auth for the @chi-ecosystem scope
@chi-ecosystem:registry=https://npm.pkg.github.com

Lineup + live tickets in ~20 lines

import {
  ChiStorefrontProvider,
  useTicketDefinitions,
  useQuote,
  formatMoney,
  money,
} from '@chi-ecosystem/storefront-react';

// Once, at the root - CHI handles auth, caching, retries,
// outage healing and quote rate-limit budgets from here on.
<ChiStorefrontProvider eventSlug="your-festival" baseUrl="production">
  <App />
</ChiStorefrontProvider>;

function Tickets() {
  const { definitions } = useTicketDefinitions();   // live prices + stock
  const [lines, setLines] = useState([]);           // your cart UI state
  const { quote } = useQuote({ lines });            // debounced + deduped

  return (
    <div className="my-tickets">                    {/* your CSS, your rules */}
      {definitions.map((d) => (
        <button key={d.id} onClick={() => addLine(setLines, d)}>
          {d.name} - {formatMoney(money(d.priceMinor, d.currency))}
        </button>
      ))}
      <Total>{formatMoney(money(quote?.pricing.totalMinor ?? 0, quote?.pricing.currency ?? 'USD'))}</Total>
    </div>
  );
}

错误处理

错误返回包含 statusCode、message 和 error 字段的JSON对象。处理 401（令牌过期）、403（禁止）和 429（速率限制）。

Error Response

{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Token expired"
}

状态码	含义	操作
400	错误请求	检查请求体和参数
401	未授权	令牌过期 — 刷新并重试
403	禁止访问	对此资源权限不足
429	速率限制	使用指数退避延迟
500	服务器错误	稍后重试或联系支持

速率限制

每个API密钥每分钟100个请求。对429响应使用指数退避。

等级	速率	突发
标准	100 req/min	20 req/s
企业版	1000 req/min	100 req/s

LLM与代理集成

标准上下文文件

我们提供符合 llms.txt 规范的标准化上下文文件。将您的AI代理指向这些URL，即可立即加载完整的CHI生态系统上下文。

代理系统提示词 (agent.md)

要让您的编码助手（Cursor、Windsurf、Copilot）全面了解CHI平台，请在项目根目录创建 agent.md 文件并粘贴以下内容块。这确保AI遵循我们的设计令牌和API模式。

agent.md

# CHI Ecosystem API Context for AI Agents

You are integrating with the CHI Ecosystem (EventCHI) REST API.
Base URL: https://api.chi.app (production) | https://api.staging.chi.app (staging)
Auth: Bearer token via Authorization header.

## Resources
- Full Context: https://chi.app/llms-full.txt
- Minimal Context: https://chi.app/llms-minimal.txt
- 开发者概览: https://chi.app/zh/developers
- 聚合器上下文: https://chi.app/llms-aggregators.txt
- 尚未发布 — API 访问目前仅限受邀用户。
- MCP服务器: 尚未推出 — CHI MCP 服务器仍在开发中。

## API Guidelines
1. **Authentication**: All requests require a Bearer token. Obtain tokens via POST /auth/login.
2. **REST Patterns**: Use strict RESTful conventions — resource-based URLs, proper HTTP methods, JSON request/response bodies.
3. **Pagination**: List endpoints support `?page=` and `?limit=` query params. Responses include `total`, `page`, and `lastPage`.
4. **Error Handling**: Errors return `{ statusCode, message, error }`. Handle 401 (token expired), 403 (forbidden), 429 (rate limited).
5. **Webhooks**: Register webhook endpoints via the API to receive real-time event notifications (ticket scans, payments, check-ins).
6. **Rate Limits**: 100 req/min per API key. Use exponential backoff on 429 responses.

## Key Resources
- **Events**: /events — create, manage, and query events.
- **Tickets**: /tickets — issue, validate, and scan tickets.
- **Payments**: /payments — process and track transactions.
- **Visitors**: /visitors — attendee profiles and wallet data.
- **Coupons**: /coupons — create and redeem discount codes.
- **Organizations**: /organizations — manage org settings and team members.

## Key Terminology
- **Visitor App**: The mobile wallet for attendees.
- **Crew App**: POS and access control for staff.
- **Backstage**: The organizer dashboard.

活动聚合器

获取 CHI 活动以在您的平台上展示。我们提供多种 Feed 格式和专用的 AI 上下文文件供聚合器使用。

JSON Feed

GET /feeds/events.json

适用于现代应用和 API 的结构化 JSON

https://api.chi.app/feeds/events.json

Example

fetch('https://api.chi.app/feeds/events.json')
  .then(res => res.json())
  .then(data => {
    console.log(data.items);
  });

// Organization-scoped
fetch('https://api.chi.app/feeds/organizations/{orgId}/events.json')

// Single event JSON-LD
fetch('https://api.chi.app/feeds/events/{eventId}.json')

聚合器 LLMs.txt

/llms-aggregators.txt

专用上下文文件，帮助 AI 驱动的聚合器理解 CHI 活动数据结构

聚合器合作伙伴计划

从您的应用或平台带来的每笔门票销售中赚取佣金。联系我们加入聚合器合作伙伴计划，获得销售奖励。

联系我们

API 访问 — 仅限邀请

我们的 API 目前仅通过邀请提供。我们正在努力在不久的将来向所有人开放访问。