Vender un flipbook y consultar las ventas

Qué puedes hacer

Estos cinco endpoints cubren todo el ciclo de vida de la venta de un flipbook y del seguimiento de lo que genera:

• Configurar la venta — fija el precio, la moneda y si el flipbook está a la venta.
• Personalizar la página de checkout — títulos, texto de los botones y color de los botones.
• Elegir una pasarela de pago — selecciona la pasarela y define sus credenciales.
• Registrar una compra — anota una venta completada realizada mediante tu propio flujo de pago.
• Consultar tus ventas — lista los registros de ventas completadas (o de carritos abandonados), con paginación y exportación a CSV.

Antes de empezar

• Una clave de API — se envía en el encabezado X-Api-Key, o como Authorization: Bearer YOUR_API_KEY, en cada solicitud.
• Todas las solicitudes van a la URL base https://go.fliplink.me.
• Todos los endpoints excepto List Sales toman el ID numérico del flipbook como parámetro de ruta {flipbookId} — por ejemplo .../set-sale-settings/96216.
• Los endpoints de escritura (Set Sale Settings, Set Sale Page Text, Set Sale Gateway, Set Flipbook Purchase) envían su cuerpo como campos form-urlencoded (NO JSON).

Configurar la venta

PUT /api/set-sale-settings/{flipbookId} configura la venta del flipbook (precio, moneda, opciones). Activar el modo de venta habilita automáticamente la verificación por correo y hace que el correo del lead sea obligatorio.

Campos clave:

• SaleAmount — el precio en unidades enteras de la moneda (p. ej. dólares), con decimales permitidos. 9.99 significa $9.99 y 1000 significa $1,000 — NO es un valor en centavos/unidades menores.
• SaleCurr — el código de moneda (por defecto usd). Elige un código válido de /api/list-currencies.

curl -X PUT 'https://go.fliplink.me/api/set-sale-settings/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'IsForSale=true' \
  --data-urlencode 'SaleCurr=usd' \
  --data-urlencode 'SaleAmount=9.99'

Respuesta:

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

Personalizar la página de checkout

PUT /api/set-sale-page-text/{flipbookId} define el texto de marketing que se muestra en la página de venta / checkout del flipbook.

curl -X PUT 'https://go.fliplink.me/api/set-sale-page-text/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'SalePageTitle=' \
  --data-urlencode 'SaleAccessPageTitle=' \
  --data-urlencode 'SalePurchaseButtonText=' \
  --data-urlencode 'SaleButtonText=' \
  --data-urlencode 'SaleAccessButtonText=' \
  --data-urlencode 'SaleButtonColor='

Respuesta:

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

Elegir una pasarela de pago

PUT /api/set-sale-gateway/{flipbookId} selecciona y configura la pasarela de pago que se usa al vender este flipbook.

curl -X PUT 'https://go.fliplink.me/api/set-sale-gateway/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'SaleGatewayName=' \
  --data-urlencode 'SaleGatewayKey=' \
  --data-urlencode 'SaleGatewaySecret='

Respuesta:

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

Registrar una compra

POST /api/set-flipbook-purchase/{flipbookId} registra una venta (compra) completada de un flipbook — úsalo para anotar compras realizadas mediante tu propio flujo de pago, sin pasar por el checkout de Stripe de FlipLink. Envía el Email del comprador y tu referencia de pasarela de pago PaymentRef (para Stripe, el ID del PaymentIntent, pi_...); ambos son obligatorios. NO envíes Amount/Currency — esos se derivan en el servidor a partir de tu referencia de pago.

curl -X POST 'https://go.fliplink.me/api/set-flipbook-purchase/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'Email=customer@example.com' \
  --data-urlencode 'PaymentRef=pi_3O1234567890abcdef'

Respuesta:

{
  "Result": "OK",
  "Message": "Purchase recorded successfully"
}

Consultar tus ventas

GET /api/list-sales lista los registros de venta/compra de tus flipbooks (correo del comprador, flipbook, importe, fecha) más las definiciones de columna de la tabla de ventas. Admite paginación y exportación a CSV mediante IsDownload. Define IsAbandoned=true para devolver las ventas de carrito abandonado en lugar de las ventas completadas.

curl -X GET 'https://go.fliplink.me/api/list-sales?ItemIDs=&SearchText=&PageNo=1&Offset=0&IsDownload=true&IsAbandoned=false' \
  -H 'X-Api-Key: YOUR_API_KEY'

Respuesta:

{
  "Result": "OK",
  "Items": [],
  "Columns": [
    {
      "ID": 1,
      "data": "ID",
      "title": "ID",
      "type": "numeric",
      "hidden": true,
      "readOnly": true,
      "defaultValue": "",
      "source": "",
      "width": 0,
      "backgroundColor": "",
      "align": "left"
    }
  ],
  "TotalRecordCount": 0
}

Errores posibles

• Clave de API ausente o no válida → HTTP 401. Esto devuelve una página HTML de "Unauthorized" sin formato sin formato — no hay cuerpo JSON. Comprueba que el encabezado X-Api-Key esté presente y sea correcto.
• flipbookId desconocido (o uno que no pertenece a tu clave) → HTTP 200 con { "Result": "ERROR", "Message": "Item not found" }. Esto aplica a Set Sale Settings, Set Sale Page Text, Set Sale Gateway y Set Flipbook Purchase.
• Campo del cuerpo desconocido o mal escrito → HTTP 200 con { "Result": "ERROR", "Message": "Unknown field(s) '…'. Expected: …" }.
• Falta un campo obligatorio de la compra (Set Flipbook Purchase) → { "Result": "ERROR", "Message": "Email is required." } o { "Result": "ERROR", "Message": "PaymentRef is required." }.

Notas

• Activar el modo de venta (IsForSale) mediante Set Sale Settings habilita automáticamente la verificación por correo y hace que el correo del lead sea obligatorio.
• Set Flipbook Purchase es para compras realizadas mediante tu propio flujo de pago — te permite anotar una venta sin pasar por el checkout de Stripe de FlipLink.