Métricas e análises

Retorna um recorte resumido dos seus recebíveis dentro de um intervalo de datas obrigatório, voltado a relatórios, dashboards e conciliação agregada. A resposta vem na chave list (não data) e não é paginada no formato padrão — pense nela como um "extrato" de período em vez de uma listagem completa.

GET /v1/receivables/analytics

Como funciona

Um recebível (receivable) é um valor a receber gerado por uma transação aprovada. Cada parcela de uma venda parcelada e cada destinatário de um split geram seus próprios recebíveis, com data prevista de liberação (expectedOn) e status próprio — veja Visão Geral.

O endpoint Analytics roda uma consulta sobre os recebíveis que caem no período entre initdate e enddate (ambos obrigatórios) e devolve, para cada recebível encontrado, uma projeção leve — um subconjunto dos campos. Em comparação com Listar, os itens aqui não trazem transactionId, recipientId, splitId, installmentNumber, description, paidAt, refundedAt nem canceledAt. A ideia é entregar exatamente o que um relatório precisa (valores, status, datas) sem o peso da projeção completa.

Pontos importantes do comportamento:

• É somente leitura. Nenhum recebível é criado, alterado ou movido. Você pode chamar este endpoint quantas vezes quiser, com segurança, e ele não tem efeitos colaterais (é uma operação idempotente — repetir não muda nada no servidor).
• A janela de datas é obrigatória. Sem initdate e enddate, a requisição falha com invalidParameters (400). Isso evita varreduras acidentais sobre toda a base.
• A resposta usa list, não data. Quem já integra a listagem precisa ajustar o caminho de leitura: o array de itens está em list[].
• _links (HATEOAS) traz o link self desta consulta e o link list para a listagem paginada completa, para você navegar entre as duas visões sem montar URLs à mão.

Quando usar (e quando não usar)

Use Analytics quando você precisa de uma visão agregada/resumida de um período fechado: alimentar um dashboard, montar um relatório mensal de recebíveis previstos, ou exportar um recorte enxuto para conciliação.

Prefira Listar quando você precisa:

• da projeção completa de cada recebível (incluindo transactionId, installmentNumber, description, paidAt/refundedAt/canceledAt);
• de paginação robusta (offset, limit, hasMore, page) para percorrer grandes volumes;
• de filtrar por daterange* sobre um único campo de data com limites inclusivos/exclusivos.

Requisição

Headers

Como é uma requisição GET sem corpo, não há Content-Type nem X-Idempotency-Key (idempotência só se aplica a escritas).

Parâmetros de query

Exemplo curl

Período de janeiro inteiro, apenas recebíveis pendentes, ordenados do mais recente para o mais antigo:

curl -X GET "https://api.selectwin.io/v1/receivables/analytics?initdate=2026-01-01T00:00:00Z&enddate=2026-01-31T23:59:59Z&status=pending&sort=descending" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Versão mínima (apenas o período obrigatório):

curl -X GET "https://api.selectwin.io/v1/receivables/analytics?initdate=2026-01-01T00:00:00Z&enddate=2026-01-31T23:59:59Z" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta 200 OK

{
  "list": [
    {
      "id": "rec_01hqzvabc",
      "status": "pending",
      "currency": "BRL",
      "amount": 4850,
      "grossAmount": 5000,
      "anticipationFee": 0,
      "liable": true,
      "chargeProcessingFee": true,
      "expectedOn": "2026-04-20T00:00:00.000Z",
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/receivables/analytics",
      "method": "GET"
    },
    "list": {
      "href": "https://api.selectwin.io/v1/receivables/list",
      "method": "GET"
    }
  }
}

Campos da resposta

Erros

Trate sempre pelo error.code (estável), nunca pela message. A estrutura do envelope está em Tratamento de Erros e a lista completa em Catálogo de Códigos de Erro.

Boas práticas

• Sempre envie initdate e enddate. Não há padrão — a janela é obrigatória. Trate explicitamente o erro invalidParameters quando o período faltar ou estiver invertido.
• Use janelas fechadas e curtas (ex.: um mês por vez) para relatórios previsíveis e respostas rápidas; particione períodos longos em chamadas menores.
• Some valores em centavos (amount/grossAmount são inteiros) e divida por 100 só na exibição. Nunca acumule dinheiro em ponto flutuante.
• Distinga líquido de bruto: grossAmount é o valor antes de taxas; amount é o que efetivamente cai na conta. Para análise de margem, compare os dois e considere anticipationFee.
• Combine status e released para recortes úteis: status=pending mostra o que ainda está por liquidar; released=yes separa o que já foi liberado.
• Não use Analytics para detalhe transacional. Se precisar do transactionId, da parcela ou do description, vá para Listar — a projeção leve daqui não os inclui.
• Não faça polling deste endpoint para detectar mudanças de status; assine os eventos receivable.* por webhook — veja Proibição de Polling.

Veja também

• Recebíveis - Visão Geral — o que é um recebível, modelo do objeto e ciclo de status.
• Recebíveis - Listar — listagem paginada com a projeção completa.
• Convenções da API — dinheiro em centavos, datas ISO 8601 UTC, IDs opacos.
• Catálogo de Códigos de Erro — como tratar error.code.