Documentation de l’API BankConv

Authentification

Chaque requête demande une clé API d’équipe, envoyée comme jeton Bearer :

Authorization: Bearer sk_live_your_api_key

Les clés API appartiennent à une équipe. Créez-les dans l’application BankConv, dans les réglages de votre équipe. La clé complète n’est affichée qu’une fois, à sa création : gardez-la en lieu sûr. Les conversions par l’API utilisent le quota de pages de votre équipe ; voir la facturation.

Démarrage rapide

1. Envoyer un relevé

curl -X POST https://bankconv.com/api/v1/conversions \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -F "[email protected]"

L’API répond 201 Created avec la nouvelle conversion :

{
  "data": {
    "id": "9a8b7c6d-…",
    "status": "processing",
    "pages_count": 3,
    "created_at": "2026-10-11T12:00:00Z",
    "input": {
      "filename": "statement.pdf",
      "pages_count": 3
    }
  }
}

2. Interroger le statut

curl https://bankconv.com/api/v1/conversions/9a8b7c6d-… \
  -H "Authorization: Bearer sk_live_your_api_key"

Répétez toutes les quelques secondes jusqu’à ce que status vaille completed ou failed.

3. Télécharger les résultats

# JSON (default)
curl https://bankconv.com/api/v1/conversions/9a8b7c6d-…/download \
  -H "Authorization: Bearer sk_live_your_api_key"

# CSV, with matching tables merged into one transaction list
curl "https://bankconv.com/api/v1/conversions/9a8b7c6d-…/download?format=csv&view=merged" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -o statement.csv

# QBO for QuickBooks Desktop (also ofx, qfx or xero)
curl "https://bankconv.com/api/v1/conversions/9a8b7c6d-…/download?format=qbo" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -o statement.qbo

Points d’accès

Tous les chemins sont relatifs à https://bankconv.com/api/v1.

Créer une conversion

POST /conversions prend un corps multipart/form-data.

Pour un relevé protégé par mot de passe, envoyez le mot de passe avec le fichier :

curl -X POST https://bankconv.com/api/v1/conversions \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -F "[email protected]" \
  -F "password=the_pdf_password"

Si vous ne connaissez pas le mot de passe, les pages des banques donnent les formats utilisés par les banques quand nous avons pu les confirmer.

Lister les conversions

GET /conversions renvoie les conversions de votre équipe, de la plus récente à la plus ancienne.

Obtenir les opérations

GET /conversions/{id}/transactions renvoie les opérations du relevé prêtes à l’emploi : de vraies dates, un seul montant signé (entrées en positif, sorties en négatif), le solde courant, et sans le solde d’ouverture ni les lignes de total. Les montants sont des chaînes décimales dans la devise du relevé.

curl https://bankconv.com/api/v1/conversions/9a8b7c6d-…/transactions \
  -H "Authorization: Bearer sk_live_your_api_key"

{
  "data": {
    "tables": "0:1,1:0",
    "institution": "JPMorgan Chase Bank, N.A.",
    "country": "US",
    "account_type": "checking",
    "account_number": "XXXX4821",
    "currency": "USD",
    "period": { "start": "2026-01-03", "end": "2026-01-31" },
    "transaction_count": 42,
    "transactions": [
      { "date": "2026-01-03", "description": "Payroll deposit", "reference": null, "amount": "3200.00", "balance": "4450.00" },
      { "date": "2026-01-04", "description": "Coffee shop", "reference": null, "amount": "-4.80", "balance": "4445.20" }
    ],
    "warnings": []
  }
}

BankConv choisit le groupe de tableaux qui donne le plus d’opérations et vous dit lequel dans tables (index de page et de tableau, à partir de 0). Pour lire d’autres tableaux, passez-les, par exemple ?tables=2:0,3:0. S’ils ne peuvent pas être lus comme des opérations, comme un récapitulatif de compte, la réponse est 422 unreadable_statement avec la raison.

Télécharger les résultats

GET /conversions/{id}/download fonctionne une fois la conversion completed.

La réponse JSON contient chaque page extraite avec ses blocs (tableaux et texte), pour que vous fassiez vous-même la correspondance des colonnes. Pour des lignes toutes prêtes, utilisez plutôt Obtenir les opérations.

Les téléchargements OFX, QFX, QBO et Xero portent les éventuels avertissements, comme une banque absente de la liste QuickBooks, sous forme de tableau JSON dans l’en-tête X-BankConv-Warnings.

Crédits et consommation

GET /credits renvoie votre solde de pages pour la période de facturation en cours :

{
  "data": {
    "total": 1000,
    "remaining": 842,
    "bonus": 50,
    "bonusRemaining": 50
  }
}

GET /credits/usage renvoie les pages utilisées depuis le début de la période :

{
  "data": {
    "period_start": "2026-09-11",
    "period_end": "2026-10-11",
    "pages_used": 158
  }
}

Réponses et erreurs

Les réponses réussies placent le résultat sous une clé data. Les listes ajoutent les informations de pagination :

{
  "data": [ … ],
  "links": { … },
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 72
  }
}

Les erreurs ont toutes la même forme :

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits. You have 2 remaining but need 5.",
    "status": 422
  }
}

Limites de débit

Chaque clé API peut faire 60 requêtes par minute. Les réponses portent les en-têtes X-RateLimit-Limit et X-RateLimit-Remaining, et une réponse 429 inclut Retry-After avec le nombre de secondes à attendre.

Facturation

Chaque page d’un PDF converti utilise une page du quota mensuel de votre formule. Une conversion demande assez de pages restantes pour tout le document ; aucune conversion partielle n’est faite, et la requête renvoie insufficient_credits à la place. Si le paiement de votre abonnement a échoué, la requête renvoie payment_failed jusqu’à la mise à jour de la carte.

Comparez les formules sur la page des tarifs.

Conservation des données

Les conversions sont supprimées automatiquement selon la durée de conservation de votre équipe : 24, 48 ou 72 heures, 24 par défaut. Ensuite, les demandes de téléchargement renvoient 410 Gone. Téléchargez ce dont vous avez besoin avant, ou supprimez vous-même une conversion avec DELETE /conversions/{id}. Voir sécurité et traitement des données.