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,
• l'activation des licences produit (SFE / ERP / Solution),
• la remontée des erreurs applicatives locales vers le centre technique Cloud, sans envoi d'email par l'application locale.

Package npm: @fiscapi-node/local-sdk

Installation

npm install @fiscapi-node/local-sdk

Architecture fonctionnelle

1. Admin Cloud crée une clé produit pk_live_... (activation locale).
2. Admin Cloud crée un token IA local sk_live_... (scope AI_LOCAL).
3. Application locale active la licence au premier démarrage via LocalProductClient.
4. Application locale initialise le SDK IA via LocalAiClient pour:
   • synchroniser getSession() (clé gateway + état crédits),
   • synchroniser getActions() (catalogue d’actions IA),
   • exécuter les actions cloud generator, tools, ocrAnalysis, imagen,
   • débiter consumeCredits() avant chaque opération IA,
   • déclencher requestRechargeInvoice() si crédits insuffisants.
5. Application locale remonte ses erreurs via reportError() / reportMessage() au lieu d'envoyer des emails.

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 IA

• 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

Étape 4 — Émettre une clé produit locale

• Menu: Admin > IA > Licences locales
• Action: créer une clé produit pk_live_... avec:
  • type: FISCAPI SFE LOCAL, FISCAPI ERP, FISCAPI SOLUTION
  • durée: 1 an, 2 ans, 5 ans, 10 ans, illimité (selon le type)
• Résultat: clé pk_live_... (visible une seule fois)

Intégration locale (workflow recommandé)

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

const aiClient = new LocalAiClient({
  token: process.env.FISCAPI_LOCAL_AI_TOKEN!,
});

const productClient = new LocalProductClient({
  token: process.env.FISCAPI_PRODUCT_KEY!,
});

1) Activer la licence produit (premier lancement)

const activation = await productClient.activate({
  machineFingerprint: 'mac-001',
  installationName: 'Site Cotonou',
  appEdition: 'ERP',
  appVersion: '1.0.0',
  instanceId: 'local-uuid',
});

2) Vérifier l'état de licence

const session = await productClient.getSession();
// session.license.licenseScopes => scopes autorisés
// session.license.expiresAt => date d'expiration

3) Synchroniser la session IA Cloud

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

4) Synchroniser les actions IA

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

5) Débiter avant exécution IA

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

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

6) Recharger par facture

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

Puis suivre:

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

7) Remonter les erreurs locales

try {
  await runLocalFiscalJob();
} catch (error) {
  await productClient.reportError(error, {
    context: 'Synchronisation fiscale locale',
    severity: 'HIGH',
    appName: 'FiscAPI ERP Local',
    appVersion: '1.2.0',
    installationName: 'Site Cotonou',
    instanceId: 'local-uuid',
  });
  throw error;
}

Pour un service Node, le SDK peut aussi capturer les erreurs globales:

const stopReporting = productClient.installGlobalErrorHandlers({
  appName: 'FiscAPI Solution',
  appVersion: '1.2.0',
  installationName: 'Agence Cotonou',
});

Les rapports sont envoyés à POST /api/v1/local-errors, authentifiés par la clé produit pk_live_... ou le token local sk_live_..., puis stockés dans le centre technique admin. L'endpoint n'envoie pas d'email.

API du SDK

new LocalAiClient(config | token)

const client = new LocalAiClient({
  token: 'sk_live_xxx',
  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é aux valeurs gateway renvoyées par la session,
• fallback session.gatewayBaseUrl,
• fallback URL si l’ancien backend renvoie seulement 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)

generator({ prompt, outputFormat, schema })

Génère du texte ou du JSON structuré via FiscAPI Cloud.

const generated = await aiClient.generator({
  prompt: 'Rédige une relance courte pour une facture impayée.',
  outputFormat: 'json',
});

tools({ prompt, tools })

Prépare des appels tools applicatifs sans les exécuter côté cloud.

const routed = await aiClient.tools({
  prompt: 'Crée une facture ACME pour audit fiscal 250000 FCFA',
  tools: [{ name: 'create_invoice', description: 'Prépare une facture locale' }],
});

ocrAnalysis(file, options) / ocrAnalysis({ fileBase64, mimeType })

Analyse un document image/PDF via l’OCR cloud.

import fs from 'node:fs';

const file = new Blob([fs.readFileSync('./facture.pdf')], { type: 'application/pdf' });
const ocr = await aiClient.ocrAnalysis(file, {
  fileName: 'facture.pdf',
  prompt: 'Extrais les montants, références et lignes.',
});

imagen({ prompt, ...options })

Génère une image exploitable par l’application locale.

const image = await aiClient.imagen({
  prompt: 'Photo produit réaliste d’un terminal de caisse moderne',
  outputFormat: 'png',
});

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).

reportError(error, options) / reportMessage(message, options)

Remonte une erreur locale vers FiscAPI Cloud.

await productClient.reportMessage('Impression ticket impossible', {
  context: 'Caisse locale',
  severity: 'MEDIUM',
  additionalInfo: { printer: 'POS-01' },
});

Options principales: context, severity, url, method, userAgent, digest, appName, appVersion, appEdition, installationName, instanceId, machineFingerprint, tags, additionalInfo.

withErrorReporting(handler, options)

Wrapper qui remonte l'erreur puis la relance:

const normalizeInvoice = productClient.withErrorReporting(async (invoiceId: string) => {
  return normalizeLocalInvoice(invoiceId);
}, { context: 'Normalisation locale', severity: 'HIGH' });

installGlobalErrorHandlers(options)

Installe des handlers unhandledRejection / uncaughtException côté Node et error / unhandledrejection côté navigateur/Electron. La fonction retournée désinstalle les handlers.

new LocalProductClient(config | token)

const client = new LocalProductClient({
  token: 'pk_live_xxx',
  timeout: 30000,
});

activate({ machineFingerprint, ... })

Active une licence produit lors du premier lancement.

getSession()

Retourne les scopes et la date d'expiration de la licence.

Licences locales (référentiel)

Types de licences

• FISCAPI SFE LOCAL → scopes: SFE
• FISCAPI ERP → scopes: SFE, STOCK, PAIE_RH, COMPTA
• FISCAPI SOLUTION → scopes: FULL_USE

Les clés produit utilisent le préfixe pk_live_... (différent des tokens IA sk_live_...).

Durées supportées

• FISCAPI SFE LOCAL : 1 an, 2 ans, 5 ans, illimité
• FISCAPI ERP : 1 an, 2 ans, 5 ans, illimité
• FISCAPI SOLUTION : 1 an, 2 ans, 5 ans, 10 ans

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
• tools
• ocr_analysis
• imagen
• generator

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.