FiscAPI Local SDK

SDK officiel pour connecter une installation locale (FiscAPI Solution / FiscAPI ERP) à FiscAPI Cloud pour:

• la récupération de la clé AI Gateway,
• la synchronisation des actions IA,
• la consommation des crédits IA,
• la demande de recharges par facture.

Package npm: @fiscapi-node/local-sdk

Installation

npm install @fiscapi-node/local-sdk

Architecture fonctionnelle

1. Admin Cloud configure les actions IA et crée un token local (AI_LOCAL).
2. Application locale initialise le SDK avec ce token.
3. L’application locale:
   • synchronise getSession() (clé gateway + état crédits),
   • synchronise getActions() (catalogue d’actions IA),
   • débite consumeCredits() avant chaque opération IA,
   • déclenche requestRechargeInvoice() si crédits insuffisants.

Où sont stockées et récupérées les actions IA ?

Les actions IA sont récupérées depuis FiscAPI Cloud:

• source admin principale: PlatformSetting clé AI_LOCAL_ACTIONS,
• fallback stable: DEFAULT_LOCAL_AI_ACTIONS (code serveur),
• endpoint SDK: GET /api/v1/ai/actions.

Donc elles sont prévisibles (liste standard) mais pilotables par l’admin (surcharges dans la console).

Setup Admin (console Cloud)

Étape 1 — Créer un token local

• Menu: Admin > IA > Accès IA local
• Action: créer un token scope AI_LOCAL
• Résultat: clé sk_live_... (visible une seule fois)

Étape 2 — Configurer les actions IA locales

• Menu: Admin > IA > Actions IA locales
• Action: définir key, instructions, costCredits, enabled
• Résultat: ce catalogue sera servi au SDK local

Étape 3 — Suivre ventes/recharges locales

• Menu: Admin > Billing
• Onglet Recharges (factures): validation des demandes (APPROVE/REJECT)
• Onglet Solutions locales: vue ventes, solde et consommation IA locale

Intégration locale (workflow recommandé)

import { LocalAiClient } from '@fiscapi-node/local-sdk';

const client = new LocalAiClient({
  token: process.env.FISCAPI_LOCAL_TOKEN!,
  baseUrl: 'https://www.fiscapi.com',
});

1) Synchroniser la session Cloud

const session = await client.getSession();
// session.gateway.apiKey => à stocker localement en base chiffrée
// session.gateway.baseUrl => URL gateway IA (fallback auto: https://ai-gateway.vercel.sh/v1)

2) Synchroniser les actions IA

const { actions } = await client.getActions();
// injecter/mettre à jour la table locale des actions
// chaque action inclut aussi model + modelSource (résolution cloud)

3) Débiter avant exécution IA

await client.consumeCredits({ action: 'ocr_invoice', units: 1 });

Si l’API renvoie 402 INSUFFICIENT_CREDITS, bloquer l’action et ouvrir l’écran de recharge.

4) Recharger par facture

await client.requestRechargeInvoice({
  amount: 500,
  message: 'Recharge agence Cotonou',
});

Puis suivre:

const { requests } = await client.listRechargeRequests();

API du SDK

new LocalAiClient(config | token)

const client = new LocalAiClient({
  token: 'sk_live_xxx',
  baseUrl: 'https://www.fiscapi.com',
  timeout: 30000,
});

getSession()

Retourne clé gateway + URL gateway + crédits + policy. Inclut aussi models.default et models.byAction (modèle effectif + source).

Le SDK normalise automatiquement l’URL gateway:

• priorité session.gateway.baseUrl,
• fallback session.gatewayBaseUrl,
• fallback URL si l’ancien backend renvoie gateway.source = "db" / "env" (non URL).

resolveSessionGatewayBaseUrl(session)

Helper exporté pour récupérer une URL gateway valide à partir d’une session.

getActions()

Retourne les actions IA tenant/local avec:

• instructions, costCredits, enabled
• model (modèle effectif)
• modelSource (clé/source utilisée: ex AI_GATEWAY_MODEL_OCR_INVOICE, AI_GATEWAY_MODEL, env:*, fallback)

consumeCredits({ units, action })

Débite les crédits avant une action IA locale.

getCreditsBalance()

Retourne le solde de crédits global.

getCreditPacks()

Retourne le catalogue des packs (/api/v1/credits/packs).

requestRechargeInvoice({ amount, message })

Crée une demande de recharge avec facture (POST /api/billing/recharges).

listRechargeRequests()

Liste les demandes de recharge du tenant (GET /api/billing/recharges).

Actions IA standards (référentiel)

Ces actions sont les clés stables à supporter dans FiscAPI local:

• eliana_chat
• invoice
• proforma
• vigilance
• ocr_expense
• ocr_invoice

Si une action est ajoutée/modifiée côté admin, le SDK/README doit être mis à jour à la release suivante.

Gestion d’erreurs

Le SDK lève FiscApiLocalError avec:

• status: HTTP status (ex: 401, 402, 403, 422)
• code: code métier (ex: INSUFFICIENT_CREDITS, UNAUTHORIZED)
• details: payload technique si disponible

Bonnes pratiques d’exploitation

• Chiffrer localement session.gateway.apiKey (jamais en clair côté front).
• Re-synchroniser les actions IA au démarrage + tâche planifiée (ex: toutes les 24h).
• Débiter systématiquement les crédits avant exécution IA.
• Logger localement action, units, user, timestamp, requestId.
• En cas de 402, forcer un passage par le flux de recharge.