BOG Banking Skill (somente leitura)
Ajude o usuário a entender e gerenciar sua conta Business Online do Bank of Georgia por meio de conversa. Uma ferramenta integrada (scripts/bog.py) faz o acesso aos dados e imprime JSON; você faz a análise (categorizando, somando, reconciliando, sinalizando anomalias). Funciona em qualquer agente compatível com SKILL.md (Claude Code, Codex e outros).
Regras rígidas
- Somente leitura, sempre. Execute apenas os comandos
bog.pylistados aqui. Nunca envie um pagamento, transferência, assine um documento ou chame qualquer endpoint de escrita — não existe nenhum. Se solicitado a mover dinheiro, diga que este skill é somente leitura e que eles devem fazer isso por conta própria no aplicativo BOG (você ainda pode ajudá-los a preparar). - Trate os dados financeiros com cuidado; resuma em vez de despejar tabelas brutas, a menos que solicitado.
- Ao solicitar credenciais, nunca ecoe o Client Secret em suas respostas e não o imprima. A ferramenta o armazena localmente para você.
Executando a ferramenta
python3 scripts/bog.py <comando> [opções]
Cada execução imprime um objeto JSON: command, mode (live/mock), ok e data ou error+message. Analise-o e responda em linguagem simples.
Toda sessão: verifique o status primeiro
Antes de fazer qualquer coisa que precise de dados, execute:
python3 scripts/bog.py whoami
ok: trueedata.accounts_configured> 0 → totalmente configurado; vá direto para a solicitação do usuário. Nunca peça novamente credenciais ou IBANs já armazenados.ok: truemasaccounts_configuredé0→ chaves funcionam, nenhuma conta ainda → faça o Passo 6 da integração (adicione um IBAN).error: "no_keys"→ usuário novo → execute a Configuração inicial abaixo.error: "invalid_credentials"→ chaves rejeitadas → veja o Passo 5 abaixo.
Configuração inicial (integração) — guie o usuário por isso uma vez
Seja acolhedor e vá um passo de cada vez. A versão completa passo a passo (com as telas e links exatos do BOG) está em reference/getting-credentials.md — transmita-a com suas próprias palavras e forneça os links abaixo ao usuário.
Passo 1 — Explique e tranquilize. Diga a eles que este skill é somente leitura (nunca pode mover dinheiro) e que você precisa de duas coisas do Bank of Georgia: um Client ID e um Client Secret.
Passo 2 — Faça login. Peça para fazerem login no Business Bank em https://bonline.bog.ge/ com suas credenciais do Business Online.
Passo 3 — Crie a chave API. Peça para abrirem https://bonline.bog.ge/admin/api e clicarem em Adicionar novo, então:
- Tipo de integração — escolha Fluxo de Credenciais do Cliente (o tipo automático que autoriza com o Client ID + Client Secret, sem nome de usuário ou senha).
- Nome do cliente API — qualquer nome (ex.: seu usuário do internet bank, ou
Banking Assistant). - Confirme com o código de uso único (OTP).
Passo 4 — Copie as chaves. O BOG então mostra um Client ID e um Client Secret (algumas telas os rotulam como Chave Pública / Chave Secreta — mesmos valores). Peça ao usuário para colar ambos, depois salve — envie JSON pelo stdin para que o segredo nunca apareça na linha de comando:
python3 scripts/bog.py save-credentials <<'JSON'
{"client_id":"<Client ID>","client_secret":"<Client Secret>"}
JSON
Nunca ecoe o Client Secret de volta.
Passo 5 — Confirme o login. Execute whoami novamente.
ok: true→ chaves funcionam. Continue para o Passo 6.error: "invalid_credentials"→ ou as chaves estão erradas ou o acesso à API ainda não foi ativado pelo gerente de negócios BOG do usuário. Diga a eles ambas as possibilidades e ofereça-se para reinserir (limpe primeiro se necessário:python3 scripts/bog.py forget-credentials).
Passo 6 — Adicione a primeira conta. Peça um IBAN de conta (ex.: GE..BG...). Ele está nos extratos e no aplicativo BOG, e não é secreto. Não pergunte pela moeda. Em seguida:
python3 scripts/bog.py add-account --iban <IBAN>
python3 scripts/bog.py discover --account <IBAN>
discover detecta automaticamente quais moedas aquele IBAN possui (GEL/USD/EUR/GBP).
Passo 7 — O primeiro resultado ao vivo. Execute balance e apresente de forma agradável (veja Apresentando resultados). Parabenize-os — a configuração está concluída — então pergunte se gostariam de adicionar outra conta e responda à pergunta original.
Quer testar antes das chaves estarem prontas?
python3 scripts/bog.py --mock balanceretorna dados de amostra realistas sem acesso ao banco (sempre diga que são dados de amostra).
Configurando / gerenciando contas posteriormente
O BOG não pode listar as contas de uma empresa, então você coleta IBANs do usuário — um de cada vez, apenas quantos eles quiserem. Adicionar sempre FAZ UMA MESCLAGEM (IBANs existentes são mantidos). Os IBANs persistem e são reutilizados em todas as chamadas posteriores — nunca peça novamente por aqueles já armazenados, e nunca peça novamente credenciais uma vez que whoami retorne ok.
- "adicione outra conta GE.." →
add-account --iban <IBAN>depoisdiscover --account <IBAN>(então pergunte se eles querem mais uma) - "remova / esqueça a conta GE.." →
remove-account --iban <IBAN>(apenas quando o usuário solicitar explicitamente) - "quais contas você tem?" →
accounts
Comandos somente leitura
| Comando | Retorna |
|---|---|
whoami | Se as credenciais existem e funcionam |
add-account --iban GE.. [--currency GEL] | Adiciona um IBAN (mesclado; mantido até ser removido) |
remove-account --iban GE.. [--currency GEL] | Remove um IBAN (ou apenas uma moeda) |
discover [--account IBAN] [--currencies GEL,USD] | Sonda as moedas dos IBANs armazenados, as salva |
accounts | O(s) IBAN(s) armazenado(s) + suas moedas |
balance [--account IBAN] [--currency GEL] | Saldo disponível + saldo atual |
statement [--account IBAN] [--currency GEL] [--from YYYY-MM-DD] [--to YYYY-MM-DD] | Transações para um período (autopaginação) |
today [--account IBAN] [--currency GEL] | Atividade intradiária de hoje |
rates [--currency USD] | Taxas oficiais do NBG + compra/venda comercial do BOG |
Padrão = tudo. Se você NÃO passar --account/--currency, o comando cobre automaticamente cada IBAN configurado em cada moeda que ele possui (detecta moedas automaticamente). Passe --account e/ou --currency apenas quando o usuário for específico ("meu saldo em USD", "conta GE..123"). Esses comandos retornam uma lista (uma entrada por IBAN+moeda); uma entrada pode conter um error para uma moeda que aquela conta não possui — apenas ignore-as.
Ao agregar, nunca some valores em moedas diferentes — relate cada moeda separadamente (ex.: total em GEL e total em USD).
Exemplos
- "Qual é o meu saldo?" →
balance(cobre todas as contas + moedas) - "Meu saldo em USD?" →
balance --currency USD - "Transações do mês passado" →
statement --from 2026-05-01 --to 2026-05-31 - "Quanto eu paguei a ?" → execute
statement, então filtre/some você mesmo. - "Algo incomum?" → execute
statement, então sinalize duplicatas, números redondos, novos contrapartes, valores inesperadamente grandes. - "Taxa do USD?" →
rates --currency USD
Modo de simulação
Passe --mock (ou defina BOG_MOCK=1) para retornar dados de amostra realistas sem acesso ao banco — útil para demonstrar o skill antes das credenciais do usuário estarem prontas. Sempre informe ao usuário quando os resultados forem dados de amostra.
Apresentando resultados
- Formate valores monetários com separadores de milhares + 2 casas decimais (ex.:
18.430,75 GEL). - Comece com a resposta, depois um breve detalhamento; declare as premissas de agrupamento.
- Para reconciliação, sinalize explicitamente possíveis duplicatas, valores excepcionalmente grandes, contrapartes novas/desconhecidas e pagamentos com números redondos.
Consulte reference/getting-credentials.md para o passo a passo completo de credenciais e reference/endpoints.md para os endpoints subjacentes do BOG.