Configurer un domaine personnalisé (CNAME)

Ce que tu peux faire

Un domaine personnalisé (CNAME) permet de servir un flipbook depuis un nom d'hôte que tu possèdes, comme docs.example.com. Une fois qu'un domaine a été ajouté et vérifié dans le tableau de bord web, ces trois endpoints te permettent de gérer l'association entre ce domaine et tes flipbooks depuis l'API :

• Ajouter une association CNAME à un flipbook.
• Lister tous les CNAME de ton compte, avec les flipbooks auxquels chacun est associé.
• Supprimer une association CNAME d'un seul flipbook ou de tous à la fois.

Avant de commencer

• Une clé d'API — envoyée dans l'en-tête X-Api-Key (ou sous la forme Authorization: Bearer YOUR_API_KEY) sur chaque requête.
• Toutes les requêtes utilisent l'URL de base https://go.fliplink.me.
• Add CNAME cible un flipbook précis via le segment de chemin {flipbookId} — l'ID numérique renvoyé par create-by-file / create-by-url ou par list. List et Delete n'utilisent pas de paramètre de chemin {flipbookId}.
• Le CNAME doit déjà exister et être activé sur ton compte — ajouté et vérifié via le tableau de bord web, qui provisionne le DNS et le SSL. L'API ne fait que persister l'association ; elle ne vérifie pas le DNS et n'émet pas de certificats.
• Pour Add CNAME, le corps de la requête est form-urlencoded (pas du JSON).

Ajouter un CNAME à un flipbook

Associe un domaine personnalisé déjà activé à un flipbook. Passe le nom d'hôte complet dans CNAME. IsCloudflare est optionnel et vaut 0 par défaut ; passe 1 si ton DNS est derrière le 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'

Réponse :

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

Si le domaine n'a pas d'abord été activé sur ton compte, la requête est rejetée avec : Please add CNAME <domain> to your account using the web dashboard. Only activated CNAMEs are allowed to be created via API.

Lister tes CNAME

Renvoie tous les CNAME personnalisés de l'appelant. Chaque élément indique le nom d'hôte, le nombre de flipbooks actifs qui lui sont associés (Documents) et la liste des IDs de ces flipbooks actifs (FlipbookIDs).

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

Réponse :

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

Supprimer une association CNAME

Supprime une association de domaine personnalisé d'un seul ou de tous tes flipbooks. Il y a deux modes :

• En masse (par défaut) : passe CNAME=<host> et laisse FlipbookID vide — supprime ce CNAME de tous les flipbooks que tu possèdes.
• Par flipbook : passe FlipbookID=<id> (supérieur à 0) — le CNAME est recherché à partir de ce flipbook et supprimé de celui-ci uniquement.

Passe le CNAME en paramètre de requête (pas en segment d'URL) pour éviter les problèmes liés aux points dans le nom d'hôte.

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

Le curl ci-dessus s'exécute en mode masse (FlipbookID laissé vide), donc sa réponse est :

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

En mode par flipbook (FlipbookID supérieur à 0), le message est plutôt { "Result": "OK", "Message": "CNAME removed from flipbook successfully" }. Si tu ne passes ni CNAME ni FlipbookID, la réponse est { "Result": "ERROR", "Message": "CNAME or FlipbookID is required" }.

Erreurs possibles

• Clé d'API manquante ou invalide → HTTP 401. Renvoie une simple page HTML « Unauthorized » — il n'y a pas de corps JSON. Vérifie que l'en-tête X-Api-Key est présent et correct.
• flipbookId inconnu (ou non détenu par ta clé), sur Add CNAME → HTTP 200 avec { "Result": "ERROR", "Message": "Item not found" }.
• Champ de corps inconnu ou mal orthographié, sur Add CNAME → HTTP 200 avec { "Result": "ERROR", "Message": "Unknown field(s) '…'. Expected: …" }.
• Suppression sans CNAME ni FlipbookID → { "Result": "ERROR", "Message": "CNAME or FlipbookID is required" }.

Notes

• Ajouter un CNAME via l'API ne fait que persister l'association — cela ne vérifie pas le DNS et n'émet pas de certificats. Ajoute et vérifie d'abord le domaine dans le tableau de bord web.
• Le CNAME doit respecter la limite de CNAME de ton offre.