Configurar un dominio personalizado (CNAME)

Qué puedes hacer

Un dominio personalizado (CNAME) permite servir un flipbook desde un nombre de host que te pertenece, como docs.example.com. Una vez que un dominio se ha añadido y verificado en el panel web, estos tres endpoints te permiten gestionar la vinculación entre ese dominio y tus flipbooks desde la API:

• Añade una vinculación de CNAME a un flipbook.
• Lista todos los CNAME de tu cuenta, con los flipbooks a los que está vinculado cada uno.
• Elimina la vinculación de un CNAME de un flipbook o de todos ellos a la vez.

Antes de empezar

• Una clave de API — enviada como el encabezado X-Api-Key (o como Authorization: Bearer YOUR_API_KEY) en cada solicitud.
• Todas las solicitudes van a la URL base https://go.fliplink.me.
• Add CNAME apunta a un flipbook concreto mediante el segmento de ruta {flipbookId} — el ID numérico que devuelven create-by-file / create-by-url o list. List y Delete no usan un parámetro de ruta {flipbookId}.
• El CNAME debe existir y estar activado en tu cuenta previamente — añadido y verificado a través del panel web, que aprovisiona el DNS y el SSL. La API solo persiste la vinculación; no verifica el DNS ni emite certificados.
• Para Add CNAME, el cuerpo de la solicitud es form-urlencoded (no JSON).

Añade un CNAME a un flipbook

Vincula un dominio personalizado ya activado a un flipbook. Pasa el nombre de host completo como CNAME. IsCloudflare es opcional y su valor por defecto es 0; pasa 1 si tu DNS está detrás del proxy de 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'

Respuesta:

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

Si el dominio no se ha activado antes en tu cuenta, la solicitud se rechaza con: Please add CNAME <domain> to your account using the web dashboard. Only activated CNAMEs are allowed to be created via API.

Lista tus CNAME

Devuelve todos los CNAME personalizados del solicitante. Cada ítem informa del nombre de host, el número de flipbooks activos vinculados a él (Documents) y la lista de los IDs de esos flipbooks activos (FlipbookIDs).

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

Respuesta:

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

Elimina una vinculación de CNAME

Elimina la vinculación de un dominio personalizado de uno o de todos tus flipbooks. Hay dos modos:

• Masivo (por defecto): pasa CNAME=<host> y deja FlipbookID en blanco — elimina ese CNAME de todos los flipbooks que posees.
• Por flipbook: pasa FlipbookID=<id> (mayor que 0) — el CNAME se busca a partir de ese flipbook y se elimina solo de ese.

Pasa el CNAME como parámetro de consulta (no como segmento de URL) para evitar problemas con los puntos del nombre de host.

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

El curl de arriba se ejecuta en modo masivo (FlipbookID en blanco), así que su respuesta es:

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

En modo por flipbook (FlipbookID mayor que 0), el mensaje es, en cambio, { "Result": "OK", "Message": "CNAME removed from flipbook successfully" }. Si no pasas ni CNAME ni FlipbookID, la respuesta es { "Result": "ERROR", "Message": "CNAME or FlipbookID is required" }.

Errores posibles

• Clave de API ausente o no válida → HTTP 401. Esto devuelve una página HTML de "Unauthorized" sin formato — no hay cuerpo JSON. Comprueba que el encabezado X-Api-Key esté presente y sea correcto.
• flipbookId desconocido (o uno no perteneciente a tu clave), en Add CNAME → HTTP 200 con { "Result": "ERROR", "Message": "Item not found" }.
• Campo del cuerpo desconocido o mal escrito, en Add CNAME → HTTP 200 con { "Result": "ERROR", "Message": "Unknown field(s) '…'. Expected: …" }.
• Eliminar sin CNAME ni FlipbookID → { "Result": "ERROR", "Message": "CNAME or FlipbookID is required" }.

Notas

• Añadir un CNAME a través de la API solo persiste la vinculación — no verifica el DNS ni emite certificados. Añade y verifica el dominio en el panel web primero.
• El CNAME debe estar dentro del límite de CNAME de tu plan.