Finanças - Criar Saque

#Visão Geral

Este endpoint permite solicitar a transferência de fundos disponíveis em sua conta para uma carteira específica. É utilizado para iniciar o processo de saque, que será posteriormente processado e transferido para a carteira associada ao walletId fornecido.

#Precauções

• Saldo Disponível: Verifique sempre o saldo disponível antes de solicitar um saque usando o endpoint Consultar Saldo. O valor (mais a taxa) é debitado do saldo disponível no ato da criação.
• Saques habilitados: O saque precisa estar habilitado para a empresa; caso contrário, a criação retorna 400 withdrawalCreateNotEnabled.
• Valor Mínimo: Existe um valor mínimo de saque por empresa (padrão R$ 50,00 = 5000 centavos quando não configurado). Abaixo dele a API retorna 400 withdrawalAmountLessThanMinimum.
• Processamento: Saques não são instantâneos e passam por um processo de verificação antes de serem aprovados e processados.
• Carência de carteira nova: Uma carteira recém-cadastrada não pode receber saque até completar o período de carência de segurança — a API retorna 422 withdrawalWalletInCooldown. Vale apenas no ambiente live.
• Idempotência: A criação é idempotente — envie sempre o header X-Idempotency-Key (um UUID por pedido) para que um reenvio do mesmo pedido devolva o mesmo saque em vez de criar outro. Sem a chave, a API ainda recusa com 409 withdrawalDuplicateSuspected um segundo pedido idêntico (mesma carteira e mesmo valor) feito em menos de 10 segundos — nada é debitado por ele; mas essa rede só pega o duplo clique, não substitui a chave.
• Valores Monetários: Todos os valores monetários devem ser informados em centavos (por exemplo, R$ 450,00 deve ser enviado como 45000, um número inteiro).

#Descrição

O endpoint de Criação de Saque permite solicitar a transferência de fundos disponíveis em sua conta para uma carteira específica. Ao fornecer o ID da carteira e o valor desejado, o sistema iniciará o processo de saque, que será verificado, aprovado e processado de acordo com as políticas e prazos vigentes.

#Requisição

POST /v1/withdrawals

#Corpo da Requisição

{
  "walletId": "wall_01hqzvabc",
  "amount": 45000
}

#Parâmetros do Corpo

#Resposta - 201 Created

Em caso de sucesso, o servidor responde com o código de status HTTP 201 Created e um objeto JSON contendo as informações do saque criado.

{
  "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."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/withdrawals",
      "method": "POST",
      "description": "Create a new withdrawal."
    },
    "list": {
      "href": "https://api.selectwin.io/v1/withdrawals",
      "method": "GET",
      "description": "List all withdrawals."
    }
  }
}

#Atributos da Resposta

#Respostas de Erro

#400 Bad Request (validação)

Ocorre quando a requisição contém parâmetros inválidos ou está mal formatada.

{
  "error": {
    "status": "Bad Request",
    "statusCode": 400,
    "category": "validation",
    "message": "Validation errors occurred.",
    "params": [
      {
        "amount": "The withdrawal amount must be greater than zero."
      }
    ]
  }
}

#422 Unprocessable Entity (saldo insuficiente)

{
  "error": {
    "status": "Unprocessable Entity",
    "statusCode": 422,
    "category": "validation",
    "code": "balanceIsInsufficient",
    "message": "Insufficient available balance for this withdrawal."
  }
}

#Casos de Uso

1. Pagamento de Fornecedores: Transferir fundos para pagamento de fornecedores ou prestadores de serviço.
2. Retirada de Lucros: Realizar a retirada de lucros para os sócios ou proprietários do negócio.
3. Transferência Entre Contas: Mover fundos entre diferentes contas da mesma empresa.
4. Pagamentos Recorrentes: Configurar saques programados para pagamentos recorrentes.

#Melhores Práticas

1. Verificar Saldo: Sempre verifique o saldo disponível antes de solicitar um saque.
2. Confirmar Valores: Confirme o valor correto em centavos para evitar erros.
3. Acompanhar Status: Utilize o endpoint Consultar Saque para acompanhar o status do saque após sua criação.
4. Tratamento de Erros: Implemente tratamento adequado para todas as possíveis respostas de erro.
5. Registro de Histórico: Mantenha um registro de todos os saques realizados para fins de auditoria.

#Integração com Outros Endpoints

• Consultar Saldo: Use o endpoint Consultar Saldo para verificar o saldo disponível antes de solicitar um saque.
• Consultar Saque: Use o endpoint Consultar Saque para acompanhar o status do saque após sua criação.
• Listar Saques: Use o endpoint Listar Saques para obter o histórico completo de saques.