GFS API Documentation

Authentification

L'API utilise deux modes d'authentification selon l'endpoint :

Mode 1 — JWT Supabase (endpoints `/gfs-engine`)

Envoyez votre JWT Supabase dans le header Authorization. Le token est obtenu après connexion via supabase.auth.signInWithPassword().

Authorization: Bearer <votre_jwt_supabase>
Content-Type: application/json

Mode 2 — Clé API (intégrations machine-to-machine)

Pour les intégrations sans session utilisateur, utilisez votre clé API GFS dans le header X-GFS-API-Key. Générez vos clés depuis le dashboard GFS → Paramètres → Clés API.

X-GFS-API-Key: gfs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Base URL

Tous les endpoints sont servis depuis l'infrastructure Supabase EU North (Stockholm, Suède). Les données ne quittent jamais l'Union Européenne.

POST /gfs-engine

Endpoint principal de conversion. Prend un fichier comptable source, détecte le format, mappe les comptes via IA, et retourne le fichier converti au format cible.

Corps de la requête

Exemple de requête

curl -X POST \
  https://hxktqzpkupvlfyzifjfd.supabase.co/functions/v1/gfs-engine \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "fileContent": "numero_cuenta;debe;haber;fecha;concepto\n430;1500.00;;20240101;Vente client A",
    "country": "es",
    "format": "fec",
    "company": "ACME España SL",
    "year": "2024",
    "currency": "EUR",
    "language": "fr"
  }'

Structure de la réponse (200 OK)

La réponse est encapsulée dans un tableau content compatible format Anthropic Messages API. L'objet de données est dans content[0].text sous forme de JSON stringifié.

{
  "content": [{
    "type": "text",
    "text": "{
      \"analysis\": {
        \"detected_format\": \"PGC Spain\",
        \"detected_country\": \"es\",
        \"separator\": \";\",
        \"encoding\": \"UTF-8\",
        \"quality_score\": 92,
        \"ai_comment\": \"Fichier PGC espagnol détecté. 1 200 lignes converties...\",
        \"language\": \"fr\"
      },
      \"mapping\": [
        {\"source_account\": \"430\", \"target_account\": \"411\",
         \"target_label\": \"Clients\", \"confidence\": \"high\"}
      ],
      \"validation\": [
        {\"type\": \"ok\", \"message\": \"Balance équilibrée : 45 230.00 €\"},
        {\"type\": \"warn\", \"message\": \"12 lignes sans numéro de TVA — impact SII espagnol\"}
      ],
      \"vida_compliance\": {
        \"status\": \"warn\",
        \"format\": \"SII\",
        \"vat_rate\": \"21%\",
        \"missing_fields\": [\"numero_iva\"],
        \"notes\": \"Champ NIF manquant sur 12 lignes. Requis pour déclaration SII.\"
      },
      \"stats\": {
        \"lines_converted\": 1200,
        \"total_input_lines\": 1200,
        \"accounts_mapped\": 45,
        \"balance_check\": \"équilibré\",
        \"coverage_pct\": 94,
        \"total_debit\": 45230.00,
        \"total_credit\": 45230.00,
        \"truncated\": false
      },
      \"output_preview\": \"JournalCode|JournalLib|EcritureNum|...\",
      \"output_full\": \"<base64 du fichier FEC complet>\",
      \"output_filename\": \"GFS_ACME_España_SL_2024.fec\",
      \"output_mime\": \"text/plain\"
    }"
  }]
}

Champs de réponse — stats

Décodage du fichier converti

Le champ output_full contient le fichier converti encodé en Base64 (UTF-8). Pour le décoder :

// JavaScript / Node.js
const fileContent = decodeURIComponent(escape(atob(response.output_full)));

// Python
import base64
file_content = base64.b64decode(response['output_full']).decode('utf-8')

// curl + bash
echo "<base64_string>" | base64 -d > output.fec

POST /stripe-checkout

Crée une session Checkout Stripe avec le user_id en metadata. Garantit que le webhook Stripe met à jour le bon profil après paiement.

Réponse

{ "url": "https://checkout.stripe.com/...", "session_id": "cs_live_..." }

Formats supportés

Formats d'entrée

Formats de sortie

Codes pays

Liste complète des 27+ pays disponibles sur demande à api-gfs@fintusk.fr.

Codes d'erreur

Structure d'une réponse d'erreur

{
  "error": "quota_exceeded",
  "message": "Limite de 50 conversions/mois atteinte pour le plan Solo.",
  "quota": { "used": 50, "limit": 50, "plan": "cabinet" }
}

Quotas et limites

SLA & disponibilité

Le SLA complet (compensations, procédures, exclusions) est disponible en téléchargement sur demande à api-gfs@fintusk.fr.

Changelog

v5 — Mars 2026

Agent Compliance ViDA avec validation proactive chiffrée. Compteur de quota par plan. Log des conversions en BDD. Paramètre user_id ajouté. Gestion HTTP 429 quota dépassé.

v4 — Février 2026

Parser multi-langue 100+ aliases (ES, DE, IT, NL, PL...). Format montants européens 1.234,56. Paramètre language pour l'analyse IA. Limite inline 10k lignes avec safeBase64.

v3 — Janvier 2026

Parser côté serveur pour les fichiers 50 000 lignes. Mapping par préfixe de compte. Support SAF-T XML complet.