Vender um flipbook e ler as vendas

O que você pode fazer

Estes cinco endpoints cobrem todo o ciclo de vida de vender um flipbook e acompanhar o que ele rende:

• Configurar a venda — defina preço, moeda e se o flipbook está à venda.
• Personalizar a página de checkout — títulos, texto do botão e cor do botão.
• Escolher um gateway de pagamento — selecione o gateway e defina as credenciais dele.
• Registrar uma compra — registre uma venda concluída feita pelo seu próprio fluxo de pagamento.
• Ler suas vendas — liste os registros de vendas concluídas (ou de carrinho abandonado), com paginação e exportação em CSV.

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.
• Todo endpoint, exceto o List Sales, recebe o ID numérico do flipbook como parâmetro de caminho {flipbookId} — por exemplo .../set-sale-settings/96216.
• Os endpoints de escrita (Set Sale Settings, Set Sale Page Text, Set Sale Gateway, Set Flipbook Purchase) enviam o corpo como campos form-urlencoded (NÃO JSON).

Configure a venda

PUT /api/set-sale-settings/{flipbookId} configura a venda do flipbook (preço, moeda, opções). Ativar o modo de venda ativa automaticamente a verificação de e-mail e torna o e-mail do lead obrigatório.

Campos principais:

• SaleAmount — o preço em unidades inteiras da moeda (por exemplo, dólares), com decimais permitidos. 9.99 significa $9.99 e 1000 significa $1,000 — este NÃO é um valor em centavos/unidades menores.
• SaleCurr — o código da moeda (padrão usd). Escolha um 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'

Resposta:

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

Personalize a página de checkout

PUT /api/set-sale-page-text/{flipbookId} define o texto de marketing exibido na página de venda / checkout do 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='

Resposta:

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

Escolha um gateway de pagamento

PUT /api/set-sale-gateway/{flipbookId} seleciona e configura o gateway de pagamento usado ao 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='

Resposta:

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

Registre uma compra

POST /api/set-flipbook-purchase/{flipbookId} registra uma venda (compra) concluída de flipbook — use-o para registrar compras feitas pelo seu próprio fluxo de pagamento, sem passar pelo checkout da Stripe do FlipLink. Envie o Email do comprador e a referência PaymentRef do seu gateway de pagamento (para a Stripe, o ID do PaymentIntent, pi_...); ambos são obrigatórios. NÃO envie Amount/Currency — esses são derivados no servidor a partir da sua referência de pagamento.

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'

Resposta:

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

Leia suas vendas

GET /api/list-sales lista os registros de venda/compra dos seus flipbooks (e-mail do comprador, flipbook, valor, data) mais as definições de coluna da tabela de vendas. Ele aceita paginação e exportação em CSV via IsDownload. Defina IsAbandoned=true para retornar vendas de carrinho abandonado em vez de vendas concluídas.

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'

Resposta:

{
  "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
}

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) → HTTP 200 com { "Result": "ERROR", "Message": "Item not found" }. Isso vale para Set Sale Settings, Set Sale Page Text, Set Sale Gateway e Set Flipbook Purchase.
• Campo do corpo desconhecido ou digitado errado → HTTP 200 com { "Result": "ERROR", "Message": "Unknown field(s) '…'. Expected: …" }.
• Campo obrigatório de compra ausente (Set Flipbook Purchase) → { "Result": "ERROR", "Message": "Email is required." } ou { "Result": "ERROR", "Message": "PaymentRef is required." }.

Notas

• Ativar o modo de venda (IsForSale) via Set Sale Settings ativa automaticamente a verificação de e-mail e torna o e-mail do lead obrigatório.
• O Set Flipbook Purchase é para compras feitas pelo seu próprio fluxo de pagamento — ele permite registrar uma venda sem passar pelo checkout da Stripe do FlipLink.