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.
<script src="https://widget-dev.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:
- O script acompanha a navegação (incluindo
pushStateepopstatede SPAs) e, só enquanto a URL bate, observa a página. - 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 dodataLayer. - Cria uma sessão não assinada (
POST /v1/sessions/auto), que confere se a página está num dos seus domínios permitidos. - 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:
{
"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
- 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. - 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.
- Liberar a CSP da página (ver abaixo).
- 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.
- 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):
import { createHmac } from "node:crypto";
const BIS_API = "https://api-dev.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. Quandoshowvierfalse, 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:
<div id="bis-oferta"></div>
<script src="https://widget-dev.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.
Banner, modal e card
O padrão é o banner. Para usar o card, peça ao Bis: a troca vale para todas as páginas do parceiro.
Banner (padrão)
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-dev.clubebis.com e connect-src https://api-dev.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-dev.clubebis.com, mais Permissions-Policy: payment=(self "https://widget-dev.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:
- 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). - A aba vai para
https://widget-dev.clubebis.com/assinar#h=<token>. O token fica no fragmento da URL: não chega a servidor, log nemReferer. Nenhum dado do comprador vai na URL. - 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:
{
"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_mismatche 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
partnerIddiferente do cabeçalho:401.
Para GET, assine a string GET:<caminho+query>:
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-dev.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:
- Cadastre a URL (HTTPS) no painel, em Configuração → Webhooks, e escolha os eventos.
- 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. - 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).
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 emrefundse o bônus vem líquido embonuses.
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%:
- Escolha um evento e clique em Comprar agora.
- Preencha os dados do comprador com dados de teste, por exemplo Tua Mãe Aquela Ursa,
[email protected]. - Pague o ingresso com cartão de teste ou Pix (o botão Simular pagamento no banco faz o papel do banco).
- 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 widgethttps://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-devporwidgeteapi-devporapina 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)
<script src="https://widget-dev.clubebis.com/bis-auto.js" data-parceiro="prt_suaticketeira" async></script>Tag só na página de confirmação
<div id="bis-oferta"></div>
<script src="https://widget-dev.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
<script>window.Bis=window.Bis||function(){(Bis.q=Bis.q||[]).push(arguments)}</script>
<script src="https://widget-dev.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
Content-Security-Policy: script-src 'self' https://widget-dev.clubebis.com; connect-src 'self' https://api-dev.clubebis.comConfirmar pedidos (Node)
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-dev.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)
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-dev.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)
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.