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

Ao fechar uma operação (POST /v1/escrows), o sistema cria um contrato com o snapshot de taxas.

• Status inicial: pending_agree
• Vendedor e comprador enviam I Agree em POST /v1/contracts/{id}/agree
• Body: { "party": "merchant"|"buyer", "iAgree": true }
• Quando ambos aceitam → agreed e a operação segue

Termo do vendedor (cadastro): legal/termo-vendedor-v1.md — produto lícito, não roubado, autenticidade.

4. Cadastro de produtos

Campos: título, descrição, preço, moeda, estoque, canal, categoria, aceite do termo.

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 (não global). Header: Authorization: Bearer gt_live_…

POST /v1/escrows
POST /v1/contracts/{id}/agree
POST /v1/escrows/{id}/ship
POST /v1/escrows/{id}/confirm-delivery
GET  /v1/meta/fees?amount=100
POST /analytics/click

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