Automatiza la publicación de flipbooks en CI/CD con la CLI de FlipLink

Si un PDF vive en tu repositorio — un dosier de notas de versión, un catálogo de productos, un informe trimestral — entonces publicar su versión en flipbook debería formar parte del mismo build que produce el PDF. Sin panel, sin subida manual, sin "¿alguien se acordó de actualizar el flipbook?". La CLI de FlipLink está hecha justo para esto: se ejecuta en modo headless, se autentica desde una variable de entorno y devuelve códigos de salida limpios sobre los que un pipeline puede ramificarse.

Esta guía muestra un pipeline de CI/CD mínimo y neutral respecto a la plataforma que construye un PDF, crea el flipbook, lo publica y captura la URL en vivo.

Por qué ejecutar la publicación en CI

El panel es ideal para subidas puntuales. Un pipeline es mejor cuando el trabajo es repetible:

• Repetible y auditable — los mismos pasos se ejecutan siempre, registrados en el historial de tu CI.
• Sin panel, sin paso humano — nadie tiene que acordarse de subir nada después de una versión.
• Una sola fuente de la verdad — el PDF del repositorio es lo que se publica, así que el flipbook nunca se desvía del documento.
• Falla a la vista — si una publicación se rompe, el build se pone en rojo en lugar de publicar en silencio un flipbook desactualizado.

Esto es automatización en su sentido más puro: la CLI es el mismo motor que la API, así que todo lo que puedes hacer a mano lo puedes automatizar.

Paso 1: Guarda la clave de API como un secreto de CI

La CLI lee tu clave de la variable de entorno FLIPLINK_API_KEY en CI (su orden de resolución es variable de entorno → archivo de configuración → valor por defecto). Consigue una clave iniciando sesión en go.fliplink.me y abriendo la página Subscription.

Agrégala como un secreto en tu proveedor de CI — nunca la subas al repositorio, nunca la muestres en los logs. Luego exponla al job como una variable de entorno:

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

Una comprobación rápida de que la autenticación funciona antes de hacer el trabajo de verdad:

fliplink whoami

Si la clave falta o es incorrecta, esto sale con un código distinto de cero y tu pipeline se detiene pronto — justo lo que quieres.

Paso 2: Un pipeline mínimo

Aquí tienes un pipeline genérico y neutral respecto a la plataforma (pseudo-YAML — traslada las claves a la CI que uses). Para una versión específica de GitHub Actions activada por una versión, consulta el tutorial de GitHub Actions al publicar una versión.

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"

El flujo son cuatro comandos reales: construir el PDF, fliplink flipbook create, fliplink flipbook publish y luego fliplink flipbook share-link. Todo lo demás es la fontanería que aporta tu proveedor de CI.

Paso 3: Captura el ID y la URL del flipbook

El truco clave es --json. Cualquier comando de la CLI de FlipLink lo acepta e imprime JSON sin procesar, que canalizas hacia jq para extraer exactamente el campo que necesitas:

# 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')

Pasa $ID entre pasos como sea que tu CI comparta el estado — una variable de salida, un archivo de entorno o un artefacto guardado. Para más patrones de jq — filtrar listas, extraer campos anidados, construir tablas — consulta cómo crear scripts para la CLI con jq.

🚀

Prueba FlipLink Gratis

Convierte tu PDF en segundos. Sin registro, sin tarjeta de crédito — solo súbelo y listo.

Drop your PDF here or click to browse

Máximo 40MB

Los planes de pago desde $39 lo amplían a 150 MB.

Paso 4: Falla rápido según los códigos de salida

Un pipeline solo es tan bueno como su manejo de errores. La CLI te da tres códigos de salida sobre los que ramificar:

• 0 — éxito
• 1 — error de petición o HTTP (red defectuosa, fallo de autenticación 401, subida demasiado grande)
• 2 — error de aplicación (la API devolvió Result: ERROR, p. ej. un problema de validación)

La mayoría de los runners de CI detienen un paso automáticamente ante cualquier salida distinta de cero, que suele ser lo que quieres. Si necesitas reaccionar de forma distinta según el código, ramifica de manera explícita:

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

Ten en cuenta que la API de FlipLink devuelve los errores de negocio como HTTP 200 con Result: ERROR en el cuerpo — la CLI ya lo asigna al código de salida 2 por ti, así que una comprobación limpia del código de salida es suficiente. No tienes que analizar los códigos de estado a mano.

Paso 5: Notifica cuando todo salga bien

Una vez que tienes la URL capturada, el último paso es simplemente avisar a alguien. La URL es una cadena de texto sencilla, así que cualquier 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\"}"

Cambia la llamada a curl por un correo electrónico, un comentario en GitHub o una escritura en tu changelog — el patrón es el mismo. Como cada paso falla rápido, esta notificación solo se dispara cuando la publicación realmente tuvo éxito.

Para terminar

Ese es todo el patrón: guarda la clave como un secreto, instala la CLI, construye el PDF y luego create → publish → captura la URL con --json | jq, con los códigos de salida vigilando cada paso. Es lo bastante pequeño para incorporarlo a cualquier pipeline y lo bastante fiable para olvidarte de él — que es el sentido de la automatización e integraciones.

¿Nuevo en la CLI? Empieza con primeros pasos con la CLI de FlipLink y luego vuelve y conéctala a tu build.

Lecturas relacionadas

• Documentación de la CLI de FlipLink
• Primeros pasos con la CLI de FlipLink
• GitHub Actions: publica un flipbook al lanzar una versión
• Cómo crear scripts para la CLI de FlipLink con jq
• Automatización e integraciones
• Referencia de la API de FlipLink