Documentation API - Bank-Statement-Conversion

API Bank Statement Conversion

Ajoutez la conversion de relevés bancaires à votre logiciel avec un flux upload, statut et téléchargement.

Aperçu

L’API Bank Statement Conversion s’adresse aux développeurs qui veulent ajouter la conversion à leur propre application. Elle documente le flux public: vérifier éventuellement la capacité du compte, envoyer les fichiers, interroger le statut, puis télécharger les résultats avec le jeton retourné.

Cette référence est volontairement limitée au flux public de conversion.

Démarrage rapide

Étape 1

Créer un jeton API

Générez un jeton dans le tableau de bord et envoyez-le avec Authorization: Bearer YOUR_API_TOKEN.

Étape 2

Envoyer un fichier

POST vers /api/upload avec statement[], format et les options facultatives.

Étape 3

Interroger le statut

Utilisez le jobId retourné avec /api/conversion-status/{jobId} jusqu’à obtenir download_token.

Étape 4

Télécharger le résultat

GET /api/download/{downloadToken} et enregistrez la réponse binaire comme fichier converti.

Authentification

Authentification par jeton API

Toutes les requêtes API doivent inclure un jeton API. Les jetons se créent dans la section API Tokens du tableau de bord.

Créer un jeton API

  1. Connectez-vous à votre compte
  2. Ouvrez la section API Tokens du tableau de bord
  3. Cliquez sur "Create New Token" et nommez le jeton
  4. Copiez et conservez le jeton. Il ne sera affiché qu’une seule fois.

Utiliser le jeton API

Incluez le jeton API dans l’en-tête Authorization:

Authorization: Bearer YOUR_API_TOKEN

Agents IA

Utiliser l’API avec des agents IA

Les outils d’IA peuvent s’intégrer au même flux de conversion public que les développeurs. Utilisez le schéma OpenAPI, les fichiers de découverte LLM ou le point de terminaison MCP afin que les agents sachent quels points de terminaison de conversion appeler et quelles actions nécessitent une confirmation.

Découverte pour agents

/api/openapi.json/llms.txt/llms-full.txt/mcp/bank-statement-conversion
  • Utilisez /api/openapi.json pour les outils compatibles avec un schéma, comme ChatGPT Actions ou les générateurs d’agents personnalisés.
  • Utilisez /llms.txt et /llms-full.txt pour fournir aux agents le contexte produit et API canonique.
  • Utilisez /mcp/bank-statement-conversion pour les clients agents compatibles MCP qui prennent en charge les serveurs MCP distants.

Configuration unique du jeton

  1. Connectez-vous une fois et créez un jeton API dans le tableau de bord.
  2. Conservez toutes les autorisations de conversion activées, sauf si vous souhaitez un jeton restreint.
  3. Définissez le jeton comme BSC_API_TOKEN dans l’environnement du client MCP.
  4. Révoquez le jeton depuis le tableau de bord lorsque l’accès de l’agent doit prendre fin.

Connecter Codex, Claude, Cursor et d’autres clients IA

Tous les clients IA compatibles MCP utilisent le même endpoint distant et un jeton bearer. Gardez le jeton dans une variable d’environnement, pas dans les prompts ni dans le code source.

Endpoint MCP distant
https://bank-statement-conversion.com/mcp/bank-statement-conversion
En-tête d’authentification
Authorization: Bearer YOUR_API_TOKEN
Configuration Codex

Ajoutez cette entrée de serveur à votre configuration Codex.

Codex MCP configtoml
[mcp_servers.bank_statement_conversion]
url = "https://bank-statement-conversion.com/mcp/bank-statement-conversion"
bearer_token_env_var = "BSC_API_TOKEN"

Définissez le jeton dans votre shell ou environnement système, puis redémarrez le client IA.

Token environment variablebash
export BSC_API_TOKEN="YOUR_API_TOKEN_HERE"
Autres clients IA
  • Claude, Cursor et les autres clients MCP doivent utiliser le même endpoint et le même jeton bearer Authorization.
  • ChatGPT Actions et les générateurs d’agents personnalisés doivent utiliser /api/openapi.json au lieu de MCP lorsqu’ils ont besoin d’un schéma OpenAPI.
  • Utilisez /llms.txt et /llms-full.txt comme contexte produit pour les agents qui prennent en charge les fichiers de connaissances.

Autorisations de jeton limitées

account:statusconversion:uploadconversion:readconversion:download

Endpoints du flux

Voici les seuls endpoints nécessaires pour ajouter la conversion de documents à votre application.

EndpointMéthodeDescription
/api/user-statusGETVérification facultative des crédits, pages et abonnement
/api/uploadPOSTEnvoyer des relevés bancaires à convertir
/api/conversion-status/{jobId}GETVérifier le statut d’une conversion
/api/download/{downloadToken}GETTélécharger une conversion terminée avec le jeton retourné

Endpoint de statut du compte

GET /api/user-status

Utilisez cet endpoint facultatif avant l’envoi pour confirmer que le jeton dispose de crédits, pages ou accès payant.

Champs utiles de la réponse

ChampTypeDescription
remaining_creditsintegerCrédits disponibles pour les conversions basées sur des crédits.
remaining_daily_pagesintegerQuota quotidien de pages restant pour l’utilisateur authentifié.
remaining_premium_pagesintegerQuota mensuel premium de pages restant pour le plan effectif.
plan_typestringPlan d’abonnement effectif du jeton API.

Exemple de réponse

Réponse JSONjson
Copiez cette structure pour l’analyse côté client et la gestion des erreurs.
{
  "success": true,
  "remaining_credits": 42,
  "remaining_daily_pages": 100,
  "remaining_premium_pages": 950,
  "plan_type": "premium"
}

Endpoint d’envoi

POST /api/upload

Cet endpoint permet d’envoyer des relevés bancaires à convertir. La conversion est asynchrone et vous recevrez un ID de tâche pour vérifier le statut plus tard.

Formats d’entrée pris en charge

UtilisationFormatsExtensionsNotes
Conversions standardPDF, JPG/JPEG, PNG, TIFF/TIF, CSV, XLS/XLSX, OFX, QBO, QFX, 940, STA, MT940, MT940X, XML, CAMT.053.pdf, .jpg, .jpeg, .png, .tiff, .tif, .csv, .xls, .xlsx, .ofx, .qbo, .qfx, .940, .sta, .mt940, .mt940x, .xml, .camt053À utiliser pour les conversions de relevés bancaires, factures et reçus.
Nettoyage CSVCSV, XLS, XLSX.csv, .xls, .xlsxÀ utiliser uniquement lorsque format vaut csv_clean.
Génération de fichiers de paiementCSV, XLS, XLSX.csv, .xls, .xlsxÀ utiliser pour les lignes de paiement CSV ou Excel qui génèrent des fichiers ACH/NACHA, CPA005, SEPA XML, BACS, ABA ou NZ prêts pour la banque.

Formats de sortie pris en charge

document_typeDocumentValeurs format autorisées
bank_statementRelevé bancaire
csvexceljsonqb_onlineqb_desktopxeroofxofx_legacyqfxmt940mt940_moneybirdcamt053camt053_legacycamt053_moneybirdcamt053_netsuitecamt053_sap_v2camt053_sap_v8camt053_business_centralcamt053_datevcamt053_afascamt053_twinfieldtally_xmlbai2bai2_netsuitebai2_sapbai2_bank_xsagesage_cloudsage_intacctmyobdatevdatev_accountingcsv_clean
invoiceFacture
csvexceljsonqb_onlineqb_desktopubl_xmlubl_peppolxrechnung_ublzugferd_pdffactur_x_pdf
receiptReçu
csvexceljson
payment_fileFichier de paiement bancaire
payment_nachapayment_cpa005payment_sepa_pain001payment_bacspayment_abapayment_nz

Paramètres de requête

ParamètreTypeRequisDescription
formatstringOuiFormat de sortie. Utilisez l’une des valeurs format autorisées ci-dessus pour le document_type choisi.
document_typestringNonCatégorie de document : bank_statement, invoice, receipt ou payment_file. Par défaut : bank_statement.
statementfile arrayOuiFichiers à convertir. Envoyez un ou plusieurs fichiers comme statement[].
conversion_modestringNonMode de conversion: precision ou fast. La valeur par défaut est precision.
separate_debit_creditbooleanNonIndique s’il faut séparer les colonnes débit et crédit. Par défaut: false.
combine_filesbooleanNonIndique s’il faut combiner plusieurs fichiers en une seule sortie. Par défaut: false.

Exemple de réponse

Réponse JSONjson
Copiez cette structure pour l’analyse côté client et la gestion des erreurs.
{
  "stage": "pending",
  "jobId": "5f3a7d8c-8a91-4a2e-9d3b-4c84f0636c12"
}

Endpoint de statut

GET /api/conversion-status/{jobId}

Cet endpoint permet de vérifier le statut d’une tâche de conversion. Interrogez-le jusqu’à ce que la tâche soit terminée.

Paramètres de chemin

ParamètreTypeDescription
jobIdstringL’ID de tâche retourné par l’endpoint d’envoi

Exemple de réponse en attente

Réponse JSONjson
Copiez cette structure pour l’analyse côté client et la gestion des erreurs.
{
  "stage": "processing",
  "success": false,
  "previews": []
}

Exemple de réponse terminée

Réponse JSONjson
Copiez cette structure pour l’analyse côté client et la gestion des erreurs.
{
  "success": true,
  "previews": [
    {
      "file_name": "bank_statement.pdf",
      "format": "CSV",
      "download_token": "Y8Jm7qVf9sR2kP6nL4xA0bT3cD5eF1gH",
      "partial_conversion": false,
      "credits_used": 1
    }
  ],
  "failed_files": [],
  "remaining_credits": 41,
  "remaining_premium_pages": 949,
  "remaining_daily_pages": 99
}

Exemple de réponse échouée

Réponse JSONjson
Copiez cette structure pour l’analyse côté client et la gestion des erreurs.
{
  "stage": "complete",
  "success": false,
  "error": "An error occurred during the conversion process.",
  "message": "The uploaded file could not be processed.",
  "previews": []
}

Endpoint de téléchargement

GET /api/download/{downloadToken}

Utilisez le download_token retourné dans une réponse de statut terminée. Ne construisez pas vous-même les jetons de téléchargement.

Paramètres de chemin

ParamètreTypeDescription
downloadTokenstringLe download_token retourné pour un fichier converti dans la réponse de statut.

Exemple de requête

Télécharger avec cURLbash
Exécutez depuis un terminal après avoir remplacé le jeton et le jeton de téléchargement.
curl -L \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o converted_statement.csv \
  "https://bank-statement-conversion.com/api/download/Y8Jm7qVf9sR2kP6nL4xA0bT3cD5eF1gH"

Exemple de réponse

200 OK
Retourne le fichier converti comme téléchargement binaire avec Content-Disposition: attachment. L’extension dépend du format de sortie demandé, par exemple .csv, .xlsx, .qbo, .ofx, .xml, .json, .ach, .txt ou .aba.

Exemples d’en-têtes de réponse

En-têtes de réponsehttp
L’endpoint de téléchargement retourne un flux de fichier au lieu d’un corps JSON.
HTTP/1.1 200 OK
Content-Type: text/csv
Content-Disposition: attachment; filename="bank-statement.csv"
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
}

Gestion des erreurs

L’API utilise les codes de statut HTTP standard pour indiquer le succès ou l’échec des requêtes.

Code de statutDescription
200 OKLa requête a réussi
400 Bad RequestLa requête est invalide ou des paramètres requis sont manquants
401 UnauthorizedL’authentification a échoué ou le jeton est invalide
403 ForbiddenL’utilisateur authentifié n’a pas l’autorisation d’accéder à la ressource
422 Unprocessable EntityDes erreurs de validation se sont produites
500 Internal Server ErrorUne erreur s’est produite sur le serveur

Exemples de réponses d’erreur

401 Non authentifiéjson
Copiez cette structure pour l’analyse côté client et la gestion des erreurs.
{
  "message": "Unauthenticated."
}
422 Erreur de validationjson
Copiez cette structure pour l’analyse côté client et la gestion des erreurs.
{
  "message": "The given data was invalid.",
  "errors": {
    "statement": [
      "The statement field is required."
    ],
    "format": [
      "The selected format is invalid."
    ]
  }
}
403 Capacité insuffisantejson
Copiez cette structure pour l’analyse côté client et la gestion des erreurs.
{
  "success": false,
  "error": "Insufficient credits or page allowance for this conversion."
}

Limites de débit

Pour garantir un usage équitable, les limites dépendent de votre abonnement:

  • Utilisateurs premium: 100 requêtes par minute
  • Taille maximale: 100 Mo par fichier
  • Maximum: 5 fichiers par requête

Exemples de code

Exemples complets du flux: envoyer, interroger, télécharger.

1. Envoyer2. Interroger3. Télécharger
JavaScript exemplejavascript
Utilise axios et form-data pour envoyer, interroger et télécharger le fichier converti.
1// Upload a bank statement file
2const axios = require('axios');
3const FormData = require('form-data');
4const fs = require('fs');
5
6// Your API token from the dashboard
7const API_TOKEN = 'your_api_token_here';
8
9// Create a form data object
10const formData = new FormData();
11formData.append('document_type', 'bank_statement');
12formData.append('format', 'csv');
13formData.append('statement[]', fs.createReadStream('bank_statement.pdf'));
14formData.append('separate_debit_credit', 'true');
15formData.append('combine_files', 'false');
16
17// Make the API request
18const BASE_URL = 'https://bank-statement-conversion.com/api';
19
20axios.post(`${BASE_URL}/upload`, formData, {
21  headers: {
22    'Authorization': `Bearer ${API_TOKEN}`,
23    ...formData.getHeaders()
24  }
25})
26.then(response => {
27  const jobId = response.data.jobId;
28  console.log(`Conversion job started with ID: ${jobId}`);
29
30  // Poll for job status
31  checkJobStatus(jobId);
32})
33.catch(error => {
34  console.error('Error uploading file:', error.response ? error.response.data : error.message);
35});
36
37// Function to check job status
38function checkJobStatus(jobId) {
39  axios.get(`${BASE_URL}/conversion-status/${jobId}`, {
40    headers: {
41      'Authorization': `Bearer ${API_TOKEN}`
42    }
43  })
44  .then(response => {
45    const data = response.data;
46    console.log('Job stage:', data.stage);
47
48    if (data.success && data.previews && data.previews.length > 0) {
49      const downloadToken = data.previews[0].download_token;
50      downloadFile(`${BASE_URL}/download/${downloadToken}`);
51    } else if (data.stage === 'pending' || data.stage === 'processing') {
52      // Check again after 5 seconds
53      setTimeout(() => checkJobStatus(jobId), 5000);
54    } else {
55      console.error('Conversion failed:', data.error || data.message || data);
56    }
57  })
58  .catch(error => {
59    console.error('Error checking job status:', error.response ? error.response.data : error.message);
60  });
61}
62
63// Function to download the converted file
64function downloadFile(url) {
65  const outputPath = 'converted_statement.csv';
66
67  axios({
68    method: 'get',
69    url: url,
70    responseType: 'stream',
71    headers: {
72      'Authorization': `Bearer ${API_TOKEN}`
73    }
74  })
75  .then(response => {
76    response.data.pipe(fs.createWriteStream(outputPath));
77    console.log(`File downloaded to ${outputPath}`);
78  })
79  .catch(error => {
80    console.error('Error downloading file:', error.message);
81  });
82}