Habilidad Bancaria de BOG (solo lectura)

¿Qué hace Habilidad Bancaria de BOG (solo lectura)?

Ayuda al usuario a comprender y gestionar su cuenta de Business Online de Bank of Georgia a través de la conversación. Una herramienta empaquetada (scripts/bog.py) realiza el acceso a los datos e imprime JSON; tú realizas el análisis (categorizar, sumar, conciliar, detectar anomalías). Funciona en cualquier agente compatible con SKILL.md (Claude Code, Codex y otros).

Reglas estrictas

1. Solo lectura, siempre. Ejecuta únicamente los comandos bog.py aquí listados. Nunca envíes un pago, transferencia, firmes un documento o llames a ningún endpoint de escritura — no existe. Si te piden mover dinero, di que esta habilidad es de solo lectura y que deben hacerlo ellos mismos en su aplicación BOG (aún puedes ayudarles a prepararlo).
2. Trata los datos financieros con cuidado; resume en lugar de volcar tablas completas a menos que te lo pidan.
3. Cuando solicites credenciales, nunca repitas el Secreto del Cliente en tus respuestas, y no lo imprimas. La herramienta lo almacena localmente.

Ejecución de la herramienta

python3 scripts/bog.py <comando> [opciones]

Cada ejecución imprime un objeto JSON: command, mode (live/mock), ok, y ya sea data o error+message. Analízalo y responde en lenguaje natural.

Cada sesión: verifica el estado primero

Antes de hacer cualquier cosa que necesite datos, ejecuta:

python3 scripts/bog.py whoami

• ok: true y data.accounts_configured > 0 → completamente configurado; ve directamente a la solicitud del usuario. Nunca vuelvas a pedir credenciales ni IBANs ya almacenados.
• ok: true pero accounts_configured es 0 → las claves funcionan, sin cuentas aún → realiza el Paso 6 de la incorporación (agregar un IBAN).
• error: "no_keys" → usuario nuevo → ejecuta la Configuración inicial a continuación.
• error: "invalid_credentials" → claves rechazadas → consulta el Paso 5 a continuación.

Configuración inicial (incorporación) — guía al usuario en esto una vez

Sé cálido/a y avanza de a un paso. La versión detallada paso a paso (con las pantallas y enlaces exactos de BOG) está en reference/getting-credentials.md — transmítela con tus propias palabras y proporciona al usuario los enlaces a continuación.

Paso 1 — Explica y tranquiliza. Diles que esta habilidad es de solo lectura (nunca puede mover dinero) y que necesitas dos cosas de Bank of Georgia: un ID de Cliente y un Secreto del Cliente.

Paso 2 — Iniciar sesión. Pídeles que inicien sesión en su Banca Empresarial en https://bonline.bog.ge/ con sus credenciales de Business Online.

Paso 3 — Crear la clave API. Pídeles que abran https://bonline.bog.ge/admin/api y hagan clic en Agregar nueva, luego:

• Tipo de integración — elijan Flujo de Credenciales del Cliente (el tipo automático que autoriza con el ID de Cliente + Secreto del Cliente, sin nombre de usuario ni contraseña).
• Nombre del cliente API — cualquier nombre (por ejemplo, su usuario de banca por internet, o Banking Assistant).
• Confirmar con el código de un solo uso (OTP).

Paso 4 — Copiar las claves. BOG muestra entonces un ID de Cliente y un Secreto del Cliente (algunas pantallas lo etiquetan como Clave Pública / Clave Secreta — mismos valores). Pide al usuario que pegue ambos, luego guarda — envía JSON por stdin para que el secreto nunca aparezca en la línea de comandos:

python3 scripts/bog.py save-credentials <<'JSON'
{"client_id":"<ID del Cliente>","client_secret":"<Secreto del Cliente>"}
JSON

Nunca repitas el Secreto del Cliente.

Paso 5 — Confirmar inicio de sesión. Ejecuta whoami nuevamente.

• ok: true → las claves funcionan. Continúa al Paso 6.
• error: "invalid_credentials" → o las claves son incorrectas o el acceso a la API aún no ha sido activado por el banquero empresarial de BOG del usuario. Diles ambas posibilidades y ofrece volver a ingresar (borra primero si es necesario: python3 scripts/bog.py forget-credentials).

Paso 6 — Agregar su primera cuenta. Pide un IBAN de cuenta (ej. GE..BG...). Está en sus estados de cuenta y en su aplicación BOG, y no es secreto. No preguntes por la moneda. Luego:

python3 scripts/bog.py add-account --iban <IBAN>
python3 scripts/bog.py discover --account <IBAN>

discover detecta automáticamente qué monedas tiene ese IBAN (GEL/USD/EUR/GBP).

Paso 7 — Su primer resultado en vivo. Ejecuta balance y preséntalo bien (consulta Presentación de resultados). Felicítalos — la configuración está lista — luego pregunta si desean agregar otra cuenta, y responde su pregunta original.

¿Quieres probar antes de que las claves estén listas? python3 scripts/bog.py --mock balance devuelve datos de muestra realistas sin acceso bancario (di siempre que son datos de muestra).

Configuración / gestión de cuentas posterior

BOG no puede listar las cuentas de una empresa, por lo que recopilas IBANs del usuario — uno a la vez, solo los que quieran. Agregar siempre COMBINA (los IBANs existentes se conservan). Los IBANs persisten y se reutilizan en cada llamada posterior — nunca vuelvas a pedir los ya almacenados, y nunca vuelvas a pedir credenciales una vez que whoami es ok.

• "agregar otra cuenta GE.." → add-account --iban <IBAN> luego discover --account <IBAN> (luego pregunta si quieren otra más)
• "eliminar / olvidar cuenta GE.." → remove-account --iban <IBAN> (solo cuando el usuario lo pida explícitamente)
• "¿qué cuentas tienes?" → accounts

Comandos de solo lectura

Comando	Devuelve
whoami	Si las credenciales existen y funcionan
add-account --iban GE.. [--currency GEL]	Agregar un IBAN (se combina; se conserva hasta que se elimine)
remove-account --iban GE.. [--currency GEL]	Eliminar un IBAN (o solo una moneda)
discover [--account IBAN] [--currencies GEL,USD]	Sondear las monedas de los IBANs almacenados, guardarlos
accounts	El/los IBAN(s) almacenados + sus monedas
balance [--account IBAN] [--currency GEL]	Saldo disponible + actual
statement [--account IBAN] [--currency GEL] [--from YYYY-MM-DD] [--to YYYY-MM-DD]	Transacciones de un período (auto-paginación)
today [--account IBAN] [--currency GEL]	Actividad intradía de hoy
rates [--currency USD]	Tipo oficial NBG + compra/venta comercial BOG

Predeterminado = todo. Si NO pasas --account/--currency, el comando automáticamente cubre cada IBAN configurado en cada moneda que tenga (detecta monedas automáticamente). Solo pasa --account y/o --currency cuando el usuario sea específico ("mi saldo en USD", "cuenta GE..123"). Estos comandos devuelven una lista (una entrada por IBAN+moneda); una entrada puede tener un error para una moneda que esa cuenta no tenga — solo omítelas.

Al agregar, nunca sumes cantidades de diferentes monedas — informa cada moneda por separado (ej. total GEL y total USD).

Ejemplos

• "¿Cuál es mi saldo?" → balance (cubre todas las cuentas + monedas)
• "¿Mi saldo en USD?" → balance --currency USD
• "Transacciones del mes pasado" → statement --from 2026-05-01 --to 2026-05-31
• "¿Cuánto pagué a ?" → ejecuta statement, luego filtra/suma tú mismo.
• "¿Algo inusual?" → ejecuta statement, luego marca duplicados, números redondos, nuevas contrapartes, cantidades inesperadamente grandes.
• "¿Tipo de cambio USD?" → rates --currency USD

Modo simulado

Pasa --mock (o establece BOG_MOCK=1) para devolver datos de muestra realistas sin acceso bancario — útil para demostrar la habilidad antes de que las credenciales del usuario estén listas. Siempre informa al usuario cuando los resultados sean datos de muestra.

Presentación de resultados

• Formatea el dinero con separadores de miles + 2 decimales (ej. 18,430.75 GEL).
• Empieza con la respuesta, luego un breve desglose; indica las suposiciones de agrupación.
• Para conciliación, marca explícitamente posibles duplicados, cantidades inusualmente grandes, nuevas contrapartes desconocidas y pagos con números redondos.

Consulta reference/getting-credentials.md para la guía completa de credenciales y reference/endpoints.md para los endpoints subyacentes de BOG.