Marketplace - Operar como a sub-conta

#Visão Geral

Uma venda feita com onBehalfOf pertence à sub-conta: é ela o vendedor de registro, é o saldo dela que recebe. Para consultar, capturar ou estornar essa venda, ler o saldo e os recebíveis da sub-conta, ou pedir um saque para ela, a plataforma age como a sub-conta com o cabeçalho X-Selectwin-Account.

curl "https://api.selectwin.io/v1/transactions/tra_01hqzvtx1" \
     -H "SelectKey: sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
     -H "X-Selectwin-Account: bus_01hqzvsub1"

Com o cabeçalho, a requisição roda na sub-conta indicada: os dados, as vendas, o saldo, os recebíveis, as carteiras e os saques são os dela, e a resposta diz isso em merchant (merchantId é a sub-conta e isSubAccount é true). A credencial continua sendo a sua chave de API, com as permissões dela.

#Onde vale

Em toda a API pública, exceto no próprio recurso Marketplace (/v1/marketplace/*, que já é da plataforma) e nas leituras de referência (/v1/utils, /v1/simulators, /v1/public). Os usos típicos:

Um saque pedido assim vai para a conta bancária da sub-conta (a carteira dela), nunca para a plataforma. A taxa da plataforma continua chegando pelo caminho de sempre: o split na venda.

#Regras

• Só chave de API. O cabeçalho é aceito apenas com SelectKey. Com qualquer outra credencial, a requisição é recusada.
• Só sub-conta sua. A conta tem de ser uma sub-conta da sua plataforma (a mesma regra do onBehalfOf). Caso contrário a resposta é 401 actingAccountInvalid — o cabeçalho nunca é ignorado em silêncio, para uma requisição que queria a sub-conta não rodar na sua conta por engano.
• A sua plataforma precisa estar ativa. Uma plataforma bloqueada, desabilitada ou ainda em análise não opera pelas sub-contas: com o cabeçalho a resposta é 401 actingAccountInvalid, mesmo com a sub-conta ativa — o mesmo que já valia para a venda com onBehalfOf.
• Os bloqueios da sua plataforma valem na sub-conta. Um recurso que a Selectwin bloqueou para a sua plataforma continua recusado (403) quando ela age pela sub-conta, somado aos bloqueios da própria sub-conta.
• A sub-conta precisa estar ativa para a maior parte das operações, como se o próprio vendedor chamasse: uma sub-conta pending, em análise ou suspensa responde 403 companyNotActive fora do cadastro.
• Ambiente: o da sua chave (sk_live_ ou sk_test_). As vendas de teste da sub-conta ficam no sandbox dela.
• Idempotência: o X-Idempotency-Key vale por sub-conta — a mesma chave em sub-contas diferentes são operações diferentes.
• Limites de uso: contam para a plataforma, não para cada sub-conta.
• Auditoria: a ação fica registrada na sub-conta, com a sua plataforma identificada como quem agiu.

#Erros

#Exemplo: criar, acompanhar e estornar

# 1. a venda, em nome da sub-conta
curl -X POST "https://api.selectwin.io/v1/transactions" \
     -H "SelectKey: sk_live_…" -H "Content-Type: application/json" \
     -d '{ "amount": 10000, "payment": { "method": "pix" }, "customer": { "id": "cus_…" }, "onBehalfOf": "bus_01hqzvsub1" }'

# 2. a mesma venda, lida como a sub-conta
curl "https://api.selectwin.io/v1/transactions/tra_01hqzvtx1" \
     -H "SelectKey: sk_live_…" -H "X-Selectwin-Account: bus_01hqzvsub1"

# 3. o estorno, como a sub-conta
curl -X POST "https://api.selectwin.io/v1/transactions/tra_01hqzvtx1/refund" \
     -H "SelectKey: sk_live_…" -H "X-Selectwin-Account: bus_01hqzvsub1" \
     -H "X-Idempotency-Key: 9c0d…" -H "Content-Type: application/json" -d '{}'