Migration /api → /v1
Correspondance entre l’API dashboard actuelle (Clerk Bearer) et l’API premium cible (clés Pro, namespace /v1).
Aujourd’hui, le dashboard consomme /api/* avec Clerk Bearer. L’API Pro expose /api/v1/* avec x-njanggo-api-key — partiellement déployée (calendrier, guests, export, check-ins). Gestion des clés : /api/calendars/:slug/api-keys.
Les intégrations Plus (webhooks par événement, widget iframe) ne nécessitent pas de clé API — secret webhook ou aucune auth.
Légende statuts
LiveDivergentPreviewPlanned
Authentification
| Contexte | Header | Usage |
|---|---|---|
| Dashboard / Plus | Authorization: Bearer <clerk_jwt> | Config webhooks par événement, widget, clés API (gestion) |
| API Pro (live) | x-njanggo-api-key: nj_live_… | /api/v1/… — calendrier, guests, export, check-ins |
| API Pro (cible) | x-njanggo-api-key: nj_live_… | CRUD events, billing, logs webhooks |
| Webhooks entrants (actuel) | X-Njanggo-Webhook-Signature: t=…,v1=… | HMAC de "{timestamp}.{body}" |
| Webhooks entrants (cible) | X-Njanggo-Signature: sha256=… | HMAC du corps brut |
Table de correspondance
| Statut | Méthode | Actuel (/api) | Cible | Auth cible | Scopes |
|---|---|---|---|---|---|
| divergent | GET | /api/events/:eventId/webhooks | /api/calendars/:slug/webhooks | Bearer (dashboard) | — |
| divergent | POST | /api/events/:eventId/webhooks | /api/calendars/:slug/webhooks | Bearer (dashboard) | — |
| divergent | POST | /api/events/:eventId/webhooks/:id/test | /api/calendars/:slug/webhooks/:id/test | Bearer (dashboard) | — |
| divergent | GET | /api/calendars/:slug/events | /api/calendars/:slug/embed.json | none | — |
| live | GET | /api/v1/calendars/:slug | /api/v1/calendars/:slug | x-njanggo-api-key | events:read |
| live | GET | /api/calendars/:slug/api-keys | /api/v1/api-keys | Bearer (dashboard) | — |
| live | POST | /api/calendars/:slug/api-keys | /api/v1/api-keys | Bearer (dashboard) | — |
| live | PATCH | /api/calendars/:slug/api-keys/:keyId | /api/calendars/:slug/api-keys/:keyId | Bearer (dashboard) | — |
| live | DELETE | /api/calendars/:slug/api-keys/:keyId | /api/calendars/:slug/api-keys/:keyId | Bearer (dashboard) | — |
| divergent | POST | /api/events | /api/v1/events | x-njanggo-api-key | events:write |
| divergent | GET | /api/events | /api/v1/calendars/:slug/events | x-njanggo-api-key | events:read |
| divergent | GET | /api/events/slug/:slug | /api/v1/events/:slug | x-njanggo-api-key ou none | events:read |
| live | GET | /api/v1/events/:eventId/guests | /api/v1/events/:eventId/guests | x-njanggo-api-key | guests:read |
| divergent | POST | /api/events/:eventId/guests | /api/v1/events/:eventId/guests | x-njanggo-api-key | guests:write |
| live | GET | /api/v1/events/:eventId/export | /api/v1/events/:eventId/export | x-njanggo-api-key | guests:read |
| live | POST | /api/v1/events/:eventId/checkins | /api/v1/events/:eventId/checkins | x-njanggo-api-key | checkins:write |
| live | GET | /api/v1/events/:eventId/checkins/lookup | /api/v1/events/:eventId/checkins/lookup | x-njanggo-api-key | checkins:read |
| live | GET | /api/v1/events/:eventId/checkins | /api/v1/events/:eventId/checkins | x-njanggo-api-key | checkins:read |
| preview | GET | — | /api/v1/webhook-deliveries | x-njanggo-api-key | webhooks:read |
| preview | POST | — | /api/v1/webhook-deliveries/:id/retry | x-njanggo-api-key | webhooks:write |
| divergent | GET | /api/events/:eventId/orders | /api/v1/events/:eventId/orders | x-njanggo-api-key | billing:read |
| divergent | POST | /api/events/:eventId/orders/:orderId/refund | /api/v1/events/:eventId/orders/:orderId/refund | x-njanggo-api-key | billing:write |
| divergent | GET | /api/coupons/calendar/:slug | /api/v1/calendars/:slug/coupons | x-njanggo-api-key | events:read |
| live | GET | /api/health | /api/health | none | — |
Formats de réponse
Pagination actuelle (@njanggo/types PaginatedResponse) : { data, total, page, limit, totalPages }
Pagination cible Pro : { data, meta: { page, limit, total, totalPages } } — convergence prévue phase Pro.
Erreurs actuelles : { statusCode, message, path, timestamp }
Erreurs cibles : { statusCode, message, errors: [{ field, message }] }
OpenAPI
Le contrat machine-readable est disponible à /v1/openapi.json. Chaque opération inclut x-njanggo-status et x-njanggo-current-path quand applicable.