Automatize a publicação de flipbooks no CI/CD com a CLI do FlipLink

Se um PDF mora no seu repositório — um deck de notas de versão, um catálogo de produtos, um relatório trimestral — então publicar a versão em flipbook dele deveria fazer parte do mesmo build que gera o PDF. Sem painel, sem upload manual, sem aquele "será que alguém lembrou de atualizar o flipbook?" A CLI do FlipLink foi feita exatamente para isso: ela roda headless, autentica a partir de uma variável de ambiente e retorna exit codes limpos nos quais um pipeline pode se ramificar.

Este guia mostra um pipeline de CI/CD mínimo e neutro em relação à plataforma, que gera um PDF, cria o flipbook, publica e captura a URL ao vivo.

Por que rodar a publicação no CI

O painel é ótimo para uploads pontuais. Um pipeline é melhor quando o trabalho é repetível:

• Repetível e auditável — os mesmos passos rodam todas as vezes, registrados no histórico do seu CI.
• Sem painel, sem etapa humana — ninguém precisa lembrar de fazer upload depois de um lançamento.
• Fonte única da verdade — o PDF no repositório é o que vai para produção, então o flipbook nunca fica fora de sincronia com o documento.
• Falhe alto — se uma publicação quebrar, o build fica vermelho em vez de publicar silenciosamente um flipbook desatualizado.

Isto é automação no sentido mais simples: a CLI é o mesmo motor que a API, então tudo o que você consegue fazer na mão dá para colocar em script.

Passo 1: Guarde a chave de API como um secret do CI

A CLI lê sua chave a partir da variável de ambiente FLIPLINK_API_KEY no CI (a ordem de resolução dela é variável de ambiente → arquivo de configuração → padrão). Obtenha uma chave fazendo login em go.fliplink.me e abrindo a página Subscription.

Adicione-a como um secret no seu provedor de CI — nunca faça commit dela, nunca a exiba nos logs. Depois exponha-a para o job como uma variável de ambiente:

# Provided by your CI's secret store, not hard-coded
export FLIPLINK_API_KEY="$CI_SECRET_FLIPLINK_API_KEY"

Um teste rápido de sanidade para confirmar que a autenticação funciona antes de fazer o trabalho de verdade:

fliplink whoami

Se a chave estiver faltando ou errada, isso sai com código diferente de zero e seu pipeline para cedo — exatamente o que você quer.

Passo 2: Um pipeline mínimo

Aqui está um pipeline genérico e neutro em relação à plataforma (pseudo-YAML — mapeie as chaves para qualquer CI que você usar). Para uma versão específica do GitHub Actions acionada por release, veja o passo a passo GitHub Actions on release.

pipeline:
  publish-flipbook:
    image: node:20
    secrets:
      - FLIPLINK_API_KEY        # injected from the CI secret store
    steps:
      - name: Install the CLI
        run: npm install -g fliplink-cli

      - name: Build the PDF
        run: ./scripts/build-report.sh   # your build that emits ./dist/report.pdf

      - name: Verify auth
        run: fliplink whoami

      - name: Create the flipbook
        run: |
          ID=$(fliplink flipbook create ./dist/report.pdf \
                 --title "Quarterly Report" --name quarterly \
                 --json | jq -r '.ID')
          echo "FLIPBOOK_ID=$ID" >> "$PIPELINE_ENV"

      - name: Publish the flipbook
        run: fliplink flipbook publish "$FLIPBOOK_ID"

      - name: Capture the share URL
        run: |
          URL=$(fliplink flipbook share-link "$FLIPBOOK_ID" \
                  --json | jq -r '.URL')
          echo "Published: $URL"

O fluxo são quatro comandos de verdade: gere o PDF, fliplink flipbook create, fliplink flipbook publish e então fliplink flipbook share-link. Todo o resto é encanamento que seu provedor de CI fornece.

Passo 3: Capture o ID e a URL do flipbook

O truque principal é --json. Qualquer comando da CLI do FlipLink aceita esse parâmetro e imprime JSON puro, que você canaliza para o jq a fim de extrair exatamente o campo de que precisa:

# Create and grab the new flipbook's ID
ID=$(fliplink flipbook create ./dist/report.pdf \
       --title "Quarterly Report" --name quarterly \
       --json | jq -r '.ID')

# Publish it
fliplink flipbook publish "$ID"

# Grab the public share URL to post in Slack, an email, or a release note
URL=$(fliplink flipbook share-link "$ID" --json | jq -r '.URL')

Passe o $ID entre os passos do jeito que seu CI compartilha estado — uma variável de saída, um arquivo de ambiente ou um artefato gravado. Para mais padrões de jq — filtrar listas, extrair campos aninhados, montar tabelas — veja scripting the CLI with jq.

Experimente o FlipLink Grátis

Converta seu PDF em segundos. Sem cadastro, sem cartão de crédito — basta enviar o arquivo.

Drop your PDF here or click to browse

Máx 40MB

Os planos pagos a partir de $39 aumentam esse limite para 150 MB.

Passo 4: Falhe rápido com os exit codes

Um pipeline é tão bom quanto seu tratamento de erros. A CLI te dá três exit codes nos quais se ramificar:

• 0 — sucesso
• 1 — erro de requisição ou HTTP (rede ruim, falha de autenticação 401, upload acima do tamanho permitido)
• 2 — erro de aplicação (a API retornou Result: ERROR, por exemplo, um problema de validação)

A maioria dos runners de CI para um passo automaticamente em qualquer saída diferente de zero, que costuma ser o que você quer. Se você precisa reagir de forma diferente por código, ramifique explicitamente:

set -euo pipefail

if fliplink flipbook publish "$ID" --json; then
  echo "Published OK"
else
  code=$?
  if [ "$code" -eq 2 ]; then
    echo "FlipLink rejected the request (application error)" >&2
  else
    echo "Request/HTTP error talking to FlipLink" >&2
  fi
  exit "$code"
fi

Repare que a API do FlipLink retorna erros de negócio como HTTP 200 com Result: ERROR no corpo — a CLI já mapeia isso para o exit code 2 para você, então uma verificação limpa de exit code é suficiente. Você não precisa interpretar status codes na mão.

Passo 5: Notifique no sucesso

Depois de ter a URL capturada, o último passo é só avisar alguém. A URL é uma string simples, então qualquer notificador funciona:

URL=$(fliplink flipbook share-link "$ID" --json | jq -r '.URL')

curl -X POST "$SLACK_WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d "{\"text\": \"New flipbook published: $URL\"}"

Troque a chamada curl por um e-mail, um comentário no GitHub ou uma escrita no seu changelog — o padrão é o mesmo. Como cada passo falha rápido, essa notificação só dispara quando a publicação realmente deu certo.

Para finalizar

Esse é o padrão inteiro: guarde a chave como um secret, instale a CLI, gere o PDF e então create → publish → capture a URL com --json | jq, com exit codes protegendo cada passo. É pequeno o bastante para encaixar em qualquer pipeline e confiável o bastante para esquecer dele — que é justamente o ponto da automação e integrações.

Novo na CLI? Comece com getting started with the FlipLink CLI e depois volte e conecte tudo no seu build.

Leituras relacionadas

• Documentação da CLI do FlipLink
• Primeiros passos com a CLI do FlipLink
• GitHub Actions: publique um flipbook no release
• Como criar scripts da CLI do FlipLink com jq
• Automação e integrações
• Referência da API do FlipLink