Ir para o conteúdo

ClickBank API Reference

A API REST do ClickBank está mapeada na pasta docs/clickbank-api/ do repositório como esquemas OpenAPI JSON e é consumida pelo pacote @brandvelia/integrations. Esta página detalha como a Brandvelia utiliza essas definições oficiais para sincronização de catálogo, pedidos e relatórios analíticos.

Esquemas Disponíveis

Arquivo API Versão / Endpoint Base
products-v2.json Produtos & Funis de Venda v2 /v2/sellers/{accountName}
orders-v2.json Pedidos & Reembolsos v2 /v2/orders
analytics-v1.json Analytics & Assinaturas v1 /rest/1.3/analytics

Products API (products-v2)

Caminho base: GET /v2/sellers/{accountName} (padrão de accountName: [a-zA-Z\d]{5,10}).

Operações de Leitura

  • GET /products → searchProducts — lista produtos com title, urlAlias, status (DRAFT, PENDING_APPROVAL, UNDER_REVIEW, ACTION_REQUIRED, APPROVED, DISAPPROVED, INACTIVE), skus[], versions[], active (boolean).
  • GET /categories → getSkuCategories.
  • GET /products/{productId} → getProduct; GET /products/{productId}/offerSplit → getProductOfferSplit.
  • GET /funnels, /funnels/{funnelId}/upsellFlows, /orderBumps, /itemSets, /customTexts, /images, /compliance/documents.
  • GET /shipping/regions → getShippingRegions.

Operações de Modificação

  • POST /products, POST /products/{productId}/sku → createProduct / createSku.
  • POST /funnels, /upsellFlows, /orderBumps, /itemSets, /customTexts, /images.
  • PUT /status (action: SUBMIT_FOR_APPROVAL, REVERT_TO_DRAFT) → updateProductStatus.
  • Todos os recursos suportam operações de atualização e exclusão (DELETE).

Tipos Principais

  • MonetaryAmount — { amount: number, currency: string } (ISO 4217, ex.: USD).
  • Subscription — frequencyType/offsetType (YEAR, MONTH, WEEK, DAY), recurrences, offset, notificationOffset.

Orders API (orders-v2)

Caminho base: GET /v2/orders.

Operações de Leitura

  • GET /orders (getOrders) — filtros: seller, startDate (obrigatório), transactionType (enum), funnelId, skuId, customerEmail, customerLastName, page, size, sort.
  • GET /orders/{receipt} → getOrder.

Reembolsos e Atualizações

  • POST /orders/{receipt}/transactions/refund → processRefund (RefundRequest: amount, refundType (FULL, PARTIAL_AMOUNT), reason).
  • PUT /orders/{receipt}/customer/shippingCustomer → updateOrderCustomerInfo.

Tipos Principais

  • Transaction — type (SALE, BILL, RFND, CGBK, TEST*), amount, taxAmount, details, itemSets[].
  • Receipt — chave do pedido em todas as operações (ex.: ABCD1234).
  • Payment → Card (método de pagamento), com marketingConsent.
  • Visão consolidada do pedido — billed, shipping, tax, fee, payouts por item.

Analytics API (analytics-v1)

Caminho base: GET /rest/1.3/analytics/{role}/{dimension} (role: vendor, affiliate; padrão de account: ^[a-z0-9]{5,10}$).

Sumário vs. Detalhe

  • GET .../summary → getAnalyticsData.
  • GET .../{dimension} → getAnalyticsData_1.

Dimensões de Consulta

affiliate, vendor, vendor_category, customer_currency, customer_country, customer_province, customer_language, product_sku, tracking_id, vendor_product_sku.

Detalhe de Assinaturas e Recorrência

/subscription/details/* — nextpmtdate, canceldate, startdate, cancelthirty, compsixty, trends, details/status, details. Enum de status: active, completed, canceled, retry_payment, request_new_card.

Campos da Linha de Assinatura

affNickName, chargebackAmount, chargebackCount, countryCode, currencyCode, customerDisplayName, email, frequency, ftxnId, futurePaymentsCount, initialSaleAmount, initialSaleCount, receipt, refundAmount, refundCount, returnCount, status, subCancelDate, subEndDate, subValue.

Como a Brandvelia usa a API ClickBank

  • Marketplace Feed: Popula a esteira offers_src → marketplaces → snapshots.
  • LinkBuilder: Constrói HopLinks com parâmetros padronizados (buildClickBankLink).
  • Webhooks INS 8.0: Decodifica eventos de pedidos/conversões em tempo real e os atribui a visitas via extclid.
  • QuickStats: Reconcilia relatórios diários de vendas e estornos com a verdade de caixa.
  • Opportunity Score: Pontua produtos no Radar.

Os esquemas de API aqui documentados servem como referência estrita de integração; as definições de métricas financeiras da Brandvelia (receita líquida, lucro real e ROAS) são sempre calculadas de forma determinística em SQL.