Documentação Gobtween

Manual operacional e de integração — no mesmo espírito da documentação do Sensor Tattoo Fix: tudo num lugar, para operar sem surpresa.

1. Visão geral

O Gobtween retém o pagamento até a entrega/confirmação. O vendedor recebe o líquido = bruto − taxa do PSP − comissão Gobtween.

• Loja Gobtween — cadastra e vende aqui
• API / embed — vende no site dele, passa pelo cofre

2. Comissão configurável

No admin: PUT /admin/config com fees.commissionPercent.

Regra de ouro: ao salvar uma comissão nova, ela se espalha para o site inteiro e para novos fechamentos. Contratos/escrows já fechados mantêm o feeSnapshot antigo — não mudam.

{
  "fees": {
    "commissionPercent": 5,
    "estimatedPspFeePercent": { "mercadopago": 4.99, "paypal": 4.4 }
  }
}

O vendedor sempre vê o breakdown antes de confirmar (bruto, PSP, comissão, líquido).

3. Contrato + I Agree

O I Agree aparece em dois momentos distintos:

1. Vendedor — ao cadastrar o produto (/vendedor/) → Termo do Vendedor
2. Comprador — na compra (/comprar/) → Termo do Comprador. Operação é só acompanhamento.

• Embed leva para /comprar/?product=… (I Agree + pagar)
• API merchant sem aceite do buyer: redirecione a buyUrl
• Só após agreed libera approveUrl (PayPal)

4. Cadastro de produtos

Campos: título, descrição, preço, moeda, estoque, canal, categoria, termsAccepted / I Agree.

Categorias: ingresso_show, ingresso_esporte, evento, produto_fisico, servico, outro.

Ingressos ficam pending_review antes de publicar.

5. API / embed

API key por merchant e por site. Gerada no I Agree do vendedor (/vendedor/). Header: Authorization: Bearer gt_live_…

Dois caminhos:

• A · Produto no Gobtween — POST /v1/products → link /comprar/?product=p_…
• B · Outro site — valor avulso no embed ou POST /v1/escrows → redireciona ao buyUrl

POST /v1/merchants/register
POST /v1/merchants/accept-terms   → devolve apiKey (1ª vez)
POST /v1/products                 { termsAccepted: true }
POST /v1/embed/start              { iAgree, productId } OU { iAgree, merchantId, amount }
POST /v1/escrows                  Bearer gt_live_… (pedido do seu sistema)
POST /v1/contracts/{id}/agree
GET  /v1/meta/fees?amount=100

Snippet A (produto):

<div data-gobtween-pay data-product="p_xxx"></div>
<script src="https://gobtween.com/embed.js" async></script>

Snippet B (venda externa, sem produto):

<div data-gobtween-pay
     data-merchant="m_xxx"
     data-amount="99.90"
     data-currency="BRL"></div>
<script src="https://gobtween.com/embed.js" async></script>

5b. Tela visual da operação

Modelo P2P (pessoa ↔ pessoa): quem vende pode ser alguém que comprou ingresso antecipado e revende. O nome do item vem do anúncio (genérico — não só ingresso).

Tela: /operacao/?demo=1 — dinheiro no cofre até o comprador entrar no evento ou confirmar item em bom estado.

6. Liberação automática (sem mão na massa)

Cron a cada 30 min (api/wrangler.toml) roda processAutoReleases:

1. Entrega confirmada pelo comprador → captura PSP → released
2. Transportadora marca entregue → delivered → libera
3. Após N dias em delivered sem disputa → libera sozinho

Disputa bloqueia auto-release até resolução. Monitoramento via API/webhooks do PSP — objetivo: zero intervenção manual.

7. Cliques e exportações

• POST /analytics/click — categorias (destino, seção, página, país…)
• GET /admin/clicks — lista
• GET /admin/clicks?format=csv — export
• Export de produtos/comissões — painel admin (fase B, padrão STF CSV/Excel)

8. PT / EN / IT

Site e documentação espelhados:

• PT: /, /ajuda/, /documentacao.html
• EN: /en/, /en/ajuda/, /en/documentacao.html
• IT: /it/, /it/ajuda/, /it/documentacao.html

Textos de contrato/e-mail seguem o locale da operação.

hello@gobtween.com · gobtween.com