Plataforma de desarrolladores CHI

v1.0.0 • OAS 3.0 • Staging

Primeros pasos

Esta API proporciona endpoints para gestionar eventos, entradas, organizaciones, pagos y cuentas de usuario. Integra los servicios de CHI en tus apps y construye sobre el ecosistema CHI.

Entorno de staging

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

Pagination

GET /events?page=1&limit=20

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

Autenticacion

La mayoria de los endpoints requieren autenticacion Bearer token. Incluye el token JWT en el header de autorizacion:

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

Registre endpoints de webhook a través de la API para recibir notificaciones en tiempo real de escaneos de tickets, pagos y check-ins.

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"
  }
}

SDKs

Use nuestros paquetes oficiales para integrar la plataforma CHI en su lenguaje preferido.

Servidor MCP

Próximamente

Aún no disponible: el servidor MCP de CHI todavía está en desarrollo.

REST API

OpenAPI 3.0

Aún no publicado: el acceso a la API es solo por invitación por ahora.

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>
  );
}

Errores

Los errores devuelven un objeto JSON con campos statusCode, message y error. Maneje 401 (token expirado), 403 (prohibido) y 429 (límite de tasa).

Error Response

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

Código	Significado	Acción
400	Solicitud Incorrecta	Verifique el cuerpo de la solicitud y los parámetros
401	No Autorizado	Token expirado — actualice y reintente
403	Prohibido	Permisos insuficientes para este recurso
429	Límite de Tasa	Retroceda con retraso exponencial
500	Error del Servidor	Reintente más tarde o contacte soporte

Limites de solicitudes

100 solicitudes por minuto por clave de API. Use backoff exponencial en respuestas 429.

Nivel	Tasa	Ráfaga
Estándar	100 req/min	20 req/s
Empresarial	1000 req/min	100 req/s

Integración de LLM y Agentes

Archivos de Contexto Estándar

Proporcionamos archivos de contexto estandarizados conforme a la especificación llms.txt. Apunte sus agentes de IA a estas URLs para cargar instantáneamente el contexto completo del ecosistema CHI.

Habilidades del agente

Prompt del Sistema del Agente (agent.md)

Para dar a su asistente de codificación (Cursor, Windsurf, Copilot) conocimiento completo de la plataforma CHI, cree un archivo agent.md en la raíz de su proyecto y pegue el siguiente bloque. Esto asegura que la IA siga nuestros tokens de diseño y patrones de 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
- Resumen para desarrolladores: https://chi.app/es/developers
- Contexto para agregadores: https://chi.app/llms-aggregators.txt
- Aún no publicado: el acceso a la API es solo por invitación por ahora.
- Servidor MCP: Aún no disponible: el servidor MCP de CHI todavía está en desarrollo.

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

Agregadores de Eventos

Obtén eventos de CHI para mostrarlos en tu plataforma. Proporcionamos múltiples formatos de feed y un archivo de contexto IA dedicado para agregadores.

Feed JSON

GET /feeds/events.json

JSON estructurado para aplicaciones y APIs modernas

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 para Agregadores

/llms-aggregators.txt

Archivo de contexto dedicado para agregadores con IA para comprender las estructuras de datos de eventos CHI

Programa de Socios Agregadores

Gana comisiones por cada venta de entradas que provenga de tu app o plataforma. Contáctanos para unirte a nuestro programa de socios agregadores y ser recompensado por impulsar ventas.

Contáctanos

Acceso API — Solo por invitación

Nuestra API está disponible actualmente solo por invitación. Estamos trabajando para abrir el acceso a todos en un futuro próximo.