Saques - 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

• 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_*).

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

#Status do Saque

#Fluxo de Status do Saque

stateDiagram-v2
    state "pending" as pending
    state "processing" as processing
    state "confirmed" as confirmed
    state "paid" as paid
    state "refused" as refused
    state "canceled" as canceled

    [*] --> pending: POST /v1/withdrawals (debita o saldo disponível)
    pending --> processing: em processamento
    pending --> canceled: cancelado
    pending --> refused: recusado
    processing --> confirmed: confirmado
    processing --> paid: concluído
    processing --> refused: falhou
    confirmed --> paid
    paid --> [*]
    refused --> [*]
    canceled --> [*]

#Webhooks Acionados

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