Artículo técnico · REST v1

Documentación de la API Foliade

API de prueba: 5 conversiones correctas en 30 días, una a la vez; 50 MB y 100 páginas por PDF, 250 MB de paquetes API almacenados.

MCP está incluido desde el plan gratuito. La API completa, las estadísticas, la carga masiva y los webhooks se incluyen desde Pro. La exportación HTML autónoma se incluye desde Business.

Abrir referencia interactiva Descargar OpenAPI

Autenticación de portador

Cree una clave en Foliade → API, luego envíela en el encabezado Authorization. La clave da acceso a los catálogos de su cuenta: guárdela en un administrador de secretos y nunca en el código fuente.

export FOLIADE_API_KEY="fl_live_your_key"
curl https://foliade.gekkode.com/v1/me \
  -H "Authorization: Bearer ${FOLIADE_API_KEY}"

Ciclo de vida clave

crear una clave dedicada para cada integración;
copiar su valor al crearlo;
monitorear su última llamada;
revocarlo tan pronto como ya no se utilice.

Se responde a una clave faltante, desconocida o revocada 401.

Puntos finales v1

Método	Camino	Resultado
`POST`	`/v1/catalogs`	Convierte un PDF, borrador o publicado.
`POST`	`/v1/catalogs/bulk`	Acepte una fuente pública e inicie un lote.
`GET`	`/v1/catalogs`	Enumera los catálogos de la cuenta.
`GET`	`/v1/catalogs/{id}`	Devuelve el catálogo y el estado de su última conversión.
`POST`	`/v1/catalogs/{id}/publish`	Publica un borrador existente sin volver a convertirlo ni cambiar su enlace.
`GET`	`/v1/catalogs/{id}/stats?days=30`	Devuelve lecturas, lectores, contactos y visitas a páginas.
`DELETE`	`/v1/catalogs/{id}`	Anula la publicación del catálogo sin eliminar datos de la cuenta.
`GET`	`/v1/me`	Consulta la clave, la oferta y el número de catálogos.

Publicar un PDF

enviar un cuerpo multipart/form-data. solo fichier es obligatorio. publier=0 crea un borrador; publier=1 hace público el enlace. con attendre=1, la consulta espera la conversión hasta 300 segundos antes de generar un 202.

curl -X POST https://foliade.gekkode.com/v1/catalogs \
  -H "Authorization: Bearer ${FOLIADE_API_KEY}" \
  -F "[email protected];type=application/pdf" \
  -F "titre=Catalogue été 2026" \
  -F "langue=fr" \
  -F "publier=1" \
  -F "attendre=1"

campo	Predeterminado	Descripción
`fichier`	—	API de prueba: 50 MB y 100 páginas por PDF. API completa: 300 MB por PDF.
`remplace`	—	Identificador de un catálogo de la cuenta que sustituir, sin cambiar su enlace ni protección. Una conversión correcta consume una unidad de la cuota de prueba.
`titre`	nombre de archivo	Título visible del catálogo.
`langue`	idioma de la cuenta	Código de idioma soportado por el reproductor.
`publier`	`0`	`1` para abrir inmediatamente el enlace público.
`attendre`	`1`	`0` para recibir inmediatamente trabajo asincrónico.

{
  "id": "abc123",
  "url": "https://foliade.gekkode.com/c/abc123",
  "etat": "public",
  "pages": 24,
  "duree_s": 8.4,
  "texte_indexe": true
}

Procesamiento masivo

La API completa se incluye desde Pro.

El punto de entrada masiva recibe una URL HTTP(S) pública en un cuerpo JSON. El webhook es opcional. la respuesta 202 contiene el identificador del lote aceptado.

curl -X POST https://foliade.gekkode.com/v1/catalogs/bulk \
  -H "Authorization: Bearer ${FOLIADE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "https://exemple.fr/catalogues.zip",
    "webhook": "https://exemple.fr/webhooks/foliade"
  }'

La fuente es un archivo ZIP de hasta 2 GB, con un máximo de 500 archivos PDF de 300 MB cada uno. Las notificaciones utilizan una cola persistente: después de un error HTTP, se programan cinco reintentos después de 1 minuto, 5 minutos, 15 minutos, 1 hora y 6 horas.

Cada notificación incluye un identificador estable y una firma HMAC-SHA256. Recupere el secreto de firma de su espacio a través de la API de identidad. Verifique la firma del cuerpo HTTP sin procesar, rechace las marcas de tiempo de más de cinco minutos y elimine los duplicados de eventos ya procesados. Una rotación de la clave de la aplicación renueva los secretos.

GET /v1/me → webhook_signing_secret
X-Foliade-Event-Id: event_id
X-Foliade-Signature: t=timestamp,v1=signature
signature = HMAC-SHA256(webhook_signing_secret, timestamp + "." + raw_body)

Estadísticas

Las estadísticas requieren Pro.

El período se transmite con days. La API REST y el servidor MCP alojado aceptan un número entero de 1 a 3650 días. Se rechazan los valores fuera de rango.

curl "https://foliade.gekkode.com/v1/catalogs/abc123/stats?days=30" \
  -H "Authorization: Bearer ${FOLIADE_API_KEY}"

Respuestas y errores

Estado	Significado	acción
`201`	Conversión completa.	uso `url` y `id`.
`202`	Conversión o lote aceptado, aún en curso.	Conserve la identificación devuelta.
`400`	La fuente masiva no es una URL pública aceptada.	Proporcione una URL HTTP(S) accesible.
`401`	Clave faltante, desconocida o revocada.	Verifique el encabezado o cree una clave.
`403`	Función reservada a un plan superior o cuenta suspendida.	Compruebe los permisos de la cuenta.
`404`	Falta el catálogo de la cuenta autenticada.	Verifique el DNI y la clave.
`409`	Conversión en curso, plazas ocupadas o almacenamiento lleno.	Espere o libere una plaza en su cuenta.
`413`	El PDF supera el límite de tamaño o páginas de su plan.	Reducir o dividir el documento.
`422`	PDF protegido, dañado o la conversión falló.	Vuelva a exportar un PDF legible sin contraseña.
`429`	Cuota API o límite de protección alcanzado.	Consulte sus cuotas antes de reintentar.

Protección contra abusos: 60 llamadas API por minuto y 10 intentos de carga cada 24 horas, compartidos con el sitio y MCP. Los errores cuentan para el límite diario, no para la cuota mensual.

Eliminar o retirar una publicación no devuelve una conversión correcta. Las 5 plazas de publicación se comparten con las cargas web. Los borradores y archivos API cuentan en los 5 catálogos API almacenados y los 250 MB de almacenamiento.

Tras una respuesta 202, consulte el catálogo para seguir la conversión. La respuesta de identidad de la cuenta indica las cuotas de prueba restantes; el secreto del webhook solo se facilita a Pro y planes superiores.

¿Servidor API o MCP?

La API es adecuada para una aplicación, backend o canal editorial. El servidor MCP envuelve las mismas operaciones con herramientas que Codex y Claude Code pueden llamar bajo el control del usuario.

Comprender la diferencia entre MCP y API

Referencia ejecutable

La documentación de Swagger y el esquema OpenAPI se generan a partir de las rutas realmente implementadas.

Prueba en Swagger UI

Registro de cambios

Versión	Fecha	Cambios
v1	28 de agosto de 2026	Documentación pública de conversión, lotes, estadísticas, despublicación e identidad de cuenta.