Configurare un dominio personalizzato (CNAME)

Cosa puoi fare

Un dominio personalizzato (CNAME) permette a un flipbook di essere servito da un hostname di tua proprietà, come docs.example.com. Una volta che un dominio è stato aggiunto e verificato nella dashboard web, questi tre endpoint ti permettono di gestire dall'API il collegamento tra quel dominio e i tuoi flipbook:

• Aggiungere un collegamento CNAME a un flipbook.
• Elencare ogni CNAME del tuo account, con i flipbook a cui ciascuno è collegato.
• Eliminare un collegamento CNAME da un flipbook o da tutti in una volta.

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.
• Add CNAME agisce su un flipbook specifico tramite il segmento di percorso {flipbookId} — l'ID numerico restituito da create-by-file / create-by-url o da list. List e Delete non usano un parametro {flipbookId} nel percorso.
• Il CNAME deve esistere già ed essere attivato sul tuo account — aggiunto e verificato tramite la dashboard web, che predispone il DNS e l'SSL. L'API si limita a salvare il collegamento; non verifica il DNS né emette certificati.
• Per Add CNAME, il body della richiesta è form-urlencoded (non JSON).

Aggiungere un CNAME a un flipbook

Collega un dominio personalizzato già attivato a un flipbook. Passa l'hostname completo come CNAME. IsCloudflare è facoltativo e predefinito a 0; passa 1 se il tuo DNS è servito dal proxy di Cloudflare.

curl -X POST 'https://go.fliplink.me/api/add-cname/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'CNAME=docs.example.com' \
  --data-urlencode 'IsCloudflare=0'

Risposta:

{
  "Result": "OK",
  "Message": "Updated successfully"
}

Se il dominio non è stato prima attivato sul tuo account, la richiesta viene rifiutata con: Please add CNAME <domain> to your account using the web dashboard. Only activated CNAMEs are allowed to be created via API.

Elencare i tuoi CNAME

Restituisce tutti i CNAME personalizzati del chiamante. Ogni elemento riporta l'hostname, il numero di flipbook attivi a cui è collegato (Documents) e l'elenco degli ID di quei flipbook attivi (FlipbookIDs).

curl -X GET 'https://go.fliplink.me/api/list-cnames' \
  -H 'X-Api-Key: YOUR_API_KEY'

Risposta:

{
  "Result": "OK",
  "Items": [
    {
      "CNAME": "ttr.antifragile.ae",
      "Documents": 1,
      "FlipbookIDs": [
        93270
      ]
    }
  ]
}

Eliminare un collegamento CNAME

Rimuove il collegamento di un dominio personalizzato da uno o tutti i tuoi flipbook. Ci sono due modalità:

• In blocco (predefinita): passa CNAME=<host> e lascia FlipbookID vuoto — rimuove quel CNAME da ogni flipbook di tua proprietà.
• Per flipbook: passa FlipbookID=<id> (maggiore di 0) — il CNAME viene cercato in quel flipbook e rimosso solo da quello.

Passa il CNAME come parametro di query (non come segmento dell'URL) per evitare problemi con i punti nell'hostname.

curl -X DELETE 'https://go.fliplink.me/api/delete-cname?CNAME=docs.example.com&FlipbookID=' \
  -H 'X-Api-Key: YOUR_API_KEY'

Il curl qui sopra viene eseguito in modalità in blocco (FlipbookID lasciato vuoto), quindi la sua risposta è:

{
  "Result": "OK",
  "Message": "CNAME removed successfully"
}

In modalità per flipbook (FlipbookID maggiore di 0), il messaggio è invece { "Result": "OK", "Message": "CNAME removed from flipbook successfully" }. Se non passi né CNAME né FlipbookID, la risposta è { "Result": "ERROR", "Message": "CNAME or FlipbookID is required" }.

Errori possibili

• Chiave API mancante o non valida → HTTP 401. Restituisce una semplice pagina HTML di Unauthorized — non c'è alcun body JSON. Controlla che l'header X-Api-Key sia presente e corretto.
• flipbookId sconosciuto (o non di proprietà della tua chiave), su Add CNAME → HTTP 200 con { "Result": "ERROR", "Message": "Item not found" }.
• Campo del body sconosciuto o scritto male, su Add CNAME → HTTP 200 con { "Result": "ERROR", "Message": "Unknown field(s) '…'. Expected: …" }.
• Eliminazione senza né CNAME né FlipbookID → { "Result": "ERROR", "Message": "CNAME or FlipbookID is required" }.

Note

• Aggiungere un CNAME tramite l'API salva solo il collegamento — non verifica il DNS né emette certificati. Aggiungi e verifica prima il dominio nella dashboard web.
• Il CNAME deve rientrare nel limite di CNAME del tuo piano.