API & intégrations

L'API de Blina Desk

Blina Desk n'a pas à être votre seul logiciel. Avec l'API REST, vos autres systèmes lisent et écrivent les mêmes données que celles affichées dans l'interface, avec les mêmes règles.

Ce que vous pouvez en faire

Documents et recherche

Lister, télécharger et téléverser des documents, parcourir les dossiers, chercher en plein texte. Ce que vous envoyez suit le même chemin que n'importe quel dépôt : analyse antivirus, OCR, indexation.

Clients et contacts

Lire, créer et modifier entreprises et personnes, mêmes champs obligatoires et même historique que dans le CRM.

Commandes et factures

Les créer, ajouter les lignes, changer le statut. Le numéro vient du serveur et les totaux de la base : aucun client ne peut les écraser.

Lire les factures fournisseurs

Vous lisez les factures fournisseurs et leurs lignes via l'API. Elles naissent de la validation EN 16931 avec détection des doublons, si bien que chaque facture suit le même chemin que dans le logiciel.

BASE="https://api.blina-desk.com/api/v1"

curl -s "$BASE/documents?limit=5" -H "Authorization: Bearer $BDK"
curl -s "$BASE/accounts?q=gmbh"   -H "Authorization: Bearer $BDK"
curl -s "$BASE/search?q=vertrag"  -H "Authorization: Bearer $BDK"

Regardez plutôt que lire

Enregistré dans le logiciel réel, avec de vraies données : ce n'est pas une animation.

Clés et permissionsL’entreprise crée ses propres clés, en clair une seule fois, avec des permissions choisies une par une.
Webhooks, archive, consommationDes événements signés, l’horodatage dans la signature, et une file qui réessaie.

Comment commencer

  1. Dans l'espace d'administration, sous « API et intégrations », créez une clé et donnez-lui les droits qu'elle doit avoir. La clé en clair, vous la voyez une seule fois, nous n'en gardons que l'empreinte.
  2. Envoyez la clé comme bearer token. Le premier appel qui répond vous dit à quelle entreprise elle appartient.
  3. Lisez, écrivez, et pour le reste abonnez-vous aux webhooks au lieu d'interroger sans cesse.
# en-tête, le serveur attribue le numéro
curl -s -X POST "$BASE/invoices" \
  -H "Authorization: Bearer $BDK" -H "Content-Type: application/json" \
  -d '{"account_id":"...","issue_date":"2026-07-29"}'
# {"id":"...","invoice_no":"INV-000042","status":"draft","total":0.0}

# lignes, la base calcule les totaux
curl -s -X POST "$BASE/invoices/$ID/lines" \
  -H "Authorization: Bearer $BDK" -H "Content-Type: application/json" \
  -d '{"name":"Beratung","qty":3,"unit_price":100,"vat_rate":19}'
# {"id":"...","total":357.0}   <- 3 x 100 + 19%

Webhooks : vous l'apprenez sans demander

Au lieu d'aller voir si quelque chose a changé, on vous le dit. Chaque livraison est signée, vérifiez la signature avant d'utiliser le contenu.

  • L'adresse doit être en https public : les adresses privées, loopback et link-local sont refusées, à l'enregistrement et de nouveau à chaque livraison.
  • Répondez 2xx dès que vous avez enregistré l'événement. Tout le reste compte comme un échec et sera réessayé : 0s → 30s → 5m → 30m → 2h.
  • Après cinq livraisons épuisées d'affilée, le point de terminaison est suspendu, et c'est vous qui le réactivez.
  • Une livraison peut arriver plusieurs fois : servez-vous de l'identifiant de l'événement pour savoir si vous l'avez déjà vue.

Vérifier la signature, ce n'est pas facultatif

Calculez-la sur le corps brut, avant tout parsing JSON : re-sérialiser change les octets et la comparaison échoue. Rejetez ce qui ne se vérifie pas, et ce qui a plus de cinq minutes, même avec un MAC correct.

import hashlib, hmac, time

def verify(secret: str, raw_body: bytes, header: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    ts, sig = int(parts["t"]), parts["v1"]
    if abs(time.time() - ts) > tolerance:      # anti-replay
        return False
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(sig, expected)  # confronto a tempo costante

Quotas et sécurité

  • 120 appels par minute et 20 000 par jour et par clé. Chaque réponse réussie vous dit où vous en êtes ; au-delà, un 429 avec Retry-After.
  • Une clé ne porte que les droits que vous lui donnez, documents, recherche, CRM, ventes, achats, webhooks, accordés un par un.
  • Chaque réponse porte un X-Request-Id : citez-le et nous pouvons reconstituer exactement ce qui s'est passé.
X-RateLimit-Limit-Minute: 120
X-RateLimit-Remaining-Minute: 118
X-RateLimit-Limit-Day: 20000
X-RateLimit-Remaining-Day: 19863