API 문서 - Bank-Statement-Conversion

Bank Statement Conversion API

업로드, 상태 확인, 다운로드 흐름으로 변환 기능을 추가하세요.

개요

Bank Statement Conversion API는 자체 앱에 변환 기능을 추가하려는 개발자를 위한 문서입니다. 공개 변환 흐름인 계정 용량 확인, 파일 업로드, 작업 상태 조회, 반환된 토큰으로 완료된 결과 다운로드를 설명합니다.

이 참조 문서는 공개 변환 워크플로로 의도적으로 제한됩니다.

빠른 시작

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 스키마, 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을 사용하세요.

일회성 토큰 설정

  1. 한 번 로그인한 뒤 대시보드에서 API 토큰을 만드세요.
  2. 제한된 토큰이 필요하지 않다면 모든 변환 권한을 활성화해 두세요.
  3. MCP 클라이언트 환경에서 토큰을 BSC_API_TOKEN으로 설정하세요.
  4. 에이전트 접근을 중단해야 할 때 대시보드에서 토큰을 취소하세요.

Codex, Claude, Cursor 및 기타 AI 클라이언트 연결

모든 MCP 호환 AI 클라이언트는 동일한 원격 엔드포인트와 bearer token을 사용합니다. 토큰은 프롬프트나 소스 코드가 아니라 환경 변수에 보관하세요.

원격 MCP 엔드포인트
https://bank-statement-conversion.com/mcp/bank-statement-conversion
인증 헤더
Authorization: Bearer YOUR_API_TOKEN
Codex 설정

이 서버 항목을 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"

shell 또는 시스템 환경에 토큰을 설정한 다음 AI 클라이언트를 다시 시작하세요.

Token environment variablebash
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를 제품 컨텍스트로 사용하세요.

범위가 지정된 토큰 권한

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, .xlsxformat이 csv_clean일 때만 사용합니다.
결제 파일 생성CSV, XLS, XLSX.csv, .xls, .xlsxCSV 또는 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

요청 매개변수

매개변수유형필수설명
formatstring출력 형식입니다. 선택한 document_type에 대해 위에 나열된 허용 format 값 중 하나를 사용하세요.
document_typestring아니요문서 범주: bank_statement, invoice, receipt 또는 payment_file. 기본값: bank_statement.
statementfile array변환할 파일입니다. 하나 이상의 파일을 statement[]로 보내세요.
conversion_modestring아니요변환 모드: precision 또는 fast. 기본값은 precision입니다.
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개 요청
  • 최대 파일 크기: 파일당 100MB
  • 요청당 최대 파일 수: 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}