# StudEvent API

> StudEvent est une plateforme de billetterie pour BDE/associations étudiantes. Cette API publique permet d'intégrer la billetterie sur le site du BDE : afficher les events, vendre des places via Stripe, valider les billets à l'entrée, recevoir des webhooks temps réel.

L'API est REST, JSON, en HTTPS, avec auth Bearer (clé `sk_live_…` créée depuis le dashboard).
Base URL : `https://studevent-app.com/api/v1`. Toutes les routes nécessitent `Authorization: Bearer <key>`.

## Documentation

- [Documentation portail (HTML)](https://studevent-app.com/docs) : référence complète avec exemples curl/JS/Python.
- [Documentation full markdown](https://studevent-app.com/llms-full.txt) : doc complète aplatie, optimisée pour ingestion LLM.
- [Spec OpenAPI 3.1 (JSON)](https://studevent-app.com/api/v1/openapi.json) : à importer dans Postman, Insomnia, ou pour code-gen.

## Endpoints

- `GET /v1/events` — lister les événements publiés (scope: events:read)
- `GET /v1/events/{id_or_slug}` — détail event + ticket_types (scope: events:read)
- `POST /v1/checkout/sessions` — créer une commande pending et obtenir l'URL Stripe (scope: checkout:write)
- `GET /v1/orders/{ref}` — récupérer une commande par display_ref ou UUID (scope: orders:read)
- `GET /v1/tickets/{ref}` — récupérer un billet (scope: tickets:read)
- `POST /v1/tickets/{ref}/scan` — valider un billet en server-to-server (scope: tickets:write)
- `GET /v1/webhook_endpoints` — lister les endpoints webhooks (scope: webhooks:manage)
- `POST /v1/webhook_endpoints` — créer un endpoint (scope: webhooks:manage)
- `DELETE /v1/webhook_endpoints/{id}` — supprimer un endpoint (scope: webhooks:manage)

## Webhooks

Événements possibles : `order.paid`, `order.refunded`, `ticket.created`, `ticket.scanned`, `refund.created`.
Signature : header `studevent-signature: t=<unix>,v1=<hex>` (HMAC-SHA256 sur `${t}.${rawBody}`).

## MCP server

Disponible pour intégration dans Claude Desktop, Cursor, Windsurf : `npx -y @studevent/mcp`.
Variable d'env : `STUDEVENT_API_KEY=sk_live_…`. Voir https://studevent-app.com/docs#ai-tools.

## Modèles de réponse

Listes : `{ object: "list", data: [...], has_more, next_cursor }`.
Erreurs : `{ error: { type: "invalid_api_key" | "insufficient_scope" | ..., message: "..." } }`.