{"openapi":"3.1.0","info":{"title":"Njanggo API","version":"1.0.0-preview","description":"Contrat cible API premium Njanggo (Plus / Pro / Enterprise). Certaines opérations sont en preview ou divergent du backend actuel (/api + Clerk). Voir la documentation sur docs.njanggo.com.","contact":{"name":"Njanggo","url":"https://njanggo.com"}},"servers":[{"url":"https://api.njanggo.com/api","description":"Production"},{"url":"http://localhost:3001/api","description":"Développement local"}],"tags":[{"name":"Webhooks Plus"},{"name":"ICS"},{"name":"Widget"},{"name":"Exports"},{"name":"Calendriers"},{"name":"Clés API"},{"name":"Événements"},{"name":"Invités"},{"name":"Check-in"},{"name":"Webhooks Pro"},{"name":"Ventes"},{"name":"Coupons"},{"name":"Système"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-njanggo-api-key","description":"Clé API Pro (prefix nj_live_ ou nj_test_)"},"BearerAuth":{"type":"http","scheme":"bearer","description":"Token session dashboard (Clerk) — Plus et gestion clés"}},"schemas":{"ApiResponse":{"type":"object","properties":{"data":{},"message":{"type":"string"}},"required":["data"]},"PaginatedResponseTarget":{"type":"object","properties":{"data":{"type":"array","items":{}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}}}},"PaginatedResponseCurrent":{"type":"object","description":"Format actuel backend (@njanggo/types PaginatedResponse)","properties":{"data":{"type":"array","items":{}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"}}},"ApiErrorTarget":{"type":"object","properties":{"statusCode":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}},"WebhookPayload":{"type":"object","properties":{"id":{"type":"string","description":"del_* delivery id"},"type":{"type":"string","enum":["guest.registered","checkin.created","event.updated","event.cancelled","announcement.sent","reminder.sent"]},"createdAt":{"type":"string","format":"date-time"},"calendarSlug":{"type":"string"},"data":{"type":"object"}}}}},"paths":{"/api/calendars/{slug}/webhooks":{"get":{"operationId":"listCalendarWebhooks","summary":"Lister les webhooks du calendrier","description":"Aujourd’hui : webhooks par événement, pas par calendrier.\n\nChemin actuel : `GET /api/events/:eventId/webhooks`\n\nStatut implémentation : divergent","tags":["Webhooks Plus"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"divergent","x-njanggo-plan":"Plus","x-njanggo-current-path":"/api/events/:eventId/webhooks"},"post":{"operationId":"createCalendarWebhook","summary":"Créer un webhook calendrier","description":"Chemin actuel : `POST /api/events/:eventId/webhooks`\n\nStatut implémentation : divergent","tags":["Webhooks Plus"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"divergent","x-njanggo-plan":"Plus","x-njanggo-current-path":"/api/events/:eventId/webhooks"}},"/api/calendars/{slug}/webhooks/{id}/test":{"post":{"operationId":"testCalendarWebhook","summary":"Envoyer un événement test","description":"Chemin actuel : `POST /api/events/:eventId/webhooks/:id/test`\n\nStatut implémentation : divergent","tags":["Webhooks Plus"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"divergent","x-njanggo-plan":"Plus","x-njanggo-current-path":"/api/events/:eventId/webhooks/:id/test"}},"/api/calendars/{slug}/events.ics":{"get":{"operationId":"getCalendarIcsFeed","summary":"Flux ICS public ou privé","description":"Non déployé — spec validée.\n\nStatut implémentation : planned","tags":["ICS"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"planned","x-njanggo-plan":"Plus"}},"/api/calendars/{slug}/embed.json":{"get":{"operationId":"getCalendarEmbedJson","summary":"Données JSON pour widget custom","description":"Aujourd’hui : GET /api/calendars/:slug/events. embed.json en cours.\n\nChemin actuel : `GET /api/calendars/:slug/events`\n\nStatut implémentation : divergent","tags":["Widget"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"divergent","x-njanggo-plan":"Plus","x-njanggo-current-path":"/api/calendars/:slug/events"}},"/api/calendars/{slug}/scheduled-exports":{"post":{"operationId":"createScheduledExport","summary":"Planifier un export récurrent","description":"Statut implémentation : preview","tags":["Exports"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"preview","x-njanggo-plan":"Plus"}},"/api/v1/calendars/{slug}":{"get":{"operationId":"getCalendar","summary":"Fiche calendrier","description":"Chemin actuel : `GET /api/v1/calendars/:slug`\n\nScopes requis : events:read\n\nStatut implémentation : live","tags":["Calendriers"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"live","x-njanggo-plan":"Pro","x-njanggo-current-path":"/api/v1/calendars/:slug"}},"/api/v1/api-keys":{"get":{"operationId":"listApiKeys","summary":"Lister les clés API du calendrier","description":"Gestion : /api/calendars/:slug/api-keys. Usage REST : x-njanggo-api-key sur /api/v1/…\n\nChemin actuel : `GET /api/calendars/:slug/api-keys`\n\nStatut implémentation : live","tags":["Clés API"],"parameters":[],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"live","x-njanggo-plan":"Pro","x-njanggo-current-path":"/api/calendars/:slug/api-keys"},"post":{"operationId":"createApiKey","summary":"Créer une clé API","description":"Chemin actuel : `POST /api/calendars/:slug/api-keys`\n\nStatut implémentation : live","tags":["Clés API"],"parameters":[],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"live","x-njanggo-plan":"Pro","x-njanggo-current-path":"/api/calendars/:slug/api-keys"}},"/api/calendars/{slug}/api-keys/{keyId}":{"patch":{"operationId":"patchApiKey","summary":"Renommer ou désactiver une clé API","description":"Chemin actuel : `PATCH /api/calendars/:slug/api-keys/:keyId`\n\nStatut implémentation : live","tags":["Clés API"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"keyId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"live","x-njanggo-plan":"Pro","x-njanggo-current-path":"/api/calendars/:slug/api-keys/:keyId"},"delete":{"operationId":"revokeApiKey","summary":"Révoquer une clé API","description":"Chemin actuel : `DELETE /api/calendars/:slug/api-keys/:keyId`\n\nStatut implémentation : live","tags":["Clés API"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"keyId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"live","x-njanggo-plan":"Pro","x-njanggo-current-path":"/api/calendars/:slug/api-keys/:keyId"}},"/api/v1/events":{"post":{"operationId":"createEvent","summary":"Créer un événement","description":"Chemin actuel : `POST /api/events`\n\nScopes requis : events:write\n\nStatut implémentation : divergent","tags":["Événements"],"parameters":[],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"divergent","x-njanggo-plan":"Pro","x-njanggo-current-path":"/api/events"}},"/api/v1/calendars/{slug}/events":{"get":{"operationId":"listCalendarEvents","summary":"Lister les événements d’un calendrier","description":"Chemin actuel : `GET /api/events`\n\nScopes requis : events:read\n\nStatut implémentation : divergent","tags":["Événements"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"divergent","x-njanggo-plan":"Pro","x-njanggo-current-path":"/api/events"}},"/api/v1/events/{slug}":{"get":{"operationId":"getEventBySlug","summary":"Détail événement public","description":"Chemin actuel : `GET /api/events/slug/:slug`\n\nScopes requis : events:read\n\nStatut implémentation : divergent","tags":["Événements"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"divergent","x-njanggo-plan":"Pro","x-njanggo-current-path":"/api/events/slug/:slug"}},"/api/v1/events/{eventId}/guests":{"get":{"operationId":"listEventGuests","summary":"Lister les invités","description":"Également accessible via /api/events/:eventId/guests (Bearer uniquement).\n\nChemin actuel : `GET /api/v1/events/:eventId/guests`\n\nScopes requis : guests:read\n\nStatut implémentation : live","tags":["Invités"],"parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"live","x-njanggo-plan":"Pro","x-njanggo-current-path":"/api/v1/events/:eventId/guests"},"post":{"operationId":"createEventGuest","summary":"Ajouter un invité","description":"Chemin actuel : `POST /api/events/:eventId/guests`\n\nScopes requis : guests:write\n\nStatut implémentation : divergent","tags":["Invités"],"parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"divergent","x-njanggo-plan":"Pro","x-njanggo-current-path":"/api/events/:eventId/guests"}},"/api/v1/events/{eventId}/export":{"get":{"operationId":"exportEventGuests","summary":"Exporter invités CSV/JSON","description":"Également accessible via /api/events/:eventId/export (Bearer uniquement).\n\nChemin actuel : `GET /api/v1/events/:eventId/export`\n\nScopes requis : guests:read\n\nStatut implémentation : live","tags":["Invités"],"parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"live","x-njanggo-plan":"Pro","x-njanggo-current-path":"/api/v1/events/:eventId/export"}},"/api/v1/events/{eventId}/checkins":{"post":{"operationId":"createCheckin","summary":"Enregistrer un check-in","description":"Chemin actuel : `POST /api/v1/events/:eventId/checkins`\n\nScopes requis : checkins:write\n\nStatut implémentation : live","tags":["Check-in"],"parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"live","x-njanggo-plan":"Pro","x-njanggo-current-path":"/api/v1/events/:eventId/checkins"},"get":{"operationId":"listCheckins","summary":"Lister les check-ins","description":"Chemin actuel : `GET /api/v1/events/:eventId/checkins`\n\nScopes requis : checkins:read\n\nStatut implémentation : live","tags":["Check-in"],"parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"live","x-njanggo-plan":"Pro","x-njanggo-current-path":"/api/v1/events/:eventId/checkins"}},"/api/v1/events/{eventId}/checkins/lookup":{"get":{"operationId":"lookupCheckin","summary":"Pré-valider un QR code","description":"Chemin actuel : `GET /api/v1/events/:eventId/checkins/lookup`\n\nScopes requis : checkins:read\n\nStatut implémentation : live","tags":["Check-in"],"parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"live","x-njanggo-plan":"Pro","x-njanggo-current-path":"/api/v1/events/:eventId/checkins/lookup"}},"/api/v1/webhook-deliveries":{"get":{"operationId":"listWebhookDeliveries","summary":"Historique des livraisons webhook","description":"Scopes requis : webhooks:read\n\nStatut implémentation : preview","tags":["Webhooks Pro"],"parameters":[],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"preview","x-njanggo-plan":"Pro"}},"/api/v1/webhook-deliveries/{id}/retry":{"post":{"operationId":"retryWebhookDelivery","summary":"Relancer une livraison échouée","description":"Scopes requis : webhooks:write\n\nStatut implémentation : preview","tags":["Webhooks Pro"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"preview","x-njanggo-plan":"Pro"}},"/api/v1/events/{eventId}/orders":{"get":{"operationId":"listEventOrders","summary":"Lister les commandes","description":"Chemin actuel : `GET /api/events/:eventId/orders`\n\nScopes requis : billing:read\n\nStatut implémentation : divergent","tags":["Ventes"],"parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"divergent","x-njanggo-plan":"Pro","x-njanggo-current-path":"/api/events/:eventId/orders"}},"/api/v1/events/{eventId}/orders/{orderId}/refund":{"post":{"operationId":"refundOrder","summary":"Rembourser une commande","description":"Chemin actuel : `POST /api/events/:eventId/orders/:orderId/refund`\n\nScopes requis : billing:write\n\nStatut implémentation : divergent","tags":["Ventes"],"parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"divergent","x-njanggo-plan":"Pro","x-njanggo-current-path":"/api/events/:eventId/orders/:orderId/refund"}},"/api/v1/calendars/{slug}/coupons":{"get":{"operationId":"listCalendarCoupons","summary":"Lister les coupons calendrier","description":"Chemin actuel : `GET /api/coupons/calendar/:slug`\n\nScopes requis : events:read\n\nStatut implémentation : divergent","tags":["Coupons"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"divergent","x-njanggo-plan":"Pro","x-njanggo-current-path":"/api/coupons/calendar/:slug"}},"/api/health":{"get":{"operationId":"healthCheck","summary":"Santé de l’API","description":"Chemin actuel : `GET /api/health`\n\nStatut implémentation : live","tags":["Système"],"parameters":[],"responses":{"200":{"description":"Succès"},"401":{"description":"Non authentifié"},"403":{"description":"Plan ou scope insuffisant"},"404":{"description":"Ressource introuvable"},"429":{"description":"Rate limit dépassé"}},"x-njanggo-status":"live","x-njanggo-plan":"Pro","x-njanggo-current-path":"/api/health"}}},"x-njanggo-scopes":[{"scope":"events:read","description":"Lecture calendrier, événements, billets, stats"},{"scope":"events:write","description":"CRUD événements, billets, cancel, duplicate"},{"scope":"guests:read","description":"Liste invités, export CSV/JSON"},{"scope":"guests:write","description":"Invite, approve, reject, transfer"},{"scope":"checkins:read","description":"Liste check-ins, lookup QR"},{"scope":"checkins:write","description":"POST check-in"},{"scope":"communications:write","description":"Annonces et rappels e-mail"},{"scope":"webhooks:read","description":"Logs livraisons webhook"},{"scope":"webhooks:write","description":"Retry livraison webhook"},{"scope":"billing:read","description":"Orders, sales-report"},{"scope":"billing:write","description":"Remboursements"},{"scope":"analytics:read","description":"Stats agrégées calendrier"}]}