Facture entrée, QR de paiement sorti — via API

Prêt en trois étapes

1. 1

   Créer une clé API

   Connecte-toi à l’appli et crée une clé sous « API & intégrations ». Elle commence par gsk_live_ et n’est affichée qu’une seule fois — garde-la en lieu sûr. 10 tokens gratuits sont déjà sur le compte.

2. 2

   Choisir une porte

   REST pour ton système, MCP pour ton agent IA, e-mail pour tes flux d’envoi existants — ou simplement l’appli web. La clé est la même partout.

3. 3

   Envoyer des factures

   Document entré, réponse avec les données de paiement et le GiroCode — pour les PDF, aussi le PDF tamponné. Chaque réponse indique les tokens débités et restants.

L’API REST et le serveur MCP s’authentifient avec la même clé API GiroSnap en bearer token. Il n’existe pas de « clé MCP » séparée — la clé gsk_live_ de l’appli est la seule clé :

Authorization: Bearer gsk_live_...

Les clés se créent et se révoquent uniquement dans l’appli (session connectée) — une clé qui fuite ne peut jamais créer de nouvelles clés. Le texte en clair n’est plus jamais récupérable après création.

JSON ou multipart, 12 Mo max par document (JPG, PNG, WEBP, PDF). Le départ le plus rapide est l’endpoint tout-en-un :

curl -X POST https://www.girosnap.eu/api/v1/invoices \
  -H "Authorization: Bearer gsk_live_..." \
  -F "file=@rechnung.pdf"

• POST/api/v1/invoicesTout en un : données de paiement + QR, pour les PDF aussi le PDF tamponné.
• POST/api/v1/extractExtraire uniquement les données de paiement (pas de QR, pas de tampon).
• POST/api/v1/qrQR seul — depuis des données de paiement (sans extraction) ou un document.
• POST/api/v1/stampTamponner le GiroCode sur un PDF.
• GET/api/v1/balanceConsulter le solde de tokens, le seuil d’alerte et les packs (gratuit).
• POST/api/v1/checkoutCréer un lien Stripe directement payable pour un pack de tokens.

Tous les paramètres, formats de réponse et codes d’erreur — avec « try it out » directement dans le navigateur : Ouvrir la référence API interactive

MCP (Model Context Protocol) est le standard ouvert avec lequel les agents IA (p. ex. Claude) utilisent des outils externes. Notre serveur MCP donne GiroSnap à ton agent comme boîte à outils : il photographie une facture, appelle un outil et reçoit le GiroCode ou le PDF tamponné directement dans son flux.

Le chemin le plus simple — Claude (web & desktop) : Réglages → Connecteurs → « Ajouter un connecteur personnalisé », nomme-le « GiroSnap » et colle cette URL avec ta clé. Laisse les champs OAuth vides :

https://www.girosnap.eu/api/mcp?key=GIROSNAP_API_KEY

Cette URL contient ta clé API — traite-la comme un mot de passe et ne la partage pas.

Connexion : saisis l’URL du serveur et passe ta clé API dans l’en-tête Authorization — la même config fonctionne dans Claude, les agents d’IDE et tes propres agents SDK :

{
  "mcpServers": {
    "girosnap": {
      "type": "http",
      "url": "https://www.girosnap.eu/api/mcp",
      "headers": {
        "Authorization": "Bearer gsk_live_..."
      }
    }
  }
}

GIROSNAP_API_KEY est ta clé gsk_live_ normale de l’appli — il n’y a pas de clé MCP séparée.

Les outils en détail

• extract_invoice1 token/page

  Lit le bénéficiaire, l’IBAN, le BIC, le montant (en centimes) et la référence depuis une photo de facture ou un PDF. Utile seulement si ton agent ne peut ou ne doit pas lire la facture lui-même.

• create_payment_qr1 token/page

  Génère l’EPC/GiroCode scannable — en image, SVG et payload brut. Accepte des données de paiement prêtes (le plus rapide, sans extraction) ou un document.

• stamp_invoice_pdf1 token/page

  Tamponne le GiroCode sur la facture PDF — sur une zone libre ou une page ajoutée ; les PDF signés et les e-factures restent intacts et reçoivent une feuille d’accompagnement.

• get_token_balancegratuit

  Solde de tokens actuel, indicateur de seuil, liste des packs et lien de recharge.

• buy_tokensgratuit

  Crée un lien Stripe Checkout directement payable pour un pack de tokens — les tokens sont crédités automatiquement après paiement.

Astuce : si ton agent connaît déjà les données de paiement (il a vu la facture, après tout), il les passe simplement en payment à create_payment_qr ou stamp_invoice_pdf — aucune extraction ne tourne chez nous et la réponse est la plus rapide.

Envoie tes factures simplement par e-mail — sans aucune ligne de code. Pour les photos, le GiroCode arrive dans le corps de la réponse ; les PDF reviennent tamponnés en pièces jointes, plusieurs par e-mail si tu veux.

1. Enregistre ton adresse d’expéditeur dans l’appli sous « API & intégrations ».
2. Clique sur le lien de confirmation dans l’e-mail — c’est tout.
3. Envoie tes factures (PDF, JPG, PNG, WEBP) à l’adresse de traitement et attends la réponse.

Jusqu’à 10 pièces jointes par e-mail, 12 Mo chacune. La réponse indique toujours les tokens débités et restants ; quand le solde devient bas, le lien de recharge est inclus.

L’appli elle-même est la quatrième porte : téléverser, vérifier, tamponner — directement dans le navigateur. Et quelle que soit la porte d’entrée d’une facture, tout est journalisé dans ton historique, avec QR, PDF et coûts consultables à tout moment.

Une règle, partout : 1 token par page (un QR depuis des données prêtes compte comme une page). Les nouveaux comptes démarrent avec 10 tokens gratuits ; on recharge via Stripe — dans l’appli, via POST /api/v1/checkout ou avec l’outil buy_tokens.

Quand le solde devient bas, on te prévient par e-mail ; à 0, le traitement est en pause sur toutes les portes (aucun service IA n’est appelé) et chaque réponse porte le lien de recharge.

Facturé équitablement : si le traitement échoue de notre côté, le token est remboursé. Si le modèle a tourné mais n’a pas pu lire la facture, il reste débité.

Toutes les erreurs utilisent la même enveloppe — un code lisible par machine, un message compréhensible et, en cas de tokens insuffisants (HTTP 402), le lien de recharge directement dans la réponse :

{
  "error": {
    "code": "insufficient_tokens",
    "message": "Not enough tokens for this operation.",
    "needed": 3,
    "balance": 1,
    "checkoutUrl": "https://www.girosnap.eu/app?screen=tokens"
  }
}

Codes importants : insufficient_tokens (402), unreadable (422, le modèle a tourné — token débité), extraction_failed (502, remboursé), unsupported_media (415), file_too_large (413). Catalogue complet dans la référence interactive.