Listar fichas em atraso

Cenário: você precisa de todas as fichas com atraso acima de um patamar, em um determinado produto, para alimentar um motor de propostas ou um data warehouse.

Escopo necessário: fichas.read.

Fluxo

1. GET /v1/fichas com filtros (idProduto, atrasoMin, atrasoMax, pageSize=200).
2. Iterar enquanto vier nextPageToken.
3. Acumular ou processar cada lote.

A API limita pageSize em 200. Para 50 mil fichas, isso são 250 chamadas. Cada chamada é rápida (típico < 200ms), o gargalo é a serialização do seu lado.

Implementação

Python

from banqer_client import paginar

def fichas_em_atraso(id_produto: int, atraso_min: int = 90):
    """Itera por todas as fichas em atraso, paginadas automaticamente."""
    return paginar(
        "/v1/fichas",
        params={
            "idProduto": id_produto,
            "atrasoMin": atraso_min,
        },
        key="fichas",
    )

# Uso: extrair para CSV
import csv
with open("fichas_atraso_90mais.csv", "w", newline="", encoding="utf-8") as f:
    writer = csv.writer(f)
    writer.writerow(["id_exibicao", "atraso", "saldo", "uf", "situacao"])
    total = 0
    for ficha in fichas_em_atraso(id_produto=23, atraso_min=90):
        writer.writerow([
            ficha["idFichaCobrancaExibicao"],
            ficha["atraso"],
            ficha.get("saldoDevedor", 0),
            ficha.get("uf", ""),
            ficha.get("situacaoDivida", ""),
        ])
        total += 1
print(f"Exportadas {total} fichas.")

JavaScript

import { paginar } from './banqer-client.mjs';
import { writeFile } from 'node:fs/promises';

async function exportarFichasEmAtraso(idProduto, atrasoMin) {
  const linhas = ['id_exibicao,atraso,saldo,uf,situacao'];
  let total = 0;

  for await (const ficha of paginar('/v1/fichas', {
    idProduto,
    atrasoMin,
  })) {
    linhas.push([
      ficha.idFichaCobrancaExibicao,
      ficha.atraso,
      ficha.saldoDevedor ?? 0,
      ficha.uf ?? '',
      ficha.situacaoDivida ?? '',
    ].join(','));
    total++;
  }

  await writeFile('fichas_atraso.csv', linhas.join('\n'), 'utf-8');
  console.log(`Exportadas ${total} fichas.`);
}

await exportarFichasEmAtraso(23, 90);

Pontos importantes

• Use pageSize=200 (o máximo) para reduzir o número de chamadas. Pedir mais não retorna mais: o servidor reduz silenciosamente.
• Filtre no servidor sempre que possível: filtros como atrasoMin, atrasoMax, uf, idProduto, emCobranca são aplicados antes da paginação. Filtrar no seu lado significa baixar dados que serão descartados.
• O cursor expira? Não. O cursor codifica o último ID lido; você pode pausar a iteração e retomar mais tarde com o mesmo pageToken. Mas dados podem ter sido inseridos entre as duas execuções e ficarão de fora.
• Não confie em ordenação por outro campo: o servidor ordena por idFichaCobranca (UUID) crescente, e essa é a única ordem garantida. Se precisar ordenar por atraso ou saldo, ordene no seu lado após coletar.
• Snapshots consistentes: a API não oferece transação de leitura. Para um snapshot exato, faça a coleta dentro de uma janela curta (alguns minutos) e aceite uma margem de variação.

Filtros disponíveis em /v1/fichas

Todos opcionais e combináveis:

Parâmetro	Tipo	Significado
idProduto	int	Produto da ficha (sua credencial só vê produtos da sua lista)
idCredor	int	Credor do produto
idCarteira	int	Carteira (faixa de atraso)
atrasoMin	int	Atraso mínimo em dias
atrasoMax	int	Atraso máximo em dias
uf	string	UF (2 letras maiúsculas: BA, ES)
idSituacaoDivida	int	1 Em Atraso, 2 Em Dia, 3 Finalizado
emCobranca	bool	Se true, apenas fichas atualmente em cobrança
pageSize	int	Tamanho da página (padrão 50, máximo 200)
pageToken	string	Cursor da próxima página

Consulte a Referência da API para a lista completa e tipos exatos de cada filtro.