Guia de Inicio Rapido
Comienza a usar la API de ZenFlip en menos de cinco minutos. Crea tu primera clave API, autenticate y lista tus publicaciones.
Guia de Inicio Rapido
Esta guia te lleva paso a paso a traves de la obtencion de credenciales, la autenticacion con la API de ZenFlip y la realizacion de tu primera solicitud exitosa. Al finalizar, habras listado todas las publicaciones de tu organizacion.
URL Base
Todas las solicitudes a la API se realizan a la URL base versionada:
` https://api.zenflip.io/v1 `
Cada endpoint documentado en esta guia es relativo a esa URL base. Por ejemplo, el endpoint de inicio de sesion se resuelve como https://api.zenflip.io/v1/auth/login.
Paso 1 --- Obtener Tu Clave API
ZenFlip admite dos metodos de autenticacion: tokens JWT (para aplicaciones orientadas al usuario) y claves API (para integraciones servidor a servidor).
Para crear una clave API:
Inicia sesion en el panel de control de ZenFlip en
https://app.zenflip.io.Navega a Settings > API Keys.
Haz clic en Generate New Key, dale una etiqueta descriptiva (ej., "Production Backend") y copia la clave inmediatamente. No se mostrara de nuevo.
Las claves API estan vinculadas a tu organizacion. Las solicitudes realizadas con una clave API heredan los permisos del propietario de la organizacion.
Paso 2 --- Autenticar
Opcion A: Clave API (Servidor a Servidor)
Pasa tu clave API en el encabezado Authorization con el prefijo Bearer:
`bash curl https://api.zenflip.io/v1/publications \ -H "Authorization: Bearer zf_live_abc123yourAPIkeyHere" `
Opcion B: Token JWT (Sesiones de Usuario)
Obtiene un token de acceso JWT de corta duracion llamando al endpoint de inicio de sesion:
`bash curl -X POST https://api.zenflip.io/v1/auth/login \ -H "Content-Type: application/json" \ -d '{ "email": "you@example.com", "password": "your-password" }' `
Una respuesta exitosa devuelve un token de acceso y un token de actualizacion:
`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" } } `
Usa el accessToken en solicitudes posteriores:
`bash curl https://api.zenflip.io/v1/publications \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." `
Paso 3 --- Realizar Tu Primera Llamada a la API
Lista todas las publicaciones de tu organizacion con una simple solicitud GET:
`bash curl https://api.zenflip.io/v1/publications?page=1&limit=10 \ -H "Authorization: Bearer YOUR_TOKEN" `
La respuesta sigue el formato paginado estandar:
`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 } } `
Formato de Respuesta
Todas las respuestas exitosas envuelven los datos en una clave data. Los endpoints paginados incluyen un objeto meta con detalles de paginacion.
Respuestas de Error
Cuando una solicitud falla, la API devuelve una estructura de error consistente:
`json { "statusCode": 401, "message": "Invalid or expired token", "error": "Unauthorized" } `
Codigo de Estado | Significado |
|---|---|
| Bad Request --- entrada invalida |
| Unauthorized --- token faltante o invalido |
| Forbidden --- permisos insuficientes |
| Not Found --- el recurso no existe |
| Too Many Requests --- limite de tasa alcanzado |
| Internal Server Error |
Limites de Tasa
La API aplica limites de tasa por minuto segun tu plan:
Plan | Limite de Tasa |
|---|---|
Explorer | 100 req/min |
Creator | 100 req/min |
Business | 100 req/min |
Enterprise | 1,000 req/min |
Cuando excedes el limite, la API devuelve un estado 429 con un encabezado Retry-After que indica cuantos segundos esperar.
Proximos Pasos
[Autenticacion](/docs/authentication) --- Profundiza en tokens JWT, flujos de actualizacion y Google OAuth.
[API de Publicaciones](/docs/publications-api) --- Crea, actualiza y gestiona tus flipbooks.
[Widget de Integracion](/docs/embed-quickstart) --- Anade flipbooks interactivos a cualquier sitio web.