Настройка собственного домена (CNAME)

Что можно сделать

Собственный домен (CNAME) позволяет отдавать флипбук с принадлежащего вам хоста, например docs.example.com. После того как домен добавлен и подтверждён в веб-панели управления, эти три эндпоинта позволяют управлять привязкой между этим доменом и вашими флипбуками через API:

• Добавить привязку CNAME к флипбуку.
• Получить список всех CNAME в вашем аккаунте с флипбуками, к которым привязан каждый из них.
• Удалить привязку CNAME с одного флипбука или со всех сразу.

Перед началом

• API-ключ — передаётся в заголовке X-Api-Key (или как Authorization: Bearer YOUR_API_KEY) в каждом запросе.
• Все запросы идут на базовый URL https://go.fliplink.me.
• Add CNAME нацелен на конкретный флипбук через сегмент пути {flipbookId} — числовой ID, возвращаемый из create-by-file / create-by-url или из list. List и Delete не используют параметр пути {flipbookId}.
• CNAME должен уже существовать и быть активирован в вашем аккаунте — добавлен и подтверждён через веб-панель управления, которая настраивает DNS и SSL. API лишь сохраняет привязку; он не проверяет DNS и не выпускает сертификаты.
• Для Add CNAME тело запроса — form-urlencoded (не JSON).

Добавление CNAME к флипбуку

Привязывает уже активированный собственный домен к флипбуку. Передавайте полный хост как CNAME. IsCloudflare необязателен и по умолчанию равен 0; передайте 1, если ваш DNS проксируется через 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'

Ответ:

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

Если домен не был предварительно активирован в вашем аккаунте, запрос отклоняется с сообщением: Please add CNAME <domain> to your account using the web dashboard. Only activated CNAMEs are allowed to be created via API.

Список ваших CNAME

Возвращает все собственные CNAME вызывающей стороны. Каждый элемент сообщает хост, количество активных флипбуков, привязанных к нему (Documents), и список ID этих активных флипбуков (FlipbookIDs).

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

Ответ:

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

Удаление привязки CNAME

Удаляет привязку собственного домена с одного или всех ваших флипбуков. Есть два режима:

• Массовый (по умолчанию): передайте CNAME=<host> и оставьте FlipbookID пустым — удаляет этот CNAME со всех флипбуков, которыми вы владеете.
• По флипбуку: передайте FlipbookID=<id> (больше 0) — CNAME определяется по этому флипбуку и удаляется только с него.

Передавайте CNAME как query-параметр (а не сегмент URL), чтобы избежать проблем с точками в хосте.

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

Приведённый выше curl работает в массовом режиме (FlipbookID оставлен пустым), поэтому его ответ такой:

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

В режиме по флипбуку (FlipbookID больше 0) сообщение вместо этого — { "Result": "OK", "Message": "CNAME removed from flipbook successfully" }. Если вы не передадите ни CNAME, ни FlipbookID, ответ будет { "Result": "ERROR", "Message": "CNAME or FlipbookID is required" }.

Возможные ошибки

• Отсутствующий или неверный API-ключ → HTTP 401. Возвращается обычная HTML-страница Unauthorized — тела JSON нет. Проверьте, что заголовок X-Api-Key присутствует и указан верно.
• Неизвестный flipbookId (или не принадлежащий вашему ключу), в Add CNAME → HTTP 200 с { "Result": "ERROR", "Message": "Item not found" }.
• Неизвестное поле тела запроса или опечатка в нём, в Add CNAME → HTTP 200 с { "Result": "ERROR", "Message": "Unknown field(s) '…'. Expected: …" }.
• Удаление без CNAME и без FlipbookID → { "Result": "ERROR", "Message": "CNAME or FlipbookID is required" }.

Примечания

• Добавление CNAME через API лишь сохраняет привязку — оно не проверяет DNS и не выпускает сертификаты. Сначала добавьте и подтвердите домен в веб-панели управления.
• CNAME должен укладываться в лимит CNAME вашего тарифа.