Pain001
데모 사용해 보기 ›

레퍼런스

Pain001 기술 레퍼런스: CLI, Python API, REST

pain001 v0.0.56의 모든 플래그, 엔드포인트, 동작 — 희망 사항이 아니라 실제로 출시된 코드에서 가져왔습니다.

4 분 소요 최종 검토

이 레퍼런스는 pain001 v0.0.57의 명령줄 인터페이스, Python API, REST 마이크로서비스, 검증 파이프라인을 설명합니다. 여기에 기재된 모든 플래그와 엔드포인트, 동작은 희망 사항이 아니라 실제로 출시된 코드에서 가져온 것입니다.

Pain001은 11개의 ISO 20022 메시지 정의를 지원합니다. pain.001.001.03부터 pain.001.001.12까지(고객 자금이체 개시, 10개 버전)와 pain.008.001.02(고객 자동이체 개시)입니다.

1. 명령줄 인터페이스#

pain001 실행 파일은 기능을 하위 명령으로 묶어 제공합니다. 생성 관련 플래그만 지정해 실행하면 generate가 암묵적으로 호출되므로 기존 자동화는 그대로 동작합니다.

하위 명령 용도
generate 데이터 파일을 스키마 검증을 마친 ISO 20022 XML로 변환합니다(기본 명령).
validate XML을 작성하지 않고 입력 데이터를 검증합니다.
versions [--json] 지원되는 11개 메시지 정의를 모두 나열합니다.
inspect [--json] 메시지 유형의 필수 필드와 선택 필드를 표시합니다.
init [-o DIR] 메시지 유형에 맞는 시작용 CSV 템플릿을 생성합니다.
serve [--host] [--port] [--reload] FastAPI REST 마이크로서비스를 실행합니다(api 엑스트라 필요).
mcp 코어에 내장된 Model Context Protocol 서버를 실행합니다(도구 5개이며, 도구 17개를 갖춘 전체 서버는 pain001-mcp로 제공됩니다).
plugins list / show / disable 탐지된 로더, 검증기, 스킴, 라이터 플러그인을 확인하고 관리합니다.

generate 옵션

플래그 설명
-t, --xml-message-type 메시지 정의입니다. 예: pain.001.001.09.
-d, --data 입력 데이터입니다: .csv, .json, .jsonl, .db / .sqlite, .parquet, 또는 PGP로 암호화된 .gpg / .asc.
-o, --output-dir 생성된 XML이 저장되는 디렉터리입니다.
-m, --template / -s, --schema 번들로 제공되는 Jinja2 템플릿 또는 XSD 스키마를 재정의합니다.
-c, --config 구성 프로필에서 기본값을 불러옵니다(--profile, --show-config).
--dry-run(별칭 --validate-only) 출력을 작성하지 않고 JSON Schema, XSD, 스킴 룰북에 대해 입력을 검증합니다.
--scheme 스킴 룰북을 적용합니다: sepa-sct, sepa-inst, sepa-sdd, sepa-b2b, 또는 xborder-ct.
--explain --scheme-format {text,json} 통과하거나 실패한 각 스킴 규칙을 사람이 읽는 형식 또는 기계가 읽는 형식으로 보고합니다.
--streaming / --chunk-size 대규모 배치를 위한 메모리 제한 청크 처리입니다(기본값은 청크당 1,000건의 거래이며, 각 청크는 NbOfTxs와 CtrlSum을 다시 계산한 별도의 XML 파일이 됩니다).
--emit-metrics 관측 가능성 파이프라인을 위해 기계가 읽을 수 있는 실행 지표를 내보냅니다.

종료 코드는 CI 친화적입니다. 0은 성공, 1은 검증 실패, 2는 사용법 오류입니다.

2. Python API#

from pain001.core.core import process_files

# Generate a validated pain.001.001.09 file from CSV
process_files(
    xml_message_type="pain.001.001.09",
    xml_template_file_path="template.xml",
    xsd_schema_file_path="schema.xsd",
    data_file_path="payments.csv",
    output_dir="out",
)

생성되는 모든 문서는 기록되기 전에 세 개의 계층을 통과합니다:

  1. 입력 검증 — 각 레코드는 해당 메시지 유형의 JSON Schema에 대해 검사되며, 필드 별칭 정규화와 IBAN/BIC 구문 검사가 함께 수행됩니다.
  2. 스킴 룰북(선택) — SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B 또는 국경 간 자금이체 규칙입니다.
  3. XSD 검증 — 렌더링된 XML은 디스크에 단 1바이트라도 기록되기 전에 xmlschema를 통해 공식 ISO 20022 스키마에 대해 검증됩니다.

금액은 XML 생성과 스킴 검증 과정에서 IEEE 754 부동소수점이 아니라 decimal.Decimal로 처리되며, NbOfTxs / CtrlSum 통제 합계는 입력값을 그대로 신뢰하지 않고 검증된 레코드로부터 다시 계산됩니다.

코어 라이브러리는 pain.001 생성 외에도 pain.002 상태 보고서 파서 및 생성기(은행의 승인·거절 응답을 읽을 수 있습니다)와 일일 마감 대사를 위한 camt.053 명세서 파서 및 생성기, 그리고 메시지 버전 간에 레코드를 이전하는 VersionMapper를 함께 제공합니다.

3. REST 마이크로서비스#

pip install "pain001[api]"
pain001 serve --host 0.0.0.0 --port 8000

모든 엔드포인트는 /api/v1 아래에 마운트됩니다(버전이 없는 /api 별칭도 제공됩니다):

메서드 및 경로 용도
GET /api/v1/health 활성 상태 프로브입니다.
POST /api/v1/validate 레코드를 검증하고 필드 단위 오류를 반환합니다.
POST /api/v1/generate 동기 방식 XML 생성입니다.
POST /api/v1/generate/async 대규모 배치를 백그라운드 생성 작업으로 큐에 넣습니다.
GET /api/v1/status/{job_id} 비동기 작업의 상태를 조회합니다.
GET /api/v1/download/{job_id} 완성된 XML을 내려받습니다.
DELETE /api/v1/jobs/{job_id} 완료된 작업을 정리합니다.
GET /metrics Prometheus 지표입니다.

대화형 문서는 /api/docs(Swagger UI), /api/redoc, /api/reference(Scalar)에서 제공되며, OpenAPI 문서는 /openapi.json에 있습니다.

4. 입력 정규화#

Pain001은 검증에 앞서 실무에서 내보낸 데이터를 유효한 레코드로 변환합니다:

  • 필드 별칭 — 흔히 쓰이는 ERP 열 이름을 표준 필드에 매핑합니다(예: amount → payment_amount).
  • IBAN / BIC 정규화 — 공백을 제거하고 대소문자를 통일한 뒤 검사합니다(IBAN은 ISO 13616 mod-97, BIC은 ISO 9362 구조).
  • 날짜 — 실행일을 ISO 8601 YYYY-MM-DD 형식으로 구문 분석합니다.
  • 금액 — decimal.Decimal을 거쳐 처리되며, 형식이 잘못된 금액은 조용히 반올림되지 않고 검증에 실패합니다.
  • 문자 집합 — 음역 도우미가 내용을 SWIFT와 SEPA가 허용하는 ISO 20022 라틴 문자 집합으로 줄여 줍니다.

5. 플러그인 아키텍처#

이 제품군은 네 개의 엔트리 포인트 그룹을 통해 확장할 수 있습니다: pain001.loaders, pain001.validators, pain001.schemes, pain001.writers. pain001-loader-xlsx는 이 메커니즘으로 등록되어 설치 시 자동으로 탐지됩니다. pain001-loader-mt101은 직접 사용하는 독립형 파싱 라이브러리이며, MCP 서버의 convert_mt101 도구도 이를 사용합니다. 차단 스위치인 PAIN001_DISABLE_PLUGINS=1은 통제된 환경에서 서드파티 플러그인 탐지를 완전히 비활성화합니다.

6. 품질 게이트#

코어 라이브러리는 엄격하고 검증 가능한 게이트를 기준으로 개발됩니다. CI에서 강제되는 100% 라인 및 분기 커버리지(--cov-fail-under=100), 엄격한 mypy 타이핑, 100% 독스트링 커버리지, 보안 린팅(Bandit, pip-audit)이 적용됩니다. 모든 릴리스 빌드마다 CycloneDX SBOM이 생성됩니다.

이어서 설치 가이드, AI 에이전트를 위한 MCP 서버, 또는 지급 용어집을 살펴보세요.