Creare un flipbook (da un PDF o da un URL)

Cosa puoi fare

Ci sono due modi per creare un flipbook da un PDF, a seconda di dove si trova il PDF:

• Caricare il file direttamente — invia il PDF come multipart/form-data.
• Puntare a un URL — fornisci un URL PDF e lascia che il server lo scarichi per te.

In entrambi i casi, il file viene memorizzato, viene generata una miniatura, il record viene registrato e ottieni l'ID del nuovo elemento, il suo URL di visualizzazione e la quota del tuo piano aggiornata. Usa l'ID restituito per le chiamate successive (set-meta, set-cta-primary, save-as-template e così via).

Prima di iniziare

• Una chiave API — inviata come header X-Api-Key, o come Authorization: Bearer YOUR_API_KEY, in ogni richiesta.
• Tutte le richieste vanno all'URL di base https://go.fliplink.me.
• Se creare un Flipbook o un Document si sceglie con il campo facoltativo DocType: omettilo o invia DocType=Flipbook per un flipbook (l'impostazione predefinita), oppure DocType=Document per un documento — FlipLink supporta entrambi.
• I campi della quota restituiti (Flipbooks_Count / Flipbooks_Max / Flipbooks_Left) riflettono la quota del tuo piano dopo la creazione.

Nessuno dei due endpoint usa un parametro nel percorso — crei facendo il POST all'endpoint stesso e ottieni l'ID nuovo. Create by File usa multipart/form-data. Create by URL è form-urlencoded (non JSON).

Creare da un PDF caricato

POST /api/create-by-file crea un flipbook da un PDF caricato inviato come multipart/form-data. Il file viene memorizzato, viene generata una miniatura e il record viene registrato. L'unico campo obbligatorio è File; Name, Title e DocType sono facoltativi. La dimensione massima del file dipende dal piano (vedi MaxFileSizeMB da who-am-i).

curl -X POST 'https://go.fliplink.me/api/create-by-file' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -F 'File=@/path/to/file' \
  -F 'Name=My Document' \
  -F 'Title=My Title' \
  -F 'DocType=Flipbook'

DocType è Flipbook (l'impostazione predefinita) o Document — invia DocType=Document per creare un documento invece di un flipbook.

Risposta:

{
  "Result": "OK",
  "ID": "90001",
  "URL": "https://go.fliplink.me/view/<slug>",
  "Flipbooks_Count": 12,
  "Flipbooks_Max": 200,
  "Flipbooks_Left": 188
}

Creare da un URL PDF

POST /api/create-by-url crea un flipbook da un URL PDF. Il server scarica FileURL, lo carica su S3, genera una miniatura e registra il record. Il body è form-urlencoded. L'unico campo obbligatorio è FileURL; Name, Title e DocType sono facoltativi.

curl -X POST 'https://go.fliplink.me/api/create-by-url' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'FileURL=https://example.com/document.pdf' \
  --data-urlencode 'Name=My Document' \
  --data-urlencode 'Title=My Title' \
  --data-urlencode 'DocType=Flipbook'

L'URL di origine deve rispondere entro 60s — origini lente o irraggiungibili falliscono con Source URL timed out after 60s. Per origini poco affidabili, preferisci /api/create-by-file.

Risposta:

{
  "Result": "OK",
  "ID": "90001",
  "URL": "https://go.fliplink.me/view/<slug>",
  "Flipbooks_Count": 12,
  "Flipbooks_Max": 200,
  "Flipbooks_Left": 188
}

Errori possibili

Create by File:

• Chiave API mancante o non valida → HTTP 401. Restituisce una semplice pagina HTML di Unauthorized — non c'è alcun body JSON.
• Il file caricato non è un PDF leggibile → HTTP 200, messaggio File is not a valid PDF.
• L'upload supera la dimensione massima del file del piano → HTTP 413, messaggio File exceeds the maximum allowed upload size.

Create by URL:

• Chiave API mancante o non valida → HTTP 401. Restituisce una semplice pagina HTML di Unauthorized — non c'è alcun body JSON.
• L'host di FileURL è privato o non consentito → HTTP 200, messaggio FileURL host is not allowed.
• Campo del body sconosciuto o scritto male → HTTP 200, messaggio Unknown field(s) '…'. Expected: …

Note

• I valori Flipbooks_Count / Flipbooks_Max / Flipbooks_Left riflettono la quota del tuo piano dopo questa creazione.
• Conserva l'ID restituito — è quello che passi alle chiamate successive (set-meta, set-cta-primary, save-as-template e altre).