Listar saques

Visão Geral

Este endpoint permite recuperar um histórico detalhado de todos os saques solicitados na conta, com opções de filtragem por status, período e paginação. Este recurso é essencial para acompanhamento de transferências bancárias, controle de fluxo de caixa e reconciliação financeira com extratos bancários.

Precauções

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

Paginação: Utilize os parâmetros de paginação (limit e offset) para controlar o volume de dados retornados.
Filtros: Para consultas com muitos resultados, use filtros específicos para reduzir o conjunto de dados.
Valores Monetários: Todos os valores monetários são retornados em centavos (por exemplo, R$ 100,00 é representado como 10000).
Histórico: Os dados de saques são mantidos por tempo indeterminado para fins de auditoria.

Descrição

O endpoint Listar Saques permite consultar o histórico completo de saques solicitados na conta, incluindo saques pendentes, processados, concluídos ou cancelados. Os resultados podem ser filtrados por diversos parâmetros como status, data ou valor.

Requisição

GET /v1/withdrawals

Parâmetros de Consulta (Query)

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
`limit`	integer	Não	Número máximo de registros a serem retornados (1–100, padrão `20`)	`20`
`offset`	integer	Não	Posição inicial para retornar registros (paginação, padrão `0`)	`0`
`sort`	string	Não	Ordenação dos resultados (`ascending` / `descending`)	`descending`
`id`	string	Não	Filtrar por ID específico do saque (`cash_*`)	`cash_01hqzvabc`
`status`	string	Não	Filtrar por status (texto livre): `pending`, `processing`, `analysis`, `approved`, `confirmed`, `refused`, `canceled`, `failed`	`pending`
`method`	string	Não	Filtrar por método (texto livre): `bankTransfer` ou `pixTransfer`	`bankTransfer`
`daterange`	string	Não	Filtra por data de criação (`YYYY-MM-DD` ou datetime ISO 8601)	`2026-04-12`
`daterangegt` / `daterangegte` / `daterangelt` / `daterangelte`	string	Não	Filtros de intervalo por data de criação (datetime ISO 8601)	`2026-04-01T00:00:00Z`

status e method são filtros de texto livre: um valor desconhecido simplesmente retorna nenhum registro (não gera erro 400).

Resposta - 200 OK

Se a requisição for bem-sucedida, o servidor retornará um código de status HTTP 200 OK e uma lista paginada de saques.

Exemplo de Resposta

{
  "offset": 0,
  "limit": 20,
  "total": 2,
  "hasMore": false,
  "page": {
    "current": 1,
    "total": 1,
    "offset": { "first": 0, "prev": 0, "next": 0, "last": 0 }
  },
  "data": [
    {
      "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"
    },
    {
      "id": "cash_01hqzvdef",
      "walletId": "wall_01hqzvabc",
      "amount": 25000,
      "fee": 15,
      "status": "paid",
      "method": "bankTransfer",
      "currency": "BRL",
      "transferCode": "TRF123456",
      "paidAt": "2025-02-05T14:20:30.000Z",
      "approvedAt": "2025-02-05T10:15:22.000Z",
      "createdAt": "2025-02-05T09:15:00.000Z",
      "updatedAt": "2025-02-05T14:20:30.000Z"
    }
  ],
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/withdrawals",
      "method": "GET",
      "description": "List all withdrawals."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/withdrawals",
      "method": "POST",
      "description": "Create a new withdrawal."
    }
  }
}

Atributos da Resposta Paginada

Atributo	Tipo	Descrição
`offset`	integer	Posição inicial dos resultados retornados
`limit`	integer	Quantidade máxima de registros retornados
`total`	integer	Total de registros disponíveis para a consulta
`hasMore`	boolean	Indica se existem mais resultados além dos retornados
`page.current` / `total` / `offset.*`		Estrutura de página padrão (offsets são inteiros)
`data`	array	Saques (cada item carrega `walletId`, mas sem `receivingBankAccount` nem `_links` por item)
`merchant`	object	Merchant
`_links`	object	Links HATEOAS (no nível raiz)

Casos de Uso

Reconciliação Bancária: Comparar saques realizados com entradas em extratos bancários
Histórico Financeiro: Manter registro completo de todas as movimentações financeiras
Monitoramento de Saques: Acompanhar o status de saques pendentes ou agendados
Relatórios de Auditoria: Gerar relatórios de saques para fins de auditoria financeira

Melhores Práticas

Implementar Paginação Eficiente: Utilize os parâmetros limit e offset para controlar o volume de dados
Utilizar Filtros: Aplique filtros específicos para reduzir o conjunto de resultados
Verificação Regular: Consulte periodicamente os saques pendentes para identificar falhas ou atrasos
Exportação de Dados: Considere exportar os dados de saques para backup ou análise externa

Integração com Outros Endpoints

Use Consultar Saque para obter detalhes completos de um saque específico
Use Criar Saque para solicitar um novo saque
Use Consultar Saldo para verificar o saldo disponível para saques

Listar saques

On this page