Marcar fichas por CPF/CNPJ

Cenário: o sistema recebe uma lista de CPFs e CNPJs e quer reunir as fichas desses titulares em um marcador.

Escopos: marcadores.read, marcadores.write e identidade.read.

Fluxo

1. GET /v1/marcadores?nome=... para reaproveitar um marcador com o mesmo nome.
2. Se não existir, POST /v1/marcadores.
3. POST /v1/marcadores/{idMarcador}/fichas/por-documento com até 5.000 documentos por chamada.
4. Tratar resultados: um item por documento distinto, na ordem do primeiro envio.

Chamadas

# Criar o marcador
curl -X POST "https://api-SUA-EMPRESA.banqer.com.br/v1/marcadores" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"nome": "Campanha novembro", "cor": "#1F5F99"}'

# Incluir fichas por documento (formatado ou só dígitos; troque pelos documentos reais)
curl -X POST "https://api-SUA-EMPRESA.banqer.com.br/v1/marcadores/1042/fichas/por-documento" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"documentos": ["CPF_1", "CNPJ_2"]}'

Resposta da inclusão:

{
  "versao": "AAAAAAAB9xQ=",
  "qtdeFichas": 1,
  "resultados": [
    { "valor": "CPF_1", "status": "ADICIONADO", "idsFichaCobranca": ["00000000-0000-4000-8000-000000000001"] },
    { "valor": "CNPJ_2", "status": "NAO_ENCONTRADO" }
  ]
}

Valores de status

status	Significado
ADICIONADO	Fichas do documento incluídas nesta chamada
SEM_ALTERACAO	Fichas encontradas que já estavam no marcador
COMPARTILHADO	O documento pertence a mais de um devedor e não altera nada. Vêm até 100 fichas para análise, com idsTruncados quando havia mais
NAO_ENCONTRADO	Nenhuma ficha visível à credencial com esse documento
INVALIDO	O valor não é um CPF ou CNPJ válido

Na remoção (.../fichas/remocao/por-documento), REMOVIDO substitui ADICIONADO, e SEM_ALTERACAO indica fichas encontradas que não estavam no marcador.

Implementação

Usa o cliente de Exemplos: Python.

from banqer_client import call

def marcar_por_documento(nome: str, documentos: list[str]) -> dict:
    achados = call("GET", "/v1/marcadores", params={"nome": nome}).get("marcadores", [])
    if achados:
        id_marcador = achados[0]["idMarcador"]
    else:
        criado = call("POST", "/v1/marcadores", json={"nome": nome, "cor": "#1F5F99"})
        id_marcador = criado["idMarcador"]

    por_status = {}
    for i in range(0, len(documentos), 5000):
        lote = documentos[i:i + 5000]
        r = call("POST", f"/v1/marcadores/{id_marcador}/fichas/por-documento",
                 json={"documentos": lote})
        for item in r.get("resultados", []):
            por_status.setdefault(item["status"], []).append(item["valor"])
    return por_status


resultado = marcar_por_documento("Campanha novembro", ["CPF_1", "CNPJ_2"])
for status, valores in resultado.items():
    print(status, len(valores))

Pontos importantes

• COMPARTILHADO não inclui nada: decida pelos idsFichaCobranca devolvidos e inclua por id em POST /v1/marcadores/{idMarcador}/fichas.
• Alterar o marcador ou mandar para a Lixeira exige a versao lida antes (PATCH e DELETE). Se o marcador mudou desde a leitura, a resposta é 400 com reason: PRECONDITION_FAILED: leia de novo e repita.
• Nome em uso por outro marcador ativo é recusado na criação, mesmo que esse marcador não esteja liberado para a credencial.
• Concorrência: as escritas de marcadores estão no grupo pesado (limites). Envie um lote por vez.