API दस्तावेज़ - Bank-Statement-Conversion
API संदर्भ

Bank Statement Conversion API

अपलोड, स्थिति और डाउनलोड वाले स्पष्ट वर्कफ़्लो से कन्वर्ज़न जोड़ें।

प्रमाणीकरण अपलोड एंडपॉइंट वर्कफ़्लो एंडपॉइंट
api.bsc / v1
बेस URL
https://bank-statement-conversion.com/api
वर्कफ़्लो एंडपॉइंट
POST/uploadअपलोड एंडपॉइंट
GET/conversion-status/{jobId}स्थिति एंडपॉइंट
GET/download/{downloadToken}डाउनलोड एंडपॉइंट

अवलोकन

Bank Statement Conversion API उन डेवलपरों के लिए है जो अपने ऐप में कन्वर्ज़न जोड़ना चाहते हैं। यह सार्वजनिक कन्वर्ज़न वर्कफ़्लो बताता है: ज़रूरत हो तो खाते की क्षमता देखें, फ़ाइलें अपलोड करें, जॉब स्थिति पूछें, फिर लौटाए गए टोकन से तैयार आउटपुट डाउनलोड करें।

यह reference जानबूझकर public conversion workflow तक सीमित है।

त्वरित शुरुआत

चरण 1

API टोकन बनाएं

डैशबोर्ड में टोकन बनाएं और उसे Authorization: Bearer YOUR_API_TOKEN के रूप में भेजें।

चरण 2

फ़ाइल अपलोड करें

/api/upload पर statement[], format और वैकल्पिक सेटिंग्स के साथ POST करें।

चरण 3

जॉब स्थिति पूछें

लौटाई गई jobId को /api/conversion-status/{jobId} के साथ तब तक उपयोग करें जब तक preview में download_token न मिले।

चरण 4

आउटपुट डाउनलोड करें

/api/download/{downloadToken} पर GET करें और बाइनरी प्रतिक्रिया को कन्वर्ट की गई फ़ाइल के रूप में सहेजें।

प्रमाणीकरण

API टोकन प्रमाणीकरण

हर API अनुरोध में प्रमाणीकरण के लिए API टोकन शामिल होना चाहिए। टोकन आपके खाते के डैशबोर्ड में API Tokens सेक्शन से बनाए जा सकते हैं।

API टोकन कैसे बनाएं

  1. अपने खाते में लॉग इन करें
  2. डैशबोर्ड के API Tokens सेक्शन में जाएं
  3. "Create New Token" पर क्लिक करें और टोकन का नाम दें
  4. बनाए गए टोकन को कॉपी करके सुरक्षित रखें। यह केवल एक बार दिखाया जाएगा।

अपना API टोकन उपयोग करना

अपने अनुरोधों के Authorization हेडर में API टोकन शामिल करें:

Authorization: Bearer YOUR_API_TOKEN

AI एजेंट

AI एजेंट के साथ API का उपयोग करें

AI टूल्स डेवलपरों जैसे उसी सार्वजनिक कन्वर्ज़न वर्कफ़्लो से जुड़ सकते हैं। OpenAPI schema, LLM discovery files या MCP endpoint का उपयोग करें ताकि एजेंट जानें कि कौन से कन्वर्ज़न endpoints कॉल करने हैं और किन actions को confirmation चाहिए।

एजेंट discovery

/api/openapi.json/llms.txt/llms-full.txt/mcp/bank-statement-conversion
  • ChatGPT Actions या custom agent builders जैसे schema-aware tools के लिए /api/openapi.json उपयोग करें।
  • Agents को canonical product और API context देने के लिए /llms.txt और /llms-full.txt उपयोग करें।
  • Remote MCP servers support करने वाले MCP-compatible agent clients के लिए /mcp/bank-statement-conversion उपयोग करें।

एक बार token setup

  1. एक बार login करें और dashboard में API token बनाएँ।
  2. Restricted token न चाहिए तो सभी conversion abilities enabled रखें।
  3. MCP client environment में token को BSC_API_TOKEN के रूप में set करें।
  4. Agent access बंद करना हो तो dashboard से token revoke करें।

Codex, Claude, Cursor और अन्य AI clients जोड़ें

सभी MCP-compatible AI clients वही remote endpoint और bearer token उपयोग करते हैं। Token को environment variable में रखें, prompts या source code में नहीं।

Remote MCP endpoint
https://bank-statement-conversion.com/mcp/bank-statement-conversion
Authentication header
Authorization: Bearer YOUR_API_TOKEN
Codex setup

यह server entry अपनी Codex config में जोड़ें।

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"

Token को shell या system environment में set करें, फिर AI client restart करें।

Token environment variablebash
export BSC_API_TOKEN="YOUR_API_TOKEN_HERE"
अन्य AI clients
  • Claude, Cursor और अन्य MCP clients को वही endpoint URL और Authorization bearer token उपयोग करना चाहिए।
  • ChatGPT Actions और custom agent builders को OpenAPI schema चाहिए तो MCP के बजाय /api/openapi.json उपयोग करें।
  • Knowledge files support करने वाले agents के लिए /llms.txt और /llms-full.txt को product context के रूप में उपयोग करें।

Scoped token abilities

account:statusconversion:uploadconversion:readconversion:download

वर्कफ़्लो एंडपॉइंट

अपने ऐप में दस्तावेज़ कन्वर्ज़न जोड़ने के लिए केवल ये एंडपॉइंट चाहिए।

एंडपॉइंटमेथडविवरण
/api/user-statusGETक्रेडिट, पेज सीमा और सदस्यता प्लान की वैकल्पिक प्रारंभिक जांच
/api/uploadPOSTकन्वर्ज़न के लिए बैंक स्टेटमेंट अपलोड करें
/api/conversion-status/{jobId}GETकन्वर्ज़न जॉब की स्थिति जांचें
/api/download/{downloadToken}GETस्थिति प्रतिक्रिया में लौटे टोकन से पूरा कन्वर्ज़न डाउनलोड करें

खाता स्थिति एंडपॉइंट

GET /api/user-status

जब आपके ऐप को यह पुष्टि करनी हो कि API टोकन में क्रेडिट, पेज सीमा या पेड-प्लान एक्सेस उपलब्ध है, तो अपलोड से पहले यह वैकल्पिक एंडपॉइंट उपयोग करें।

उपयोगी प्रतिक्रिया फ़ील्ड

फ़ील्डप्रकारविवरण
remaining_creditsintegerक्रेडिट-आधारित कन्वर्ज़न के लिए उपलब्ध क्रेडिट।
remaining_daily_pagesintegerप्रमाणित उपयोगकर्ता की शेष दैनिक पेज सीमा।
remaining_premium_pagesintegerप्रभावी प्लान की शेष मासिक प्रीमियम पेज सीमा।
plan_typestringAPI टोकन के लिए प्रभावी सदस्यता प्लान।

उदाहरण प्रतिक्रिया

JSON प्रतिक्रियाjson
क्लाइंट-साइड पार्सिंग और त्रुटि प्रबंधन के लिए यह संरचना कॉपी करें।
{
  "success": true,
  "remaining_credits": 42,
  "remaining_daily_pages": 100,
  "remaining_premium_pages": 950,
  "plan_type": "premium"
}

अपलोड एंडपॉइंट

POST /api/upload

इस एंडपॉइंट से आप कन्वर्ज़न के लिए बैंक स्टेटमेंट अपलोड करते हैं। कन्वर्ज़न असिंक्रोनस है और बाद में स्थिति जांचने के लिए आपको जॉब ID मिलेगी।

समर्थित इनपुट फ़ॉर्मैट

उपयोगफ़ॉर्मैटएक्सटेंशननोट्स
मानक कन्वर्ज़नPDF, 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बैंक स्टेटमेंट, इनवॉइस और रसीद कन्वर्ज़न के लिए उपयोग करें।
CSV क्लीनरCSV, XLS, XLSX.csv, .xls, .xlsxकेवल तब उपयोग करें जब format csv_clean हो।
भुगतान फ़ाइल जनरेशनCSV, XLS, XLSX.csv, .xls, .xlsxCSV या Excel payment rows के लिए उपयोग करें जो bank-ready ACH/NACHA, CPA005, SEPA XML, BACS, ABA या NZ payment files बनाते हैं।

समर्थित आउटपुट फ़ॉर्मैट

document_typeदस्तावेज़अनुमत format मान
bank_statementबैंक स्टेटमेंट
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
invoiceइनवॉइस
csvexceljsonqb_onlineqb_desktopubl_xmlubl_peppolxrechnung_ublzugferd_pdffactur_x_pdf
receiptरसीद
csvexceljson
payment_fileबैंक भुगतान फ़ाइल
payment_nachapayment_cpa005payment_sepa_pain001payment_bacspayment_abapayment_nz

अनुरोध पैरामीटर

पैरामीटरप्रकारआवश्यकविवरण
formatstringहांआउटपुट फ़ॉर्मैट। चुने हुए document_type के लिए ऊपर दिए गए अनुमत format मानों में से एक उपयोग करें।
document_typestringनहींDocument category: bank_statement, invoice, receipt, payment_file, or positive_pay_file. Defaults to bank_statement.
statementfile arrayहांकन्वर्ट करने वाली फ़ाइलें। एक या अधिक फ़ाइलें statement[] के रूप में भेजें।
separate_debit_creditbooleanनहींक्या डेबिट और क्रेडिट कॉलम अलग करने हैं। डिफ़ॉल्ट: false.
combine_filesbooleanनहींक्या कई फ़ाइलों को एक आउटपुट में मिलाना है। डिफ़ॉल्ट: false.

उदाहरण प्रतिक्रिया

JSON प्रतिक्रियाjson
क्लाइंट-साइड पार्सिंग और त्रुटि प्रबंधन के लिए यह संरचना कॉपी करें।
{
  "stage": "pending",
  "jobId": "5f3a7d8c-8a91-4a2e-9d3b-4c84f0636c12"
}

स्थिति एंडपॉइंट

GET /api/conversion-status/{jobId}

इस एंडपॉइंट से आप कन्वर्ज़न जॉब की स्थिति जांचते हैं। जॉब पूरा होने तक इसे पोल करें।

पाथ पैरामीटर

पैरामीटरप्रकारविवरण
jobIdstringअपलोड एंडपॉइंट से लौटाई गई जॉब ID

उदाहरण लंबित प्रतिक्रिया

JSON प्रतिक्रियाjson
क्लाइंट-साइड पार्सिंग और त्रुटि प्रबंधन के लिए यह संरचना कॉपी करें।
{
  "stage": "processing",
  "success": false,
  "previews": []
}

उदाहरण पूर्ण प्रतिक्रिया

JSON प्रतिक्रियाjson
क्लाइंट-साइड पार्सिंग और त्रुटि प्रबंधन के लिए यह संरचना कॉपी करें।
{
  "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
}

उदाहरण विफल प्रतिक्रिया

JSON प्रतिक्रियाjson
क्लाइंट-साइड पार्सिंग और त्रुटि प्रबंधन के लिए यह संरचना कॉपी करें।
{
  "stage": "complete",
  "success": false,
  "error": "An error occurred during the conversion process.",
  "message": "The uploaded file could not be processed.",
  "previews": []
}

डाउनलोड एंडपॉइंट

GET /api/download/{downloadToken}

पूर्ण स्थिति प्रतिक्रिया में लौटे download_token का उपयोग करें। डाउनलोड टोकन स्वयं न बनाएं।

पाथ पैरामीटर

पैरामीटरप्रकारविवरण
downloadTokenstringस्थिति प्रतिक्रिया में कन्वर्ट की गई फ़ाइल के लिए लौटाया गया download_token.

उदाहरण अनुरोध

cURL से डाउनलोडbash
टोकन और डाउनलोड टोकन बदलने के बाद टर्मिनल से चलाएं।
curl -L \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o converted_statement.csv \
  "https://bank-statement-conversion.com/api/download/Y8Jm7qVf9sR2kP6nL4xA0bT3cD5eF1gH"

उदाहरण प्रतिक्रिया

200 OK
कन्वर्ट की गई फ़ाइल को Content-Disposition: attachment के साथ बाइनरी डाउनलोड के रूप में लौटाता है। फ़ाइल एक्सटेंशन मांगे गए आउटपुट फ़ॉर्मैट पर निर्भर करता है, जैसे .csv, .xlsx, .qbo, .ofx, .xml, .json, .ach, .txt या .aba।

उदाहरण प्रतिक्रिया हेडर

प्रतिक्रिया हेडरhttp
डाउनलोड एंडपॉइंट 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
}

त्रुटि प्रबंधन

API अनुरोध की सफलता या विफलता बताने के लिए मानक HTTP स्टेटस कोड का उपयोग करता है।

स्टेटस कोडविवरण
200 OKअनुरोध सफल रहा
400 Bad Requestअनुरोध अमान्य था या आवश्यक पैरामीटर गायब थे
401 Unauthorizedप्रमाणीकरण विफल हुआ या टोकन अमान्य है
403 Forbiddenप्रमाणित उपयोगकर्ता को संसाधन तक पहुंच की अनुमति नहीं है
422 Unprocessable Entityवैलिडेशन त्रुटियां हुईं
500 Internal Server Errorसर्वर पर त्रुटि हुई

उदाहरण त्रुटि प्रतिक्रियाएं

401 अनधिकृतjson
क्लाइंट-साइड पार्सिंग और त्रुटि प्रबंधन के लिए यह संरचना कॉपी करें।
{
  "message": "Unauthenticated."
}
422 वैलिडेशन त्रुटिjson
क्लाइंट-साइड पार्सिंग और त्रुटि प्रबंधन के लिए यह संरचना कॉपी करें।
{
  "message": "The given data was invalid.",
  "errors": {
    "statement": [
      "The statement field is required."
    ],
    "format": [
      "The selected format is invalid."
    ]
  }
}
403 अपर्याप्त क्षमताjson
क्लाइंट-साइड पार्सिंग और त्रुटि प्रबंधन के लिए यह संरचना कॉपी करें।
{
  "success": false,
  "error": "Insufficient credits or page allowance for this conversion."
}

दर सीमाएँ

API के निष्पक्ष उपयोग के लिए आपके सदस्यता प्लान के आधार पर सीमाएं लागू होती हैं:

  • प्रीमियम उपयोगकर्ता: प्रति मिनट 100 अनुरोध
  • अधिकतम फ़ाइल आकार: प्रति फ़ाइल 100 MB
  • प्रति अनुरोध अधिकतम फ़ाइलें: 5

कोड उदाहरण

कन्वर्ज़न वर्कफ़्लो के पूरे उदाहरण: अपलोड, स्थिति पूछना, फिर डाउनलोड।

1. अपलोड2. स्थिति पूछें3. डाउनलोड
JavaScript उदाहरणjavascript
कन्वर्ट की गई फ़ाइल अपलोड, पोल और डाउनलोड करने के लिए axios और form-data का उपयोग करता है.
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}