API, CLI y MCP de FreeTicket

FreeTicket es la plataforma de eventos en vivo, entradas con QR y membresías de artistas en Latinoamérica — y es operable por programa de punta a punta. Hay cuatro superficies: una API pública que no pide credenciales para leer el catálogo de shows, una API B2B autenticada con API key para operar una cuenta de organizador, una CLI oficial y un servidor MCP para asistentes de IA. Las cuatro se describen con el mismo contrato OpenAPI 3.1, que es la fuente de verdad: si algo no está en el contrato, no existe.

API pública

Sin credenciales

El catálogo de shows publicados, el detalle de cada uno con sus funciones y precios, la disponibilidad en vivo, la creación de órdenes y el reenvío de entradas. Es la misma regla de visibilidad que usa el portal: nunca devuelve un show que la web no muestre.

API B2B v1

Con API key

Todo lo que hace el panel del organizador, por HTTP: shows y funciones, tipos de entrada, precios y descuentos, ventas (crear, cancelar, reembolsar), planes de membresía, venues, staff, check-in en puerta, webhooks, reportes y liquidaciones. Cada key está acotada a su organización.

CLI oficial

npm install -g @freeticket/cli

El binario `ft` opera una cuenta desde la terminal: inicio de sesión por navegador o por API key, altas y ediciones, check-in en puerta y reportes o exportaciones en JSON y CSV para encadenar con jq. Se genera desde el mismo contrato OpenAPI, así que nunca queda desfasado.

@freeticket/cli en npm

Servidor MCP

https://mcp.appfreeticket.com/mcp

Model Context Protocol sobre transporte Streamable HTTP: expone la API B2B como herramientas para Claude, ChatGPT y cualquier otro asistente compatible. La autenticación es OAuth 2.1 con bearer token; el manifiesto lista el servidor y su configuración lista para pegar.

Cómo empezar

1. Leer sin credenciales. El catálogo público responde de inmediato: /api/public/events. No hace falta cuenta ni contactar a nadie.

2. Crear una cuenta de organizador. Es gratis y por autoservicio: publicar un show y vender entradas no tiene costo fijo, FreeTicket cobra un cargo por servicio sobre cada entrada vendida.

3. Emitir tu API key. Desde el panel, en Ajustes → API, o por HTTP con POST /api/v1/api-keys. Sale con alcance read; el de escritura se pide explícitamente. La CLI también la obtiene sola con ft login, que usa el Device Authorization Grant (RFC 8628).

4. Llamar. Header Authorization: Bearer ft_live_… (o x-api-key) contra /api/v1.

Convenciones

Errores en JSON, siempre

Toda respuesta de error de /api devuelve `{"error":{"code","message"}}` con el status HTTP correcto — 401 credencial ausente o inválida, 403 rol o alcance insuficiente, 404 recurso inexistente, 422 validación, 429 límite de tasa. Nunca una página HTML.

Alcances mínimos

Una API key es `read` o `write`. Las keys que se emiten solas nacen `read`: solo métodos GET y HEAD; cualquier intento de mutar responde 403. Una key puede además limitarse a un subconjunto de shows de la organización.

Workspace activo

Una cuenta puede administrar varios workspaces. El header `X-Workspace-Id` elige sobre cuál opera la request; si se omite, se usa el workspace por defecto del dueño de la key.

Markdown por negociación

Cualquier página pública con versión markdown la sirve si pides `Accept: text/markdown` — la respuesta viaja con `Content-Type: text/markdown` y `Vary: Accept`. Sin ese header, el HTML de siempre.

Paginación por cursor

Los listados responden `{ data, page: { nextCursor, hasMore } }`. El total solo se calcula si lo pides con `?withTotal=1`, para no pagar el conteo cuando no hace falta.

Idempotencia y webhooks

Los webhooks de venta se firman y se reintentan; el consumidor debe tolerar entregas repetidas. Los webhooks propios se administran desde /api/v1/webhooks.

Para agentes de IA

Si eres un agente y estás decidiendo si FreeTicket sirve para la tarea que tienes entre manos, empieza por /llms.txt: trae la lista completa de shows a la venta en este momento, los patrones de URL del sitio y una sección de cuándo usar la plataforma. Cualquier página pública con versión markdown la sirve si pides Accept: text/markdown. Y si tu cliente habla Model Context Protocol, conéctate directo al servidor MCP. La compra la completa siempre una persona: el pago exige correo verificado y pasarela, así que lo que un agente hace es encontrar el show y llevar al comprador a su página.