FiscAPI Local SDK

SDK officiel pour connecter une instance locale (FiscAPI Solution / FiscAPI ERP) aux crédits et à la passerelle IA de FiscAPI Cloud.

Installation

npm install @fiscapi-node/local-sdk

Vue d’ensemble

1. L’admin FiscAPI Cloud crée des actions IA (prompts + coût en crédits).
2. L’instance locale récupère ces actions via le SDK et alimente sa table locale.
3. Avant chaque action IA locale, l’instance débite des crédits via l’API Cloud.

Les actions IA standard FiscAPI sont listées plus bas.
Si vous modifiez ces actions côté admin, mettez à jour le SDK/README pour garder un référentiel fiable.
Si aucun paramétrage n’est fait côté admin, l’API renvoie les actions standards par défaut.

Pré‑requis côté Cloud (Admin)

• Créer un token local IA (scope AI_LOCAL).
• Configurer les actions IA locales (instructions, coût).

Intégration côté Local (recommandée)

1) Synchroniser la session

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

const session = await client.getSession();
// session.gateway.apiKey → clé AI Gateway à stocker localement (chiffrée)

Stockage recommandé

• Stocker session.gateway.apiKey chiffrée en base locale (ex: AI_GATEWAY_API_KEY_ENC).
• Ne jamais exposer la clé en clair côté client.

2) Synchroniser les actions IA

const { actions } = await client.getActions();
// actions → à enregistrer dans votre table locale d’actions

Table locale recommandée (exemple)

| champ | type | description | |---|---|---| | key | string | Identifiant unique de l’action | | label | string | Nom affiché | | description | string | Résumé court | | instructions | text | Prompt/consignes pour l’IA | | costCredits | number | Coût en crédits | | enabled | boolean | Actif/inactif |

3) Débiter les crédits avant une action IA

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

Si le solde est insuffisant, l’API renvoie 402 et l’UI locale doit demander une recharge.

API du SDK

new LocalAiClient(config | token)

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

getSession()

Récupère la clé Gateway, le modèle recommandé et l’état des crédits.

Retour

{
  gateway: { apiKey, model, provider, source },
  credits: { available, lowThreshold, isLow },
  policy: { creditCostPerAction }
}

getActions()

Récupère les actions IA configurées par l’admin.

Retour

{
  actions: [{
    key, label, description, instructions, costCredits, enabled
  }],
  updatedAt
}

consumeCredits({ units, action })

Débite des crédits pour une action IA locale.

Paramètres

• units (number) : nombre d’unités (default: 1)
• action (string) : clé de l’action (ex: ocr_invoice)

getCreditsBalance()

Retourne le solde global des crédits.

Actions IA standards (FiscAPI)

Ces actions sont prévues par défaut dans FiscAPI Solution / FiscAPI ERP. Utilisez-les comme base stable.

| key | label | usage | |---|---|---| | eliana_chat | Eliana (chat) | Assistant conversationnel | | invoice | Création de facture | Génération d’un brouillon de facture | | proforma | Proforma | Devis / proforma | | vigilance | Vigilance paie | Analyse risques / doublons | | ocr_expense | OCR justificatifs | Extraction données dépense | | ocr_invoice | OCR facture | Extraction facture scannée |

Schémas attendus (réponses IA)

eliana_chat

{
  "title": "string",
  "summary": "string",
  "steps": [
    { "label": "string", "detail": "string", "priority": "high|medium|low" }
  ],
  "nextActions": ["string"]
}

invoice / proforma

{
  "customer": { "name": "string", "ifu": "string|null", "contact": "string|null", "address": "string|null" },
  "invoice": { "type": "FV|FA|EV|EA", "aib": "A|B|AIB_3|NONE", "pricingMode": "HT|TTC" },
  "items": [
    { "name": "string", "price": 0, "quantity": 1, "taxGroup": "A|B|C|D|E|F", "unitLabel": "UNITE|SERVICE|JOUR|HEURE|FORFAIT" }
  ],
  "payment": [
    { "name": "ESPECES|VIREMENT|CARTEBANCAIRE|MOBILEMONEY|CHEQUES|CREDIT|AUTRE", "amount": 0 }
  ]
}

vigilance

{
  "title": "string",
  "verdict": "OK|WARNING|CRITICAL",
  "summary": "string",
  "topFindings": [
    { "code": "string", "severity": "CRITICAL|HIGH|MEDIUM|LOW", "count": 0, "explanation": "string" }
  ],
  "actionPlan": [
    { "label": "string", "detail": "string", "priority": "high|medium|low" }
  ]
}

ocr_expense

{
  "vendorName": "string|null",
  "vendorIfu": "string|null",
  "invoiceNumber": "string|null",
  "invoiceDate": "string|null",
  "currency": "string|null",
  "amountTtc": 0,
  "amountVat": 0,
  "amountHt": 0,
  "paymentMode": "CASH|CARD|BANK_TRANSFER|MOBILE_MONEY|OTHER|null",
  "isPaid": true,
  "description": "string|null"
}

ocr_invoice

{
  "customerName": "string|null",
  "customerIfu": "string|null",
  "customerAddress": "string|null",
  "customerContact": "string|null",
  "lines": [
    { "name": "string", "quantity": 1, "price": 0, "taxGroup": "A|B|C|D|E|F", "lineKind": "product|service" }
  ],
  "pricingMode": "HT|TTC|null",
  "totalHt": 0,
  "totalTax": 0,
  "totalTtc": 0
}

Bonnes pratiques

• Toujours débiter les crédits avant l’action IA locale.
• Logger l’action (key, user, montant) pour traçabilité.
• Bloquer l’IA locale quand available <= 0.
• Rafraîchir les actions (ex: 1 fois/jour).