Finanças - 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

• 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

#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

#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

stateDiagram-v2
    state "scheduled" as scheduled
    state "pending" as pending
    state "paid" as paid
    state "dispute" as dispute
    state "chargeback" as chargeback
    state "refunded" as refunded
    state "canceled" as canceled

    [*] --> scheduled: recebível gerado (expectedOn futuro)
    [*] --> pending: aguardando liquidação
    scheduled --> paid: na data prevista
    pending --> paid: liberado
    scheduled --> canceled
    pending --> canceled
    paid --> refunded: transação reembolsada
    paid --> dispute: contestação
    dispute --> chargeback
    dispute --> paid: disputa resolvida
    paid --> [*]
    refunded --> [*]
    chargeback --> [*]
    canceled --> [*]

#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.