개요
Bank Statement Conversion API는 자체 앱에 변환 기능을 추가하려는 개발자를 위한 문서입니다. 공개 변환 흐름인 계정 용량 확인, 파일 업로드, 작업 상태 조회, 반환된 토큰으로 완료된 결과 다운로드를 설명합니다.
이 참조 문서는 공개 변환 워크플로로 의도적으로 제한됩니다.
https://bank-statement-conversion.com/api빠른 시작
API 토큰 생성
대시보드에서 토큰을 생성하고 Authorization: Bearer YOUR_API_TOKEN 형식으로 보냅니다.
파일 업로드
/api/upload에 statement[], format, 선택적 변환 설정을 포함해 POST합니다.
작업 상태 조회
반환된 jobId를 /api/conversion-status/{jobId}에 사용해 preview에 download_token이 포함될 때까지 확인합니다.
출력 다운로드
/api/download/{downloadToken}에 GET 요청을 보내고 바이너리 응답을 변환된 파일로 저장합니다.
인증
API 토큰 인증
모든 API 요청에는 인증을 위한 API 토큰이 포함되어야 합니다. 토큰은 계정 대시보드의 API Tokens 섹션에서 생성할 수 있습니다.
API 토큰 생성 방법
- 계정에 로그인합니다
- 대시보드의 API Tokens 섹션으로 이동합니다
- "Create New Token"을 클릭하고 토큰 이름을 입력합니다
- 생성된 토큰을 복사해 안전하게 보관합니다. 토큰은 한 번만 표시됩니다.
API 토큰 사용
요청의 Authorization 헤더에 API 토큰을 포함하세요:
Authorization: Bearer YOUR_API_TOKENAI 에이전트
AI 에이전트와 API 사용
AI 도구는 개발자와 동일한 공개 변환 워크플로와 통합될 수 있습니다. OpenAPI 스키마, LLM 검색 파일 또는 MCP 엔드포인트를 사용하여 에이전트가 호출할 변환 엔드포인트와 확인이 필요한 작업을 알 수 있게 하세요.
에이전트 discovery
/api/openapi.json/llms.txt/llms-full.txt/mcp/bank-statement-conversion- ChatGPT Actions 또는 맞춤 에이전트 빌더처럼 스키마를 인식하는 도구에는
/api/openapi.json을 사용하세요. - 에이전트에 공식 제품 및 API 컨텍스트를 제공하려면
/llms.txt와/llms-full.txt를 사용하세요. - 원격 MCP 서버를 지원하는 MCP 호환 에이전트 클라이언트에는
/mcp/bank-statement-conversion을 사용하세요.
일회성 토큰 설정
- 한 번 로그인한 뒤 대시보드에서 API 토큰을 만드세요.
- 제한된 토큰이 필요하지 않다면 모든 변환 권한을 활성화해 두세요.
- MCP 클라이언트 환경에서 토큰을 BSC_API_TOKEN으로 설정하세요.
- 에이전트 접근을 중단해야 할 때 대시보드에서 토큰을 취소하세요.
Codex, Claude, Cursor 및 기타 AI 클라이언트 연결
모든 MCP 호환 AI 클라이언트는 동일한 원격 엔드포인트와 bearer token을 사용합니다. 토큰은 프롬프트나 소스 코드가 아니라 환경 변수에 보관하세요.
https://bank-statement-conversion.com/mcp/bank-statement-conversionAuthorization: Bearer YOUR_API_TOKENCodex 설정
이 서버 항목을 Codex 설정에 추가하세요.
[mcp_servers.bank_statement_conversion]
url = "https://bank-statement-conversion.com/mcp/bank-statement-conversion"
bearer_token_env_var = "BSC_API_TOKEN"shell 또는 시스템 환경에 토큰을 설정한 다음 AI 클라이언트를 다시 시작하세요.
export BSC_API_TOKEN="YOUR_API_TOKEN_HERE"기타 AI 클라이언트
- Claude, Cursor 및 기타 MCP 클라이언트는 동일한 엔드포인트 URL과 Authorization bearer token을 사용해야 합니다.
- ChatGPT Actions 및 맞춤 에이전트 빌더는 OpenAPI schema가 필요할 때 MCP 대신 /api/openapi.json을 사용해야 합니다.
- 지식 파일을 지원하는 에이전트에는 /llms.txt와 /llms-full.txt를 제품 컨텍스트로 사용하세요.
범위가 지정된 토큰 권한
워크플로 엔드포인트
애플리케이션에 문서 변환을 추가하는 데 필요한 엔드포인트는 다음뿐입니다.
| 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/api/user-status | GET | 크레딧, 페이지 한도, 구독 플랜을 확인하는 선택적 사전 점검 |
/api/upload | POST | 변환할 은행 명세서 업로드 |
/api/conversion-status/{jobId} | GET | 변환 작업 상태 확인 |
/api/download/{downloadToken} | GET | 상태 응답에서 반환된 토큰으로 완료된 변환 다운로드 |
계정 상태 엔드포인트
GET /api/user-status
앱에서 API 토큰에 사용 가능한 크레딧, 페이지 한도 또는 유료 플랜 접근 권한이 있는지 확인해야 할 때 업로드 전에 이 선택적 엔드포인트를 사용하세요.
유용한 응답 필드
| 필드 | 유형 | 설명 |
|---|---|---|
remaining_credits | integer | 크레딧 기반 변환에 사용할 수 있는 크레딧입니다. |
remaining_daily_pages | integer | 인증된 사용자에게 남은 일일 페이지 한도입니다. |
remaining_premium_pages | integer | 유효한 플랜에 남은 월간 프리미엄 페이지 한도입니다. |
plan_type | string | API 토큰에 적용되는 구독 플랜입니다. |
응답 예시
{
"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, .xlsx | CSV 또는 Excel 결제 행에서 은행 검토용 ACH/NACHA, CPA005, SEPA XML, BACS, ABA 또는 NZ 결제 파일을 생성할 때 사용합니다. |
지원 출력 형식
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 |
document_type=payment_file을 payment_nacha, payment_cpa005, payment_sepa_pain001, payment_bacs, payment_aba 또는 payment_nz와 함께 사용하세요. CSV, XLS 또는 XLSX를 statement[]로 업로드하면 기존 credits, history, download-token 워크플로를 사용합니다.
결제 파일 생성기 열기Use document_type=positive_pay_file with format=positive_pay. Upload CSV, XLS, or XLSX check rows as statement[] and pass positive_pay_settings for Chase, TD, generic CSV, or fixed-width profiles.
Open Positive Pay file generator요청 매개변수
| 매개변수 | 유형 | 필수 | 설명 |
|---|---|---|---|
format | string | 예 | 출력 형식입니다. 선택한 document_type에 대해 위에 나열된 허용 format 값 중 하나를 사용하세요. |
document_type | string | 아니요 | 문서 범주: bank_statement, invoice, receipt 또는 payment_file. 기본값: bank_statement. |
statement | file array | 예 | 변환할 파일입니다. 하나 이상의 파일을 statement[]로 보내세요. |
conversion_mode | string | 아니요 | 변환 모드: precision 또는 fast. 기본값은 precision입니다. |
separate_debit_credit | boolean | 아니요 | 차변 및 대변 열을 분리할지 여부입니다. 기본값: false. |
combine_files | boolean | 아니요 | 여러 파일을 단일 출력으로 결합할지 여부입니다. 기본값: false. |
응답 예시
{
"stage": "pending",
"jobId": "5f3a7d8c-8a91-4a2e-9d3b-4c84f0636c12"
}상태 엔드포인트
GET /api/conversion-status/{jobId}
이 엔드포인트로 변환 작업 상태를 확인합니다. 작업이 완료될 때까지 폴링하세요.
경로 매개변수
| 매개변수 | 유형 | 설명 |
|---|---|---|
jobId | string | 업로드 엔드포인트에서 반환된 작업 ID |
대기 중 응답 예시
{
"stage": "processing",
"success": false,
"previews": []
}완료 응답 예시
{
"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
}실패 응답 예시
{
"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을 사용하세요. 다운로드 토큰을 직접 만들지 마세요.
경로 매개변수
| 매개변수 | 유형 | 설명 |
|---|---|---|
downloadToken | string | 상태 응답에서 변환된 파일에 대해 반환된 download_token입니다. |
요청 예시
curl -L \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-o converted_statement.csv \
"https://bank-statement-conversion.com/api/download/Y8Jm7qVf9sR2kP6nL4xA0bT3cD5eF1gH"응답 예시
200 OK응답 헤더 예시
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 | 서버에서 오류가 발생했습니다 |
오류 응답 예시
{
"message": "Unauthenticated."
}{
"message": "The given data was invalid.",
"errors": {
"statement": [
"The statement field is required."
],
"format": [
"The selected format is invalid."
]
}
}{
"success": false,
"error": "Insufficient credits or page allowance for this conversion."
}속도 제한
API의 공정한 사용을 위해 구독 플랜에 따라 속도 제한이 적용됩니다:
- 프리미엄 사용자: 분당 100개 요청
- 최대 파일 크기: 파일당 100MB
- 요청당 최대 파일 수: 5개
코드 예제
업로드, 조회, 다운로드까지 변환 흐름의 전체 예시입니다.
npm install axios form-dataPython: pip install requestsPHP: PHP cURL extension enabledcURL: curl and jq installedGo: Go 1.20+Ruby: gem install multipart-postC#: .NET 7+npm install axios form-data1// 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}