Articolo tecnico · REST v1

Documentazione API Foliade

API introduttiva: 5 conversioni riuscite in 30 giorni, una alla volta; 50 MB e 100 pagine per PDF, 250 MB di pacchetti API conservati.

MCP è incluso dal piano gratuito. API completa, statistiche, caricamento in blocco e webhook sono inclusi da Pro. L’esportazione HTML autonoma è inclusa da Business.

Apri riferimento interattivo Scarica OpenAPI

Autenticazione del portatore

Crea una chiave in Foliade → API, quindi inviala nell'intestazione Authorization. La chiave dà accesso ai cataloghi del suo account: conservala in un gestore dei segreti e mai nel codice sorgente.

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

Ciclo di vita chiave

creare una chiave dedicata per ogni integrazione;
copiarne il valore durante la creazione;
monitorare la sua ultima chiamata;
revocarlo non appena non sarà più utilizzato.

Viene data risposta a una chiave mancante, sconosciuta o revocata 401.

Endpoint v1

Metodo	Percorso	Risultato
`POST`	`/v1/catalogs`	Converte un PDF, bozza o pubblicato.
`POST`	`/v1/catalogs/bulk`	Accetta una fonte pubblica e avvia un batch.
`GET`	`/v1/catalogs`	Elenca i cataloghi dell'account.
`GET`	`/v1/catalogs/{id}`	Restituisce il catalogo e lo stato dell'ultima conversione.
`POST`	`/v1/catalogs/{id}/publish`	Pubblica una bozza esistente senza riconvertirla né modificarne il link.
`GET`	`/v1/catalogs/{id}/stats?days=30`	Restituisce letture, lettori, contatti e visualizzazioni di pagina.
`DELETE`	`/v1/catalogs/{id}`	Annulla la pubblicazione del catalogo senza eliminare i dati dell'account.
`GET`	`/v1/me`	Controlla la chiave, l'offerta e il numero di cataloghi.

Pubblica un PDF

Invia un corpo multipart/form-data. Solo fichier è obbligatorio. publier=0 crea una bozza; publier=1 rende pubblico il collegamento. Con attendre=1, la query attende la conversione fino a 300 secondi prima di eseguire il rendering di a 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	Predefinito	Descrizione
`fichier`	—	API introduttiva: 50 MB e 100 pagine per PDF. API completa: 300 MB per PDF.
`remplace`	—	Identificativo di un catalogo dell'account da sostituire senza modificarne link o protezione. Una conversione riuscita consuma un'unità della quota introduttiva.
`titre`	nome del file	Titolo visibile del catalogo.
`langue`	lingua dell'account	Codice della lingua supportato dal lettore.
`publier`	`0`	`1` per aprire immediatamente il collegamento pubblico.
`attendre`	`1`	`0` per ricevere immediatamente lavoro asincrono.

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

Elaborazione di massa

L'API completa è inclusa da Pro.

Il punto di ingresso in blocco riceve un URL HTTP(S) pubblico in un corpo JSON. Il webhook è facoltativo. La risposta 202 contiene l'identificativo del lotto accettato.

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 fonte è un archivio ZIP fino a 2 GB, con un massimo di 500 PDF da 300 MB ciascuno. Le notifiche utilizzano una coda persistente: dopo un errore HTTP, vengono pianificati cinque tentativi dopo 1 minuto, 5 minuti, 15 minuti, 1 ora e 6 ore.

Ogni notifica include un identificatore stabile e una firma HMAC-SHA256. Recupera il segreto di firma del tuo spazio tramite l'API Identity. Verifica la firma del corpo HTTP non elaborato, rifiuta i timestamp più vecchi di cinque minuti e deduplica gli eventi già elaborati. Una rotazione della chiave dell'applicazione rinnova i segreti.

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)

Statistiche

Le statistiche richiedono Pro.

Il periodo viene trasmesso con days. L'API REST e il server MCP ospitato accettano un numero intero compreso tra 1 e 3650 giorni. I valori fuori range vengono rifiutati.

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

Risposte ed errori

Stato	Significato	Azione
`201`	Conversione completata.	Utilizzare `url` e `id`.
`202`	Conversione o lotto accettato, ancora in corso.	Conservare l'ID restituito.
`400`	L'origine collettiva non è un URL pubblico accettato.	Fornire un URL HTTP(S) accessibile.
`401`	Chiave mancante, sconosciuta o revocata.	Controlla l'intestazione o crea una chiave.
`403`	Funzione riservata a un piano superiore o account sospeso.	Verifica i permessi dell'account.
`404`	Catalogo mancante dall'account autenticato.	Controlla l'ID e la chiave.
`409`	Conversione in corso, posti occupati o spazio esaurito.	Attendi o libera un posto nel tuo account.
`413`	Il PDF supera il limite di dimensione o pagine del tuo piano.	Ridurre o dividere il documento.
`422`	PDF protetto, danneggiato o conversione non riuscita.	Riesportare un PDF leggibile senza password.
`429`	Quota API o limite di protezione raggiunto.	Controlla le quote prima di riprovare.

Protezione dagli abusi: 60 chiamate API al minuto e 10 tentativi di caricamento ogni 24 ore, condivisi con sito e MCP. Gli errori contano nel limite giornaliero, non nella quota mensile.

Eliminare o ritirare una pubblicazione non restituisce una conversione riuscita. I 5 posti di pubblicazione sono condivisi con i caricamenti web. Bozze e archivi API contano nei 5 cataloghi API conservati e nei 250 MB di spazio.

Dopo una risposta 202, consulta il catalogo per seguire la conversione. La risposta dell'identità dell'account indica le quote introduttive rimanenti; il segreto webhook è fornito solo a Pro e piani superiori.

Server API o MCP?

L'API è adatta per un'applicazione, un backend o un canale editoriale. Il server MCP racchiude le stesse operazioni con strumenti che Codex e Claude Code possono chiamare sotto il controllo dell'utente.

Comprendere la differenza tra MCP e API

Riferimento eseguibile

La documentazione Swagger e lo schema OpenAPI vengono generati dalle rotte effettivamente distribuite.

Prova su Swagger UI

Registro delle modifiche

Versione	Data	Cambiamenti
v1	28 agosto 2026	Documentazione pubblica di conversione, batch, statistiche, annullamento della pubblicazione e identità dell'account.