Comment consommer l’API
Guide pas à pas — choisir Plus ou Pro, authentifier, envoyer votre première requête, recevoir un webhook.
Dans cet article
Plus ou Pro ?
| Vous voulez… | Plan | Comment | Auth |
|---|---|---|---|
| Slack / Zapier / Sheets à chaque inscription | Plus | Webhook → URL Zapier | Secret whsec_… (pas de clé API) |
| Liste d’events sur votre site | Plus | Widget iframe (onglet Intégrer) | Aucune |
| Lire events publics | Plus | GET /api/calendars/:slug/events | Aucune |
| Agenda Google à jour | Plus | Flux ICS (bientôt) | Token dans l’URL |
| Créer des events depuis votre CMS | Pro | POST /api/v1/events (à venir) | nj_live_… |
| Exporter invités / check-in kiosque | Pro | GET export, POST checkins | nj_live_… |
| Sync ventes vers ERP | Pro | GET orders (Bearer aujourd’hui) | nj_live_… (cible) |
Authentification — quel token quand ?
| Mécanisme | Plan | Où le récupérer | Usage |
|---|---|---|---|
| Secret webhook whsec_… | Plus | Création webhook (dashboard) | Vérifier les POST entrants — pas pour appeler l’API |
| Bearer Clerk | Plus / Pro | Session njanggo.com (auto) | Configurer webhooks, dashboard, Try It! |
| Clé API nj_live_… | Pro | Paramètres → Développeur → Clés API | Automatisations serveur sur /api/v1/… |
| Aucune | Tous | — | Lecture publique calendrier / events |
URL de base
https://api.njanggo.com/apihttp://localhost:3001/apiPlus : webhooks et lecture publique sous /api/calendars/… et /api/events/… (sans /v1).
Pro : namespace /api/v1/… avec en-tête x-njanggo-api-key. Gestion des clés : /api/calendars/:slug/api-keys (Bearer dashboard).
Consommer Plus (sans clé API)
- 1
1. Ouvrir le panneau Développeur
njanggo.com → votre calendrier → Paramètres → Développeur. Requis : plan Plus ou Pro (onglet masqué en Free).
- 2
2. Choisir votre intégration
Webhook : Gérer l'événement → section Webhooks (aujourd'hui par événement). Site web : onglet Intégrer (iframe calendrier).
- 3
3. Webhook Zapier / Make
Créez un Catch Hook, collez l'URL dans le webhook, cochez
guest.registered, copiez le secretwhsec_…(une fois). - 4
4. Tester
Bouton Tester dans le dashboard ou inscription test. Votre outil reçoit un POST JSON signé.
Création webhook aujourd’hui (Bearer, par événement) :
curl -X POST "https://api.njanggo.com/api/events/evt_abc123/webhooks" \
-H "Authorization: Bearer $NJANGGO_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"https://hooks.zapier.com/hooks/catch/123456/abcdef/","events":["guest.registered"]}'POST /api/calendars/:slug/webhooks — actuel vs cible. Guide Zapier : Zapier & Make.Consommer Pro (clé API)
- 1
1. Créer une clé API
Plan Pro → Paramètres → Développeur → Clés API. Nommez la clé, cochez les scopes minimums, copiez
nj_live_…(affichée une seule fois). Max 3 clés actives par calendrier. - 2
2. Première requête
En-tête
x-njanggo-api-key. Testez avec la fiche calendrier : - 3
3. Endpoints live
Aujourd'hui : fiche calendrier, invités, export CSV/JSON, check-ins (lookup + création). CRUD events complet : en cours.
curl -X GET "https://api.njanggo.com/api/v1/calendars/mon-collectif" \
-H "x-njanggo-api-key: $NJANGGO_API_KEY"GET /api/v1/calendars/:slug (events:read)
GET /api/v1/events/:eventId/guests (guests:read)
GET /api/v1/events/:eventId/export (guests:read, ?format=csv|json)
GET /api/v1/events/:eventId/checkins (checkins:read)
GET /api/v1/events/:eventId/checkins/lookup?qrCode=… (checkins:read)
POST /api/v1/events/:eventId/checkins (checkins:write)Recevoir un webhook (votre serveur)
Njanggo envoie un POST JSON vers votre URL. Format actuel (webhooks par événement) :
| En-tête | Description |
|---|---|
| X-Njanggo-Webhook-Event | Type : guest.registered, checkin.created, … |
| X-Njanggo-Webhook-Timestamp | Unix timestamp (secondes) |
| X-Njanggo-Webhook-Signature | t=<timestamp>,v1=<hex> — HMAC de "{timestamp}.{body}" |
| Content-Type | application/json |
import crypto from 'crypto';
function verifyNjanggoWebhook(rawBody: string, header: string, secret: string) {
const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split('=')));
const payload = `${parts.t}.${rawBody}`;
const expected = crypto.createHmac('sha256', secret).update(payload, 'utf8').digest('hex');
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ''));
}Cible Plus (webhooks calendrier) : en-têtes X-Njanggo-Event, X-Njanggo-Signature: sha256=…, X-Njanggo-Delivery-Id — voir Webhooks → Signature.
Ce qui est live aujourd’hui
| Fonctionnalité | Statut | Chemin / accès |
|---|---|---|
| Panneau Développeur dashboard | ✓ Live | Plus & Pro — Paramètres calendrier |
| Webhooks par événement | ✓ Live | POST /api/events/:id/webhooks (Bearer) |
| Widget iframe calendrier | ✓ Live | Onglet Intégrer (dashboard) |
| Lecture publique calendrier/events | ✓ Live | GET /api/calendars/:slug, /events |
| Clés API Pro (CRUD) | ✓ Live | GET/POST /api/calendars/:slug/api-keys |
| API REST /v1 (partiel) | ✓ Live | Calendrier, guests, export, checkins |
| Webhooks calendrier | ◎ Cible | POST /api/calendars/:slug/webhooks |
| Flux ICS | ◎ Cible | GET /api/calendars/:slug/events.ics |
| embed.json | ◎ Cible | GET /api/calendars/:slug/embed.json |
| CRUD events /v1 | ◎ Cible | POST /api/v1/events |
| Logs webhook Pro | ◎ Cible | GET /api/v1/webhook-deliveries |
Table complète : Migration /api → /v1 · Roadmap.
Outils
Playground Try It! sur chaque page endpoint, snippets multi-langages, schémas dans Schémas ressource.