Marketplace - Planos de taxas

#Visão Geral

Um plano de taxas é uma tabela que a plataforma aplica a um grupo de sub-contas: a taxa por meio de pagamento (Pix, boleto, crédito, débito), a taxa por quantidade de parcelas no crédito, o prazo de liberação de cada meio e a tarifa de saque. Em vez de uma taxa simples por sub-conta (platformFee), você cria o plano uma vez e o atribui a quantas sub-contas quiser.

Nas vendas de uma sub-conta com plano, a plataforma recolhe o que o plano define para aquele meio (e parcelas); os recebíveis da sub-conta seguem o prazo de liberação do plano; e cada saque dela paga a tarifa do plano.

#Precauções

• Mesma forma que a sua taxa. Para cada meio, o plano só cobra na mesma forma (percentual ou fixo) que a taxa da sua própria conta usa naquele meio; caso contrário, 422 planFeeTypeMismatch com params: [{ "method": "credit", "field": "percent" }]. Se a sua conta ainda não tem taxa configurada, 422 platformRatesMissing.
• Prazo de liberação nunca menor que o seu. O releaseDays de um meio não pode ser menor que o prazo em que a sua plataforma recebe aquele meio (a sub-conta não pode ser paga antes de você): 422 planReleaseBelowPlatform, com o mínimo por campo em params.
• Plano em uso não é apagado. DELETE de um plano atribuído a sub-contas responde 409 planInUse com params[0].subAccounts (quantas o usam). Mova-as para outro plano (ou retire o plano) antes.
• Alterar um plano vale para as próximas cobranças de todas as sub-contas que o usam.
• Recurso de conta: crie e altere planos com uma chave sk_live_ (com sk_test_, 409 accountLevelReadOnlyInSandbox).

#Estrutura do Objeto Plano

{
  "id": "rate_01hqzvplan1",
  "name": "Vendedores Prata",
  "pix": { "percent": 1.5, "fixed": 0, "releaseDays": 1 },
  "boleto": { "percent": 0, "fixed": 250, "releaseDays": 2 },
  "credit": {
    "percent": 4.5,
    "fixed": 0,
    "installments": [ { "n": 2, "percent": 5.5 }, { "n": 3, "percent": 6.5 } ],
    "releaseDays": 30
  },
  "debit": { "percent": 2, "fixed": 0, "releaseDays": 1 },
  "withdrawalFee": 350,
  "createdAt": "2026-10-17T12:00:00.000Z"
}

#Criar um plano

POST /v1/marketplace/plans

#Corpo da Requisição

{
  "name": "Vendedores Prata",
  "pix": { "percent": 1.5, "releaseDays": 1 },
  "boleto": { "fixed": 250, "releaseDays": 2 },
  "credit": { "percent": 4.5, "installments": [ { "n": 2, "percent": 5.5 }, { "n": 3, "percent": 6.5 } ], "releaseDays": 30 },
  "debit": { "percent": 2, "releaseDays": 1 },
  "withdrawalFee": 350
}

#Resposta (201 Created)

O objeto do plano.

#Listar e consultar

GET /v1/marketplace/plans
GET /v1/marketplace/plans/{planId}

A lista responde { "data": [ …planos ], "count": 2 }; a consulta responde o objeto do plano.

#Alterar um plano

PATCH /v1/marketplace/plans/{planId}

Mesmos campos da criação, todos opcionais; campos desconhecidos são recusados com 400. Responde o plano atualizado.

#Excluir um plano

DELETE /v1/marketplace/plans/{planId}

Responde { "id": "rate_01hqzvplan1", "deleted": true }. Só um plano sem sub-contas pode ser excluído.

#Atribuir a uma sub-conta

PUT /v1/marketplace/sub-accounts/{companyId}/plan com { "planId": "rate_…" } (ou null para retirar) — veja Atualizar. Na criação da sub-conta, envie planId direto (Criar).

#Erros

#Exemplo

curl -X POST "https://api.selectwin.io/v1/marketplace/plans" \
     -H "SelectKey: sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
     -H "Content-Type: application/json" \
     -d '{ "name": "Vendedores Prata", "pix": { "percent": 1.5, "releaseDays": 1 }, "credit": { "percent": 4.5, "releaseDays": 30 }, "withdrawalFee": 350 }'