Visão geral

Visão Geral

O módulo de Saques na API Selectwin permite gerenciar todas as operações relacionadas à transferência de fundos de sua conta para carteiras específicas. Este módulo é essencial para o controle de fluxo de caixa, permitindo solicitar, acompanhar e gerenciar saques de forma eficiente e segura.

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 de saque.
• Verificação de Saldo: Sempre verifique o saldo disponível antes de solicitar um saque.
• Valores Mínimos: Respeite os valores mínimos estabelecidos pelo seu plano de taxas.
• 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_*).

Para consultar o saldo disponível antes de sacar, use Consultar Saldo (GET /v1/balance).

Objeto de Saque

O objeto de saque representa uma solicitação de transferência de fundos da sua conta para uma carteira cadastrada. Respostas de recurso (create/read) incluem merchant + _links + o snapshot receivingBankAccount no root. Os itens da listagem (/v1/withdrawals) não carregam receivingBankAccount nem _links por item.

{
  "id": "cash_01hqzvabc",
  "walletId": "wall_01hqzvabc",
  "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",
  "receivingBankAccount": {
    "holderName": "João Santos",
    "document": "12345678901",
    "bankCode": "260",
    "bankName": null,
    "routingNumber": "0001",
    "accountNumber": "11111111-5",
    "type": "checking",
    "pixKey": null
  },
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/withdrawals/cash_01hqzvabc",
      "method": "GET",
      "description": "Read a withdrawal."
    }
  }
}

Parâmetros para Criação de Saque

Atributos do Saque (Resposta)

Saque automático (auto-cashout): regras recorrentes de saque por percentual estão disponíveis na API pública em /v1/withdrawals/auto (CRUD: POST/GET/PUT/DELETE, escopos withdrawals:*) — recurso caa_*. Esta referência cobre os saques manuais (/v1/withdrawals).

• Step-up (sessão de dashboard): criar (POST) e alterar (PUT) uma ordem de saque automático exigem autenticação recente + fator forte (TOTP/código de backup) re-provado via POST /v1/authentication/step-up — a mesma barra do saque manual, porque a ordem executa exatamente o mesmo saque, todo dia. Sem isso: 401 stepUpRequired. Chamadas com API key não passam por step-up. O DELETE não exige step-up: é o freio para parar a ordem.
• Notificação: criar ou alterar a ordem avisa owners/admins (in-app + e-mail + push) com o destino mascarado e o percentual.

Status do Saque

Fluxo de Status do Saque

O saldo disponível é debitado no momento da criação do saque (débito antes do envio ao provedor, para evitar gasto duplicado). Uma falha posterior reverte o débito.

Webhooks Acionados

O nome do evento de webhook difere do status interno: approved/confirmed → withdrawal.confirmed; failed → withdrawal.refused.

Casos de Uso

1. Gestão de Fluxo de Caixa: Monitore saques para controle de saídas e planejamento financeiro.
2. Automação de Saques: Implemente rotinas automatizadas para solicitar saques quando o saldo disponível atingir determinados valores.
3. Relatórios de Saques: Desenvolva dashboards e relatórios personalizados com base no histórico de saques.
4. Auditoria de Transferências: Acompanhe o histórico completo de saques para fins de auditoria e compliance.

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 saques.
4. Filtros Eficientes: Utilize filtros específicos nas consultas para obter apenas os saques relevantes.
5. Monitoramento Regular: Acompanhe regularmente o status dos saques para identificar qualquer problema.
6. Tratamento de Webhooks: Implemente handlers adequados para os eventos de webhook relacionados a saques.

Integração com Outros Módulos

• O módulo de Saques se integra com o módulo de Finanças para verificação de saldo disponível.
• Utilize o módulo de Webhooks para receber notificações automáticas sobre mudanças de status em saques.