Clube Bisdocs Produção

Guia de integração

Como uma ticketeira oferece o Clube Bis na página de confirmação de compra. A integração é feita uma vez por plataforma e vale para todos os produtores dela.

O comprador vê um banner (com um modal) na confirmação. O botão abre a página de adesão do Bis numa aba nova, onde ele confere os dados, aceita os Termos e paga R$ 1 no primeiro mês (Apple Pay, Google Pay, cartão de crédito ou Pix Automático) (depois R$ 9,99/mês). Em troca ganha R$ 20 de crédito na sua próxima compra na ticketeira e concorre a R$ 10 mil todo mês.

O Bis é o lojista da cobrança: o nome Bis aparece na fatura e o estorno é responsabilidade do Bis. O comprador autoriza um pagamento novo ao Bis: Apple Pay, Google Pay, cartão de crédito (digitado num campo hospedado pelo gateway) ou Pix Automático. O cartão do checkout da ticketeira não é reaproveitado e o Bis nunca recebe número de cartão nem CVV: os dados do cartão vão direto para o gateway, que devolve só um token.

Escolha o modo

Sem código Assinado
Onde mexe Uma tag no site (ou no Google Tag Manager) Seu servidor + a página de confirmação
Quem garante que a compra existe Você, depois, ao confirmar o pedido Seu servidor, na hora (HMAC)
Dados do comprador O comprador digita na página do Bis Vêm pré-preenchidos (adesão em um toque)
Crédito, número da sorte e bônus Travados até a confirmação do pedido Liberados normalmente

Recomendação: comece sem código para medir e passe para o assinado (ou pelo menos para a confirmação de pedidos em lote) antes de escalar.

Os dois modos usam o mesmo banner, a mesma página de adesão e o mesmo pagamento.

Integração sem código

Uma linha no site inteiro. O script descobre sozinho quando a compra foi aprovada: nada de servidor, nada de segredo no seu código.

html
<script src="https://widget.clubebis.com/bis-auto.js" data-parceiro="prt_suaticketeira" async></script>

Também funciona como tag HTML personalizada no Google Tag Manager, com o acionador "All Pages". Se a tag aparecer duas vezes (site e GTM), a segunda é ignorada.

Três gatilhos

O atributo data-gatilho decide quando a oferta aparece. O resto é igual nos três.

Gatilho Quando mostra Use quando
auto (padrão sem data-pedido) Quando as regras de detecção reconhecem a página de confirmação A tag está no site todo ou no GTM
api Quando a sua página chama Bis("show", {…}) SPA, ou o checkout já sabe o número do pedido
carregar (padrão com data-pedido ou data-sessao) Assim que o script carrega, onde a tag está A tag fica só na página de confirmação

Opções de Bis("show", {…}) e os atributos equivalentes na tag:

Opção Atributo O que é
pedido data-pedido Número do pedido: 3 a 64 caracteres de A-Z a-z 0-9 . _ / # -
valor data-valor Valor do pedido em centavos (informativo)
sessao data-sessao Um sessionToken do modo assinado, no lugar de pedido
alvo data-alvo Seletor CSS (ou elemento) onde entra o banner. Sem ele, só o modal
modal data-modal="0" false desliga o modal

Cada pedido aparece uma vez por carregamento da página. Os gatilhos api e carregar não usam as regras de detecção.

Regras de detecção

No gatilho auto, o script lê as regras públicas do parceiro em GET /v1/partners/{id}/auto-config. As regras são configuradas pelo Bis com você durante a integração (envie a URL e um print da sua página de confirmação).

Como funciona:

  1. O script acompanha a navegação (incluindo pushState e popstate de SPAs) e, só enquanto a URL bate, observa a página.
  2. Quando aparecem a URL e o marcador (por exemplo /checkout/* e o texto "pagamento aprovado"), ele lê o número do pedido do texto da página, da URL ou do dataLayer.
  3. Cria uma sessão não assinada (POST /v1/sessions/auto), que confere se a página está num dos seus domínios permitidos.
  4. Monta o banner logo depois da âncora configurada (por exemplo, depois de "Ingressos adquiridos"), uma vez por pedido.

O script nunca lê campos de formulário (input, textarea, select), conteúdo editável, cookies ou o armazenamento da página, e nunca lança erro na sua página. Se as regras não baterem, ele não faz nada.

Você pode ter um conjunto de regras ou uma lista de até 5 (por exemplo, uma por domínio). A primeira que detectar vence.

Campo Para quê
host Domínio da página (ou subdomínio). | separa alternativas. Sem ele, vale qualquer domínio permitido
urlPattern Caminho. * = um segmento, ** = qualquer coisa, | = alternativas
textMarker Texto visível na página (sem diferença de acento ou maiúscula)
selectorMarker Seletor CSS que precisa existir
dataLayerEvent Evento do window.dataLayer, ex.: purchase. Número = transaction_id, valor = value. Não depende de idioma nem de layout
orderRef.urlSegment Número tirado da URL (-1 = último segmento)
orderRef.selector / orderRef.label Número tirado de um elemento ou do texto depois de um rótulo
orderRef.pattern Expressão regular que o número precisa respeitar
amount.selector / amount.label Onde ler o valor em reais (opcional)
anchor.selector / anchor.text Onde montar o banner. || separa alternativas (ex.: .sucesso || main)
anchor.position after, before ou append

Exemplo:

json
{
  "urlPattern": "/checkout/*|/paycheckout/*",
  "textMarker": "pagamento aprovado",
  "orderRef": { "label": "Nº da transação", "pattern": "([A-Za-z0-9][A-Za-z0-9._/#-]{2,63})" },
  "anchor": { "text": "Ingressos adquiridos", "position": "after" }
}

O que você precisa fazer no modo sem código

  1. Pôr a tag no site todo (ou no GTM). Se a confirmação fica em outro domínio (ex.: pay.suaticketeira.com.br), a tag precisa estar lá também.
  2. Cadastrar os domínios permitidos no painel, em Configuração → Domínios autorizados para o script. Sem domínio cadastrado, o modo sem código fica desligado.
  3. Liberar a CSP da página (ver abaixo).
  4. Atualizar o aviso de privacidade para citar que a confirmação exibe uma oferta de parceiro (Clube Bis). O comprador digita os próprios dados na página do Bis: nenhum dado sai da sua página.
  5. Confirmar os pedidos (recomendado), para liberar os benefícios. Veja Confirmar pedidos.

Integração assinada

O seu servidor abre uma sessão para cada pedido aprovado e a página embute o widget com o token devolvido. O comprador chega à página do Bis com os dados preenchidos e adere em um toque.

1. Abrir a sessão (servidor)

Na aprovação do pedido, chame POST /v1/sessions assinando o corpo cru com o seu widgetSecret (HMAC-SHA256 em hex):

js
import { createHmac } from "node:crypto";

const BIS_API = "https://api.clubebis.com/v1";
const PARTNER_ID = "prt_suaticketeira";
const WIDGET_SECRET = process.env.BIS_WIDGET_SECRET; // só no servidor

export async function abrirSessaoBis(pedido) {
  const body = JSON.stringify({
    partnerId: PARTNER_ID,
    orderRef: pedido.ref,          // id único do pedido
    amount: pedido.totalCentavos,  // centavos
    category: pedido.categoria,    // opcional
    city: pedido.cidade,           // opcional
    buyer: {                       // opcional; com os quatro campos, adesão em um toque
      name: pedido.comprador.nome,
      email: pedido.comprador.email,
      phone: pedido.comprador.telefone,
      cpf: pedido.comprador.cpf,   // 11 dígitos
    },
  });
  const sig = createHmac("sha256", WIDGET_SECRET).update(body).digest("hex");
  const r = await fetch(`${BIS_API}/sessions`, {
    method: "POST",
    headers: { "content-type": "application/json", "X-Bis-Partner": PARTNER_ID, "X-Bis-Signature": sig },
    body,
  });
  if (!r.ok) throw new Error(`Bis ${r.status}`);
  return r.json(); // { sessionToken, show }
}

A chamada é idempotente por orderRef. Assine exatamente os bytes que você envia: re-serializar o JSON depois de assinar quebra a assinatura.

Envie os dados do comprador só com o consentimento dele, previsto no texto legal do seu checkout.

Amostragem do piloto. O Bis decide, de forma determinística por orderRef, se o pedido entra na amostra. Quando show vier false, não embuta o widget.

2. Embutir o widget (página)

Com show: true, passe o sessionToken para o script na página de confirmação:

html
<div id="bis-oferta"></div>
<script src="https://widget.clubebis.com/bis-auto.js"
        data-parceiro="prt_suaticketeira"
        data-sessao="SESSION_TOKEN_DO_SEU_SERVIDOR"
        data-alvo="#bis-oferta" async></script>

O sessionToken vale 30 minutos e serve só para aquele pedido. Ele é opaco (cifrado): os dados do comprador não ficam legíveis na página.

O padrão é o banner. Para usar o card, peça ao Bis: a troca vale para todas as páginas do parceiro.

O banner fica num shadow DOM fechado: o CSS da sua página não vaza para dentro dele, nem o dele para fora. Ele não precisa de 'unsafe-inline' na CSP.

  • Inline, no lugar da tag ou dentro de data-alvo: "Aproveite ainda mais. Ganhe R$ 20 de crédito para usar na sua próxima compra." com o botão Resgatar.
  • Modal, uma vez por pedido: "Sua compra foi concluída! Clique aqui para receber seu crédito de R$ 20 na sua próxima compra!" com o botão Receba R$ 20. Fecha no X, no Esc ou com um clique fora.

O valor do crédito e o nome do parceiro vêm da API. Os textos podem variar por teste A/B.

Card (iframe)

Com display: "card", o script cria um iframe isolado (sandbox, allow="payment *") que só aparece quando há oferta. A adesão acontece dentro da sua página. Se a CSP não liberar connect-src para a API do Bis, o script cai sozinho no modo card.

CSP da página de confirmação

Modo O que liberar
Banner script-src https://widget.clubebis.com e connect-src https://api.clubebis.com. Não precisa de frame-src nem de payment: o pagamento acontece na aba do Bis
Card script-src e frame-src https://widget.clubebis.com, mais Permissions-Policy: payment=(self "https://widget.clubebis.com") para Apple Pay e Google Pay no iframe (cartão e Pix funcionam sem isso)

Com GTM, o GTM também precisa de script-src para o domínio do widget.

Passagem para a página do Bis

O botão do banner abre a página de adesão do Bis numa aba nova:

  1. O clique abre a aba na hora (para o navegador não bloquear) e só então pede um token de passagem à API (POST /v1/handoffs).
  2. A aba vai para https://widget.clubebis.com/assinar#h=<token>. O token fica no fragmento da URL: não chega a servidor, log nem Referer. Nenhum dado do comprador vai na URL.
  3. A página do Bis troca o token pela sessão (POST /v1/handoffs/redeem) e apaga o fragmento da barra.

O token vale 5 minutos e uma vez só; o Bis guarda apenas o hash dele. Se o navegador bloquear a aba, o banner mostra o link "Abrir o Clube Bis" com a mesma passagem.

Na página do Bis o comprador vê os dados pré-preenchidos e editáveis (modo assinado) ou campos vazios (sem código), aceita os Termos e paga com Apple Pay, Google Pay, cartão de crédito ou Pix Automático. No fim, a página diz que ele pode fechar a aba e voltar para a sua.

Por que widget.clubebis.com/assinar e não clubebis.com: é o mesmo projeto e o mesmo build do card, já aceito pela API como origem do Bis.

Confirmar pedidos

Adesões feitas pelo modo sem código nascem pendentes: a cobrança acontece, mas o crédito de R$ 20, o número da sorte e o seu bônus ficam travados até o pedido ser confirmado.

Confirme com POST /v1/partner/orders/confirm, assinado do mesmo jeito que POST /v1/sessions (corpo cru). Um job diário com as vendas aprovadas resolve:

json
{
  "partnerId": "prt_suaticketeira",
  "orders": [
    { "orderRef": "TNG-8F3K2Q", "buyerEmail": "[email protected]" },
    { "orderRef": "TNG-9J4L1R" }
  ]
}
  • Até 500 pedidos por chamada. Pode confirmar pedidos que ainda não têm adesão: a adesão futura já nasce destravada.
  • buyerEmail é opcional. Se vier e não bater com o e-mail do assinante, o resultado é email_mismatch e a adesão continua pendente para revisão.
  • Se a página de confirmação mostra identificadores diferentes conforme o caminho (por exemplo, um token de transação numa página e um código de pagamento em outra), mande os dois no mesmo lote.
  • Não confirme pedidos cancelados ou estornados.

Resposta: { "results": [{ "orderRef": "TNG-8F3K2Q", "status": "confirmed", "released": true }] }. status pode ser confirmed, already_confirmed ou email_mismatch.

Chaves de API

O widgetSecret assina as chamadas do seu servidor (POST /v1/sessions, POST /v1/partner/orders/confirm e os relatórios).

  • Crie e revogue chaves no painel do parceiro, em Configuração → Chaves de API. O painel mostra quando cada chave foi usada pela última vez.
  • Qualquer chave ativa vale. Para rotacionar sem downtime: crie a nova, troque no servidor, revogue a antiga.
  • A chave fica só no servidor: nunca no navegador, no app ou no repositório.
  • Assinatura inválida, ausente ou com partnerId diferente do cabeçalho: 401.

Para GET, assine a string GET:<caminho+query>:

js
const path = "/v1/partner/reports/monthly?month=2026-11";
const sig = createHmac("sha256", WIDGET_SECRET).update(`GET:${path}`).digest("hex");
const r = await fetch(`https://api.clubebis.com${path}`, { headers: { "X-Bis-Partner": PARTNER_ID, "X-Bis-Signature": sig } });

Webhooks

O Bis avisa o seu servidor sobre o ciclo de vida das adesões que vieram de você.

Evento Quando
member.joined Adesão criada
subscription.activated 1ª mensalidade cheia paga
subscription.canceled Assinatura cancelada
credit.issued Crédito de R$ 20 emitido (com o cupom)
credit.redeemed Cupom usado num pedido seu
credit.expired Cupom venceu sem uso
payout.ready Repasse do mês fechado

Para receber:

  1. Cadastre a URL (HTTPS) no painel, em Configuração → Webhooks, e escolha os eventos.
  2. Copie o segredo (whsec_…). Ele aparece uma vez só. Perdeu? Use Rotacionar segredo: o anterior para de valer na hora, inclusive para entregas na fila, então atualize o receptor logo em seguida.
  3. Em cada entrega, confira a assinatura e deduplique pelo id da entrega.

Cada entrega é um POST com o evento em JSON e os cabeçalhos:

  • X-Bis-Delivery: id da entrega. A mesma entrega pode chegar mais de uma vez.
  • X-Bis-Signature: sha256=<hex> = HMAC-SHA256(segredo do webhook, corpo cru).
js
import crypto from "node:crypto";
import express from "express";

const app = express();
const vistos = new Set(); // em produção, use o seu banco

app.post("/webhooks/bis", express.raw({ type: "application/json" }), (req, res) => {
  const esperado = "sha256=" + crypto.createHmac("sha256", process.env.BIS_WEBHOOK_SECRET).update(req.body).digest("hex");
  const recebido = req.get("x-bis-signature") ?? "";
  const ok = esperado.length === recebido.length && crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(recebido));
  if (!ok) return res.status(401).end();

  const entrega = req.get("x-bis-delivery");
  if (vistos.has(entrega)) return res.status(200).end();
  vistos.add(entrega);

  const evento = JSON.parse(req.body);
  // trate evento.type: "credit.issued", "subscription.canceled", …
  res.status(200).end();
});

Assine sobre o corpo cru (os bytes recebidos), não sobre um JSON re-serializado. Responda 2xx rápido e processe depois; fora de 2xx, a entrega volta com backoff.

Reembolsos

A mensalidade do Bis é uma cobrança separada do ingresso, feita pelo Bis.

  • Reembolso do Bis é pedido pelo assinante ao Bis (área do assinante, WhatsApp ou e-mail) e feito pelo Bis. Você não precisa fazer nada.
  • Estorno do ingresso é com você e não mexe na assinatura do Bis. No modo sem código, não confirme pedidos estornados: assim os benefícios daquela adesão continuam travados.
  • Efeito no repasse. Um reembolso de mensalidade reverte a sua comissão (15%) na mesma proporção. O bônus de R$ 5 do dia 60 é proporcional à parte não reembolsada da 1ª mensalidade cheia; um estorno depois do dia 60 lança o ajuste (bonus_clawback). No extrato (GET /v1/partner/payouts/{mês}), o estorno aparece em refunds e o bônus vem líquido em bonuses.

Relatórios

Rota O que traz
GET /v1/partner/reports/monthly?month=AAAA-MM Pedidos elegíveis, ofertas exibidas, adesões, assinantes ativos e a prévia do repasse
GET /v1/partner/payouts/{AAAA-MM} Extrato: comissão, bônus, créditos reembolsados, estornos e total (centavos)

Os mesmos números estão no painel do parceiro.

Testar

Demo ao vivo

Em demo.clubebis.com há uma ticketeira fictícia, a Palco Aberto (prt_palcoaberto), com o widget real no ambiente de desenvolvimento e amostragem de 100%:

  1. Escolha um evento e clique em Comprar agora.
  2. Preencha os dados do comprador com dados de teste, por exemplo Tua Mãe Aquela Ursa, [email protected].
  3. Pague o ingresso com cartão de teste ou Pix (o botão Simular pagamento no banco faz o papel do banco).
  4. Na confirmação, o banner aparece abaixo de "Ingressos adquiridos". Clique em Resgatar e siga a adesão na aba do Bis com qualquer forma de pagamento (Apple Pay, Google Pay, cartão ou Pix Automático; em dev o pagamento é simulado).

O painel Por trás da compra da demo mostra as chamadas que a ticketeira faz ao Bis. Use a demo como referência de CSP: o _headers dela libera só o que o Bis precisa.

Seu ambiente de testes

  • Use a API de desenvolvimento, https://api-dev.clubebis.com, e o widget https://widget-dev.clubebis.com. Lá o pagamento é simulado.
  • Peça ao Bis um parceiro de teste. A chave de desenvolvimento é diferente da de produção.
  • Para dados de comprador, use nomes e e-mails fictícios. Nunca dados reais de clientes.

Checklist antes de ir para produção

  • Troque widget-dev por widget e api-dev por api na tag, na CSP e no servidor.
  • Use a chave de produção, guardada como segredo do servidor.
  • Cadastre os domínios de produção no painel.
  • Confirme que o webhook valida a assinatura e deduplica por X-Bis-Delivery.
  • No modo sem código, agende a confirmação diária de pedidos.

Copiar e colar

Tag sem código (site todo ou GTM)

html
<script src="https://widget.clubebis.com/bis-auto.js" data-parceiro="prt_suaticketeira" async></script>

Tag só na página de confirmação

html
<div id="bis-oferta"></div>
<script src="https://widget.clubebis.com/bis-auto.js"
        data-parceiro="prt_suaticketeira"
        data-pedido="NUMERO_DO_PEDIDO"
        data-valor="12000"
        data-alvo="#bis-oferta" async></script>

SPA: mostrar quando a compra concluir

html
<script>window.Bis=window.Bis||function(){(Bis.q=Bis.q||[]).push(arguments)}</script>
<script src="https://widget.clubebis.com/bis-auto.js" data-parceiro="prt_suaticketeira" data-gatilho="api" async></script>
<script>
  // no callback de compra aprovada:
  Bis("show", { pedido: "TNG-8F3K2Q", valor: 12000, alvo: "#bis-oferta" });
</script>

CSP do banner

http
Content-Security-Policy: script-src 'self' https://widget.clubebis.com; connect-src 'self' https://api.clubebis.com

Confirmar pedidos (Node)

js
import { createHmac } from "node:crypto";

const body = JSON.stringify({
  partnerId: "prt_suaticketeira",
  orders: pedidosAprovados.map((p) => ({ orderRef: p.ref, buyerEmail: p.email })),
});
const sig = createHmac("sha256", process.env.BIS_WIDGET_SECRET).update(body).digest("hex");
const r = await fetch("https://api.clubebis.com/v1/partner/orders/confirm", {
  method: "POST",
  headers: { "content-type": "application/json", "X-Bis-Partner": "prt_suaticketeira", "X-Bis-Signature": sig },
  body,
});
const { results } = await r.json();

Abrir sessão (curl)

bash
BODY='{"partnerId":"prt_suaticketeira","orderRef":"TNG-480231","amount":12000}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$BIS_WIDGET_SECRET" -hex | sed 's/^.* //')
curl -s https://api.clubebis.com/v1/sessions \
  -H "content-type: application/json" \
  -H "X-Bis-Partner: prt_suaticketeira" \
  -H "X-Bis-Signature: $SIG" \
  -d "$BODY"

Verificar webhook (Python)

python
import hmac, hashlib

def assinatura_ok(corpo_cru: bytes, cabecalho: str, segredo: str) -> bool:
    esperado = "sha256=" + hmac.new(segredo.encode(), corpo_cru, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperado, cabecalho or "")

Todas as rotas, com corpos e erros, estão na referência da API.