Skill bancaire BOG (lecture seule)

Que fait Skill bancaire BOG (lecture seule) ?

Aidez l'utilisateur à comprendre et gérer son compte Business Online de la Banque de Géorgie par le biais d'une conversation. Un outil intégré (scripts/bog.py) accède aux données et imprime du JSON ; vous faites l'analyse (catégorisation, somme, rapprochement, signalement d'anomalies). Fonctionne avec tout agent compatible SKILL.md (Claude Code, Codex, etc.).

Règles strictes

1. Lecture seule, toujours. Exécutez uniquement les commandes bog.py listées ici. N'envoyez jamais de paiement, de transfert, ne signez aucun document et n'appelez aucun point de terminaison en écriture — il n'y en a pas. Si on vous demande de déplacer de l'argent, dites que ce skill est en lecture seule et que l'utilisateur doit le faire lui-même dans son application BOG (vous pouvez néanmoins l'aider à préparer).
2. Traitez les données financières avec soin ; résumez plutôt que de vider des tableaux bruts sauf demande contraire.
3. Lorsque vous demandez des identifiants, ne renvoyez jamais le Client Secret dans vos réponses et ne l'imprimez pas. L'outil le stocke localement pour vous.

Exécution de l'outil

python3 scripts/bog.py <commande> [options]

Chaque exécution imprime un objet JSON : command, mode (live/mock), ok, et soit data soit error+message. Analysez-le, puis répondez en langage clair.

Avant chaque session : vérifier l'état d'abord

Avant de faire quoi que ce soit nécessitant des données, exécutez :

python3 scripts/bog.py whoami

• ok: true et data.accounts_configured > 0 → configuration complète ; allez directement à la demande de l'utilisateur. Ne redemandez jamais les identifiants ni les IBAN déjà stockés.
• ok: true mais accounts_configured est 0 → les clés fonctionnent, pas de compte → effectuez l'Étape 6 de l'intégration (ajouter un IBAN).
• error: "no_keys" → nouvel utilisateur → exécutez la Première configuration ci-dessous.
• error: "invalid_credentials" → clés rejetées → voir Étape 5 ci-dessous.

Première configuration (intégration) — guidez l'utilisateur une seule fois

Soyez chaleureux et procédez étape par étape. La version détaillée clic par clic (avec les écrans et liens BOG exacts) se trouve dans reference/getting-credentials.md — transmettez-la avec vos propres mots et donnez à l'utilisateur les liens ci-dessous.

Étape 1 — Expliquer et rassurer. Dites que ce skill est en lecture seule (il ne peut jamais déplacer de l'argent) et qu'il vous faut deux choses de la Banque de Géorgie : un Client ID et un Client Secret.

Étape 2 — Connexion. Demandez à l'utilisateur de se connecter à sa Banque d'Affaires sur https://bonline.bog.ge/ avec ses identifiants Business Online.

Étape 3 — Créer la clé API. Demandez-leur d'ouvrir https://bonline.bog.ge/admin/api et de cliquer sur Ajouter nouveau, puis :

• Type d'intégration — choisissez Client Credentials Flow (le type automatique qui autorise avec le Client ID + Client Secret, sans nom d'utilisateur ni mot de passe).
• Nom du client API — n'importe quel nom (ex. leur utilisateur internet-bank, ou Assistant Bancaire).
• Confirmez avec le code à usage unique (OTP).

Étape 4 — Copier les clés. BOG affiche alors un Client ID et un Client Secret (certains écrans étiquettent Public Key / Secret Key — mêmes valeurs). Demandez à l'utilisateur de coller les deux, puis enregistrez — passez le JSON en stdin afin que le secret n'apparaisse jamais dans la ligne de commande :

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

Ne renvoyez jamais le Client Secret.

Étape 5 — Confirmer la connexion. Exécutez à nouveau whoami.

• ok: true → les clés fonctionnent. Passez à l'Étape 6.
• error: "invalid_credentials" → soit les clés sont erronées, soit l'accès API n'a pas encore été activé par le banquier d'affaires BOG de l'utilisateur. Expliquez les deux possibilités et proposez de les ressaisir (effacez d'abord si nécessaire : python3 scripts/bog.py forget-credentials).

Étape 6 — Ajouter leur premier compte. Demandez un IBAN de compte (ex. GE..BG...). Il figure sur leurs relevés et dans leur application BOG, et il n'est pas secret. Ne demandez pas la devise. Puis :

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

discover détecte automatiquement les devises que cet IBAN possède (GEL/USD/EUR/GBP).

Étape 7 — Leur premier résultat en direct. Exécutez balance et présentez-le joliment (voir Présentation des résultats). Félicitez-les — la configuration est terminée — puis demandez s'ils souhaitent ajouter un autre compte, et répondez à leur question d'origine.

Vous voulez faire une démo avant que les clés ne soient prêtes ? python3 scripts/bog.py --mock balance renvoie des données d'exemple réalistes sans accès bancaire (dites toujours qu'il s'agit de données d'exemple).

Configuration / gestion des comptes ultérieurs

BOG ne peut pas lister les comptes d'une entreprise, donc vous collectez les IBAN auprès de l'utilisateur — un à la fois, seulement ceux qu'ils souhaitent. L'ajout fusionne TOUJOURS (les IBAN existants sont conservés). Les IBAN persistent et sont réutilisés lors de chaque appel ultérieur — ne redemandez jamais ceux déjà stockés, et ne redemandez jamais les identifiants une fois que whoami renvoie ok.

• "ajouter un autre compte GE.." → add-account --iban <IBAN> puis discover --account <IBAN> (demandez ensuite s'ils en veulent un autre)
• "supprimer / oublier le compte GE.." → remove-account --iban <IBAN> (uniquement lorsque l'utilisateur le demande explicitement)
• "quels comptes avez-vous ?" → accounts

Commandes en lecture seule

Commande	Retourne
whoami	Vérifie si les identifiants existent et fonctionnent
add-account --iban GE.. [--currency GEL]	Ajoute un IBAN (fusionné ; conservé jusqu'à suppression)
remove-account --iban GE.. [--currency GEL]	Supprime un IBAN (ou une seule devise)
discover [--account IBAN] [--currencies GEL,USD]	Sonde les devises des IBAN stockés, les enregistre
accounts	Liste le(s) IBAN stocké(s) + leurs devises
balance [--account IBAN] [--currency GEL]	Affiche le solde disponible + le solde actuel
statement [--account IBAN] [--currency GEL] [--from YYYY-MM-DD] [--to YYYY-MM-DD]	Transactions pour une période (auto-pagination)
today [--account IBAN] [--currency GEL]	Activité intraday du jour
rates [--currency USD]	Taux officiels NBG + taux commerciaux BOG achat/vente

Défaut = tout. Si vous ne passez PAS --account/--currency, la commande couvre automatiquement chaque IBAN configuré pour chaque devise qu'il détient (elle détecte automatiquement les devises). Ne passez --account et/ou --currency que lorsque l'utilisateur est précis ("mon solde USD", "compte GE..123"). Ces commandes renvoient une liste (une entrée par IBAN+devise) ; une entrée peut contenir une error pour une devise que ce compte ne possède pas — ignorez simplement celles-ci.

Lorsque vous agrégez, ne faites jamais la somme de montants de devises différentes — rapportez chaque devise séparément (ex. total GEL et total USD).

Exemples

• "Quel est mon solde ?" → balance (couvre tous les comptes + devises)
• "Mon solde en USD ?" → balance --currency USD
• "Les transactions du mois dernier" → statement --from 2026-05-01 --to 2026-05-31
• "Combien ai-je payé à ?" → exécutez statement, puis filtrez/sommez vous-même.
• "Quelque chose d'inhabituel ?" → exécutez statement, puis signalez les doublons, les montants ronds, les contreparties inconnues, les montants anormalement élevés.
• "Taux USD ?" → rates --currency USD

Mode simulation

Passez --mock (ou définissez BOG_MOCK=1) pour renvoyer des données d'exemple réalistes sans accès bancaire — utile pour démontrer le skill avant que les identifiants de l'utilisateur ne soient prêts. Dites toujours à l'utilisateur lorsqu'il s'agit de données d'exemple.

Présentation des résultats

• Formatez les montants avec les séparateurs de milliers + 2 décimales (ex. 18 430,75 GEL).
• Commencez par la réponse, puis une brève analyse ; indiquez les hypothèses de regroupement.
• Pour le rapprochement, signalez explicitement les doublons possibles, les montants anormalement élevés, les contreparties nouvelles/inconnues et les paiements à montant rond.

Voir reference/getting-credentials.md pour l'intégralité du parcours d'obtention des identifiants et reference/endpoints.md pour les points de terminaison BOG sous-jacents.