Guide de démarrage rapide

Guide de démarrage rapide

Ce guide vous accompagne dans l'obtention de vos identifiants, l'authentification auprès de l'API ZenFlip et la réalisation de votre première requête réussie. À la fin, vous aurez listé toutes les publications de votre organisation.

URL de base

Toutes les requêtes API sont envoyées à l'URL de base versionnée :

` https://api.zenflip.io/v1 `

Chaque endpoint documenté dans ce guide est relatif à cette URL de base. Par exemple, l'endpoint de connexion se résout en https://api.zenflip.io/v1/auth/login.

Étape 1 --- Obtenez votre clé API

ZenFlip prend en charge deux méthodes d'authentification : les jetons JWT (pour les applications orientées utilisateur) et les clés API (pour les intégrations serveur à serveur).

Pour créer une clé API :

1. Connectez-vous au tableau de bord ZenFlip à l'adresse https://app.zenflip.io.

2. Naviguez vers Paramètres > Clés API.

3. Cliquez sur Générer une nouvelle clé, donnez-lui un libellé descriptif (ex. : « Backend Production ») et copiez la clé immédiatement. Elle ne sera plus affichée par la suite.

Les clés API sont limitées à votre organisation. Les requêtes effectuées avec une clé API héritent des permissions du propriétaire de l'organisation.

Étape 2 --- Authentifiez-vous

Option A : clé API (serveur à serveur)

Transmettez votre clé API dans l'en-tête Authorization avec le préfixe Bearer :

`bash curl https://api.zenflip.io/v1/publications \ -H "Authorization: Bearer zf_live_abc123yourAPIkeyHere" `

Option B : jeton JWT (sessions utilisateur)

Obtenez un jeton d'accès JWT à courte durée de vie en appelant l'endpoint de connexion :

`bash curl -X POST https://api.zenflip.io/v1/auth/login \ -H "Content-Type: application/json" \ -d '{ "email": "you@example.com", "password": "your-password" }' `

Une réponse réussie renvoie un jeton d'accès et un jeton de rafraîchissement :

`json { "accessToken": "eyJhbGciOiJIUzI1NiIs...", "refreshToken": "eyJhbGciOiJIUzI1NiIs...", "expiresIn": 3600, "user": { "id": "550e8400-e29b-41d4-a716-446655440000", "email": "you@example.com", "name": "Your Name", "role": "owner" }, "organization": { "id": "660e8400-e29b-41d4-a716-446655440000", "name": "Your Organization" } } `

Utilisez le accessToken dans les requêtes suivantes :

`bash curl https://api.zenflip.io/v1/publications \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." `

Étape 3 --- Effectuez votre premier appel API

Listez toutes les publications de votre organisation avec une simple requête GET :

`bash curl https://api.zenflip.io/v1/publications?page=1&limit=10 \ -H "Authorization: Bearer YOUR_TOKEN" `

La réponse suit le format paginé standard :

`json { "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "title": "Product Catalog 2026", "slug": "product-catalog-2026", "status": "published", "accessType": "public", "thumbnailUrl": "https://cdn.zenflip.io/thumbs/a1b2c3d4.jpg", "activeVersionNumber": 2, "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-02-01T14:22:00.000Z" } ], "meta": { "total": 1, "page": 1, "limit": 10, "totalPages": 1 } } `

Format de réponse

Toutes les réponses réussies encapsulent les données dans une clé data. Les endpoints paginés incluent un objet meta avec les détails de pagination.

Réponses d'erreur

Lorsqu'une requête échoue, l'API renvoie une structure d'erreur cohérente :

`json { "statusCode": 401, "message": "Invalid or expired token", "error": "Unauthorized" } `

Limites de débit

L'API applique des limites de débit par minute en fonction de votre forfait :

Lorsque vous dépassez la limite, l'API renvoie un statut 429 avec un en-tête Retry-After indiquant le nombre de secondes à attendre.

Prochaines étapes

• [Authentification](/docs/authentication) --- Approfondissement des jetons JWT, des flux de rafraîchissement et de Google OAuth.

• [API Publications](/docs/publications-api) --- Créez, mettez à jour et gérez vos flipbooks.

• [Widget d'intégration](/docs/embed-quickstart) --- Ajoutez des flipbooks interactifs à n'importe quel site web.