Consultar devedor por CPF/CNPJ

Cenário: o titular envia o CPF/CNPJ para um chatbot de negociação. O chatbot precisa identificar as fichas associadas, mostrar saldo agregado e oferecer opções de acordo.

Escopos necessários: identidade.read e fichas.read. Se quiser também mostrar contratos/pagamentos: financeiro.read.

Fluxo

1. Receber o CPF/CNPJ do canal (WhatsApp, voz, web).
2. GET /v1/pessoas:porDocumento?documento={cpf} para encontrar a pessoa e suas fichas.
3. Para cada ficha retornada, GET /v1/fichas/{id} para obter saldo e atraso.
4. Compor a mensagem de resposta com os dados agregados.

Em V1, o endpoint :porDocumento já retorna a lista de fichas com idProduto e nomeProduto, evitando uma chamada extra para listar todas as fichas.

Implementação

Python

from banqer_client import call, BanqerError

def consultar_devedor(documento: str) -> dict:
    """Recebe CPF (so digitos) e retorna dict com fichas + saldo total."""
    try:
        pessoa = call("GET", "/v1/pessoas:porDocumento",
                      params={"documento": documento})
    except BanqerError as e:
        if e.status_code == 404:
            return {"encontrado": False}
        raise

    # Para cada ficha, busca o saldo.
    fichas = []
    saldo_total = 0
    for f in pessoa.get("fichas", []):
        detalhe = call("GET", f"/v1/fichas/{f['idFichaCobranca']}")
        saldo = detalhe.get("saldoDevedor", 0)
        saldo_total += saldo
        fichas.append({
            "id_exibicao": detalhe["idFichaCobrancaExibicao"],
            "produto": f["nomeProduto"],
            "saldo": saldo,
            "atraso": detalhe.get("atraso", 0),
            "situacao": detalhe.get("situacaoDivida"),
        })

    return {
        "encontrado": True,
        "id_pessoa": pessoa["idPessoa"],
        "fichas": fichas,
        "saldo_total": saldo_total,
    }


# Uso
resultado = consultar_devedor("10167910701")
if not resultado["encontrado"]:
    print("Documento nao localizado na base.")
else:
    print(f"Encontradas {len(resultado['fichas'])} ficha(s).")
    print(f"Saldo total: R$ {resultado['saldo_total']:.2f}")
    for f in resultado["fichas"]:
        print(f"  - Ficha {f['id_exibicao']} ({f['produto']}): "
              f"R$ {f['saldo']:.2f}, atraso {f['atraso']} dias, "
              f"situacao: {f['situacao']}")

JavaScript

import { call, BanqerError } from './banqer-client.mjs';

export async function consultarDevedor(documento) {
  let pessoa;
  try {
    pessoa = await call('GET', '/v1/pessoas:porDocumento', { params: { documento } });
  } catch (e) {
    if (e instanceof BanqerError && e.status === 404) {
      return { encontrado: false };
    }
    throw e;
  }

  const fichas = [];
  let saldoTotal = 0;
  for (const f of pessoa.fichas ?? []) {
    const detalhe = await call('GET', `/v1/fichas/${f.idFichaCobranca}`);
    const saldo = detalhe.saldoDevedor ?? 0;
    saldoTotal += saldo;
    fichas.push({
      idExibicao: detalhe.idFichaCobrancaExibicao,
      produto: f.nomeProduto,
      saldo,
      atraso: detalhe.atraso ?? 0,
      situacao: detalhe.situacaoDivida,
    });
  }

  return {
    encontrado: true,
    idPessoa: pessoa.idPessoa,
    fichas,
    saldoTotal,
  };
}

// Uso
const r = await consultarDevedor('10167910701');
if (!r.encontrado) {
  console.log('Documento nao localizado.');
} else {
  console.log(`Encontradas ${r.fichas.length} ficha(s).`);
  console.log(`Saldo total: R$ ${r.saldoTotal.toFixed(2)}`);
  for (const f of r.fichas) {
    console.log(`  - Ficha ${f.idExibicao} (${f.produto}): R$ ${f.saldo.toFixed(2)}, ` +
                `atraso ${f.atraso} dias, situacao: ${f.situacao}`);
  }
}

Quando enriquecer com contatos

Se sua integração precisa também de telefones ou e-mails (por exemplo, para confirmar o canal de contato preferido), adicione contatos.read à sua credencial. Com esse modificador, a resposta de /v1/pessoas/{idPessoa} já vem com os arrays telefones, emails e enderecos populados:

# Apenas com identidade.read: arrays vazios
# Com identidade.read + contatos.read: arrays preenchidos
detalhe = call("GET", f"/v1/pessoas/{resultado['id_pessoa']}")
celulares = [t for t in detalhe.get("telefones", []) if t.get("celular")]

Pontos importantes

• Normalize o documento antes de enviar: remova pontos, traços e barras. A API espera apenas dígitos (10167910701, não 101.679.107-01).
• CPF inexistente devolve 404: trate BanqerError com status_code == 404 como caminho normal de "não localizado", não como erro.
• Múltiplos produtos: uma mesma pessoa pode ter fichas em mais de um produto Banqer. Sua credencial vai enxergar apenas as fichas dos produtos para os quais ela foi habilitada.
• LGPD: registre no seu próprio sistema o canal de origem da consulta (canal do chatbot, identificador do atendente, timestamp). A API não registra esse contexto, apenas a chamada autenticada.