Listar recebíveis

Visão Geral

Este endpoint permite recuperar uma lista completa de valores a receber em sua conta, com opções para filtragem e paginação. É uma ferramenta essencial para acompanhamento de fluxo de caixa, previsão de receitas e reconciliação financeira.

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 para controlar o volume de dados retornados.
• Valores Monetários: Todos os valores monetários são apresentados em centavos.
• Status: Verifique o status de cada recebível para saber se ele já foi pago ou ainda está pendente.

Descrição

O endpoint de Listagem de Recebíveis permite consultar todos os valores a receber em sua conta, incluindo aqueles já pagos e os ainda pendentes. A resposta inclui detalhes como o valor, data prevista de pagamento, status atual e origem do recebível.

Requisição

GET /v1/receivables

Escopo necessário: receivables:list.

Parâmetros de Consulta

status é texto livre (casado contra a tabela de status). released aceita yes/no. Um valor desconhecido em status simplesmente não retorna registros.

Resposta - 200 OK

Em caso de sucesso, o servidor responde com o código de status HTTP 200 e um objeto JSON contendo a lista de recebíveis e informações de paginação.

{
  "offset": 0,
  "limit": 10,
  "total": 35,
  "hasMore": true,
  "page": {
    "current": 1,
    "total": 4,
    "offset": { "first": 0, "prev": 0, "next": 10, "last": 30 }
  },
  "data": [
    {
      "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"
    }
  ],
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/receivables",
      "method": "GET",
      "description": "List all receivables."
    }
  }
}

Atributos da Resposta

As chaves do recebível usam recipient/split (não recipientId/splitId), antecipationFee e fraudChekingAt (grafias históricas mantidas).

Respostas de Erro

400 Bad Request

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": [
      {
        "limit": "The limit must be a number between 1 and 100."
      }
    ]
  }
}

Casos de Uso

1. Previsão de Fluxo de Caixa: Visualizar valores a receber para planejamento financeiro.
2. Reconciliação Financeira: Comparar recebíveis esperados com valores efetivamente recebidos.
3. Monitoramento de Pendências: Identificar recebíveis atrasados ou com problemas.
4. Relatórios Gerenciais: Gerar relatórios de receitas para análise de desempenho.

Melhores Práticas

1. Paginação Eficiente: Utilize os parâmetros de paginação para consultas eficientes, especialmente para grandes volumes de dados.
2. Filtros Específicos: Use filtros por status, período ou transação para limitar os resultados às informações relevantes.
3. Consultas Periódicas: Implemente verificações regulares para atualizar os status dos recebíveis.
4. Tratamento de Erros: Implemente tratamento adequado para todos os possíveis códigos de erro.

Integração com Outros Endpoints

• Consultar Saldo: Use o endpoint Consultar Saldo para verificar o saldo atual, que inclui os recebíveis já pagos.
• Listar Transações: Use o endpoint de Listar Transações para obter mais detalhes sobre as transações que originaram os recebíveis.
• Webhooks: Configure Webhooks para receber notificações automáticas sobre mudanças no status dos recebíveis.