Visão geral

Visão Geral

O recurso de Finanças na API Selectwin permite gerenciar todos os aspectos financeiros de sua conta, incluindo consulta de saldo, solicitação de saques e acompanhamento de transações financeiras. Este módulo é essencial para o controle financeiro, reconciliação contábil e gestão de fluxo de caixa de sua operação.

Precauções

ATENÇÃO! Por favor, leia estas informações importantes antes de usar este módulo.

• Segurança: Mantenha as credenciais de acesso à API seguras e implemente controles de acesso adequados para operações financeiras.
• Verificação Regular: Implemente verificações periódicas do saldo para garantir que os valores estejam corretos.
• Conciliação: Compare regularmente as transações financeiras com os extratos bancários para identificar divergências.
• Tratamento de Erros: Implemente tratamento adequado para falhas em saques ou transações financeiras.

Operações Disponíveis

Base URL: https://api.selectwin.io/v1. Header de autenticação: SelectKey (sk_test_* / sk_live_*).

Objetos

Objeto de Saldo

O objeto de saldo representa a situação financeira atual de sua conta na plataforma. Os valores são divididos em "buckets" (centavos, BRL). Resposta com merchant no root (sem _links).

{
  "availableBalance": 150000,
  "pendingBalance": 25000,
  "blockedBalance": 0,
  "refundedBalance": 12000,
  "warrantyBalance": 5000,
  "currency": "BRL",
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  }
}

Atributos do Saldo

O objeto de saldo não possui id/bal_, feePlan, debit, createdAt nem _links. As chaves dos buckets são availableBalance/pendingBalance/blockedBalance/refundedBalance/warrantyBalance.

Saúde de Risco (Risk Health)

Endpoint: GET /v1/finance/risk-health (escopo finance:read). Aceita o parâmetro de consulta opcional window (rolling30d padrão, rolling7d, monthToDate).

Retorna objeto direto (sem merchant/_links neste caso específico).

{
  "object": "merchant_risk_health",
  "window": "rolling30d",
  "periodStart": "2026-03-13T00:00:00.000Z",
  "periodEnd": "2026-04-12T00:00:00.000Z",
  "tier": "ok",
  "chargebackRatio": 0.8,
  "chargebackCount": 2,
  "disputeRatio": 1.2,
  "refundRatio": 2.5,
  "thresholds": {
    "chargebackWarnRatio": 1,
    "chargebackExcessiveRatio": 2,
    "mastercardEcmRatio": 1.5,
    "disputeWarnRatio": 2,
    "refundWatchRatio": 5
  },
  "lastEvaluatedAt": "2026-04-12T17:56:33.000Z"
}

tier ∈ ok/watch/warning/breach/excessive. periodStart, periodEnd e lastEvaluatedAt podem ser null. Não há disputeCount nem refundCount. Este endpoint pertence ao módulo de risco do merchant.

Objeto de Saque

O objeto de saque representa uma solicitação de transferência de fundos da sua conta para uma carteira cadastrada (veja Saques para os detalhes completos).

{
  "id": "cash_123456789",
  "walletId": "wall_123456789",
  "amount": 45000,
  "fee": 15,
  "status": "pending",
  "method": "bankTransfer",
  "currency": "BRL",
  "transferCode": null,
  "paidAt": null,
  "approvedAt": null,
  "createdAt": "2025-02-07T00:12:33.000Z",
  "updatedAt": "2025-02-07T00:12:33.000Z"
}

Parâmetros para Criação de Saque

amount e fee são números inteiros em centavos. O status inicial é pending e o saldo é debitado no ato da criação. Detalhes de status, webhooks e do snapshot receivingBankAccount em Saques.

Objeto de Recebível

O objeto de recebível representa um valor a receber em sua conta, proveniente de vendas. Veja Recebíveis para a referência completa.

{
  "id": "rec_123abc456def789ghi",
  "transactionId": "tra_987xyz654uvw321rst",
  "recipient": "com_123456789ABCDE001",
  "split": null,
  "status": "paid",
  "amount": 50000,
  "grossAmount": 50000,
  "antecipationFee": 0,
  "installmentNumber": 1,
  "currency": "BRL",
  "description": "Payment successfully completed.",
  "authorizationCode": "A1B2C3",
  "liable": true,
  "released": true,
  "expectedOn": null,
  "paidAt": "2025-02-05T18:00:00.000Z",
  "refundedAt": null,
  "canceledAt": null,
  "chargedBackAt": null,
  "disputedAt": null,
  "fraudChekingAt": null,
  "chargeProcessingFee": true,
  "createdAt": "2025-02-05T17:45:00.000Z",
  "updatedAt": "2025-02-05T18:30:00.000Z"
}

Atributos do Recebível

Fluxo de Status do Recebível

Webhooks Acionados

Saques:

Recebíveis:

Casos de Uso

1. Gestão de Fluxo de Caixa: Monitore entradas e saídas para planejamento financeiro e previsão de receitas.
2. Reconciliação Contábil: Exporte o histórico de transações financeiras para integração com sistemas contábeis.
3. Automação de Saques: Implemente rotinas automatizadas para solicitar saques quando o saldo disponível atingir determinados valores.
4. Relatórios Financeiros: Desenvolva dashboards e relatórios personalizados com base nos dados de transações financeiras.

Melhores Práticas

1. Verificar Saldo Disponível: Sempre consulte o saldo disponível antes de solicitar um saque.
2. Verificar Taxas: Esteja ciente das taxas aplicáveis ao seu plano antes de solicitar um saque.
3. Paginação de Resultados: Use parâmetros de paginação para consultas de grandes volumes de dados financeiros.
4. Filtros Eficientes: Utilize filtros específicos nas consultas para obter apenas os dados relevantes.
5. Monitoramento Regular: Acompanhe regularmente o status dos saques e recebíveis para identificar qualquer problema.

Integração com Outros Módulos

• O módulo de Finanças se integra com o módulo de Transações para acompanhamento de recebíveis gerados por vendas.
• Utilize o módulo de Webhooks para receber notificações automáticas sobre eventos financeiros importantes, como novos recebíveis ou mudanças de status em saques.