Configurar um domínio personalizado (CNAME)

O que você pode fazer

Um domínio personalizado (CNAME) permite que um flipbook seja servido a partir de um hostname que você possui, como docs.example.com. Depois que um domínio é adicionado e verificado no painel web, estes três endpoints permitem gerenciar a vinculação entre esse domínio e seus flipbooks pela API:

• Add — adicione uma vinculação de CNAME a um flipbook.
• List — liste todos os CNAMEs da sua conta, com os flipbooks a que cada um está vinculado.
• Delete — remova a vinculação de um CNAME de um flipbook ou de todos de uma vez.

Antes de começar

• Uma chave de API — enviada como cabeçalho X-Api-Key (ou como Authorization: Bearer YOUR_API_KEY) em toda requisição.
• Todas as requisições vão para a URL base https://go.fliplink.me.
• Add CNAME atua sobre um flipbook específico pelo segmento de caminho {flipbookId} — o ID numérico retornado por create-by-file / create-by-url ou por list. List e Delete não usam parâmetro de caminho {flipbookId}.
• O CNAME precisa já existir e estar ativado na sua conta — adicionado e verificado pelo painel web, que provisiona o DNS e o SSL. A API apenas persiste a vinculação; ela não verifica DNS nem emite certificados.
• Para o Add CNAME, o corpo da requisição é form-urlencoded (não JSON).

Adicione um CNAME a um flipbook

Vincula um domínio personalizado já ativado a um flipbook. Passe o hostname completo como CNAME. IsCloudflare é opcional e tem padrão 0; passe 1 se o seu DNS estiver por trás do proxy da 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'

Resposta:

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

Se o domínio não tiver sido ativado antes na sua conta, a requisição é rejeitada com: Please add CNAME <domain> to your account using the web dashboard. Only activated CNAMEs are allowed to be created via API.

Liste seus CNAMEs

Retorna todos os CNAMEs personalizados de quem chama. Cada item informa o hostname, a contagem de flipbooks ativos vinculados a ele (Documents) e a lista dos IDs desses flipbooks ativos (FlipbookIDs).

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

Resposta:

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

Remova uma vinculação de CNAME

Remove a vinculação de um domínio personalizado de um flipbook ou de todos. Há dois modos:

• Em massa (padrão): passe CNAME=<host> e deixe FlipbookID em branco — remove esse CNAME de todos os flipbooks que você possui.
• Por flipbook: passe FlipbookID=<id> (maior que 0) — o CNAME é buscado a partir desse flipbook e removido só dele.

Passe o CNAME como parâmetro de query (não como segmento de URL) para evitar problemas com os pontos do hostname.

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

O curl acima roda no modo em massa (FlipbookID em branco), então a resposta é:

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

No modo por flipbook (FlipbookID maior que 0), a mensagem é { "Result": "OK", "Message": "CNAME removed from flipbook successfully" }. Se você não passar nem CNAME nem FlipbookID, a resposta é { "Result": "ERROR", "Message": "CNAME or FlipbookID is required" }.

Erros possíveis

• Chave de API ausente ou inválida → HTTP 401. Isso retorna uma página HTML de Unauthorized simples — não há corpo JSON. Confira se o cabeçalho X-Api-Key está presente e correto.
• flipbookId desconhecido (ou que não pertence à sua chave), no Add CNAME → HTTP 200 com { "Result": "ERROR", "Message": "Item not found" }.
• Campo do corpo desconhecido ou digitado errado, no Add CNAME → HTTP 200 com { "Result": "ERROR", "Message": "Unknown field(s) '…'. Expected: …" }.
• Excluir sem CNAME nem FlipbookID → { "Result": "ERROR", "Message": "CNAME or FlipbookID is required" }.

Notas

• Adicionar um CNAME pela API apenas persiste a vinculação — não verifica DNS nem emite certificados. Adicione e verifique o domínio no painel web primeiro.
• O CNAME precisa estar dentro do limite de CNAMEs do seu plano.