Pain001
Gwada demo ›

Jagora

Jagorar Fasaha ta Pain001: CLI, Python API da REST

Kowace tuta, endpoint da hali na pain001 v0.0.56 — daga lambar da aka fitar, ba daga buri ba.

4 mintuna na karatu Bita ta ƙarshe

Wannan jagorar tana bayyana mahaɗar layin umarni, Python API, ƙaramar hidimar REST, da kuma tsarin tantancewa na pain001 v0.0.57. Kowace tuta, endpoint da hali da aka lissafa a nan an ɗauko su ne daga lambar da aka fitar, ba daga buri ba.

Pain001 tana goyon bayan ma'anonin saƙo 11 na ISO 20022: daga pain.001.001.03 zuwa pain.001.001.12 (fara tura kuɗi na abokin ciniki, sigogi goma) da kuma pain.008.001.02 (fara cirar kuɗi kai tsaye na abokin ciniki).

1. Mahaɗar Layin Umarni#

Fayil ɗin aiwatarwa na pain001 yana tara ayyukansa cikin ƙananan umarni. Idan ka gudanar da shi da tutocin ƙirƙira kaɗai, yana kiran generate a fakaice, don haka tsarin sarrafa kai da kake da shi zai ci gaba da aiki.

Ƙaramin umarni Manufa
generate Juya fayil ɗin bayanai zuwa XML na ISO 20022 wanda aka tantance da schema (umarnin tsoho).
validate Tantance bayanan shigarwa ba tare da rubuta XML ba.
versions [--json] Lissafa dukkan ma'anonin saƙo 11 da ake goyon baya.
inspect [--json] Nuna filayen wajibi da na zaɓi ga wani nau'in saƙo.
init [-o DIR] Ƙirƙiri samfurin CSV na farawa ga wani nau'in saƙo.
serve [--host] [--port] [--reload] Ƙaddamar da ƙaramar hidimar REST ta FastAPI (tana buƙatar ƙarin api).
mcp Ƙaddamar da sabar Model Context Protocol da ke cikin lambar (kayan aiki 5; cikakkiyar sabar mai kayan aiki 17 tana zuwa a matsayin pain001-mcp).
plugins list / show / disable Duba da sarrafa plugins na loader, validator, scheme da writer da aka gano.

Zaɓuɓɓukan generate

Tuta Bayani
-t, --xml-message-type Ma'anar saƙo, misali pain.001.001.09.
-d, --data Bayanan shigarwa: .csv, .json, .jsonl, .db / .sqlite, .parquet, ko .gpg / .asc da aka ɓoye da PGP.
-o, --output-dir Babban fayil ɗin da ke karɓar XML ɗin da aka ƙirƙira.
-m, --template / -s, --schema Sauya samfurin Jinja2 ko schema na XSD da aka haɗa a ciki.
-c, --config Ɗauko tsoffin ƙimomi daga bayanan sanyi (--profile, --show-config).
--dry-run (wani suna --validate-only) Tantance shigarwa bisa JSON Schema, XSD, da littafin ƙa'idar tsari ba tare da rubuta fitarwa ba.
--scheme Tilasta littafin ƙa'idar tsari: sepa-sct, sepa-inst, sepa-sdd, sepa-b2b, ko xborder-ct.
--explain --scheme-format {text,json} Bayar da rahoton kowace ƙa'idar tsari da ta ci nasara ko ta faɗi, a sigar da mutum ko na'ura za ta iya karantawa.
--streaming / --chunk-size Sarrafawa a gutsuttsura tare da iyakancewar ƙwaƙwalwa don manyan tarin bayanai (tsoho: mu'amala 1,000 a kowace gutsure; kowace gutsure tana zama fayil ɗin XML na kanta tare da NbOfTxs da CtrlSum da aka sake ƙidayawa).
--emit-metrics Fitar da ma'aunan gudanarwa da na'ura za ta iya karantawa don tsarin sa ido.

Lambobin fita suna dacewa da CI: 0 nasara, 1 faɗuwar tantancewa, 2 kuskuren amfani.

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",
)

Kowace takardar da aka ƙirƙira tana wucewa ta yadudduka uku kafin a rubuta ta:

  1. Tantance shigarwa — ana duba kowane rikodi bisa JSON Schema na nau'in saƙon, tare da daidaita sunayen filaye da duba tsarin IBAN/BIC.
  2. Littafin ƙa'idar tsari (na zaɓi) — ƙa'idojin SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B, ko na tura kuɗi tsakanin ƙasashe.
  3. Tantancewar XSD — ana tantance XML ɗin da aka samar bisa schema na hukuma na ISO 20022 ta hanyar xmlschema kafin a rubuta ko baiti ɗaya a faifai.

Ana sarrafa kuɗaɗe a matsayin decimal.Decimal yayin ƙirƙirar XML da tantance tsari — ba a taɓa amfani da floats na IEEE 754 ba — kuma ana sake ƙidaya jimillolin sarrafawa na NbOfTxs / CtrlSum daga rikodin da aka tantance maimakon dogara ga shigarwa.

Baya ga ƙirƙirar pain.001, ɗakin karatu na tushe yana kuma zuwa da mai karantawa da ƙirƙirar rahoton matsayi na pain.002 (don ka iya karanta amsar karɓa ko ƙi ta bankinka) da kuma mai karantawa da ƙirƙirar bayanin asusu na camt.053 don daidaita asusu a ƙarshen rana, tare da VersionMapper da ke tura rikodi tsakanin sigogin saƙo.

3. Ƙaramar Hidimar REST#

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

Ana ɗora dukkan endpoints a ƙarƙashin /api/v1 (tare da wani suna maras siga /api):

Hanya & Adireshi Manufa
GET /api/v1/health Binciken lafiyar sabis.
POST /api/v1/validate Tantance rikodi; yana mayar da kurakurai a matakin filaye.
POST /api/v1/generate Ƙirƙirar XML kai tsaye.
POST /api/v1/generate/async Sanya babban tari a jerin gwano don ƙirƙira a baya.
GET /api/v1/status/{job_id} Duba matsayin aikin async.
GET /api/v1/download/{job_id} Sauke XML ɗin da aka gama.
DELETE /api/v1/jobs/{job_id} Share aikin da aka kammala.
GET /metrics Ma'aunan Prometheus.

Ana bayar da takardun hulɗa a /api/docs (Swagger UI), /api/redoc, da /api/reference (Scalar), yayin da takardar OpenAPI take a /openapi.json.

4. Daidaita Bayanan Shigarwa#

Pain001 tana mayar da bayanan da aka fitar daga tsarin aiki na hakika zuwa rikodi masu inganci kafin tantancewa:

  • Sunayen madadin filaye — sunayen ginshiƙai da suka zama ruwan dare a ERP suna daidaituwa da filayen asali (misali amount → payment_amount).
  • Daidaita IBAN / BIC — ana cire fanko, a daidaita manya da ƙanana haruffa, sannan a duba (ISO 13616 mod-97 don IBAN, tsarin ISO 9362 don BIC).
  • Kwanaki — ana karanta ranakun aiwatarwa a tsarin ISO 8601 YYYY-MM-DD.
  • Kuɗaɗe — suna wucewa ta decimal.Decimal; kuɗaɗen da ba su da tsari mai kyau suna faɗin tantancewa maimakon a zagaye su a shiru.
  • Tarin haruffa — kayan taimako na canza rubutu suna mayar da abun ciki zuwa tarin haruffan Latin na ISO 20022 da SWIFT da SEPA suke karɓa.

5. Gine-ginen Plugin#

Ana iya faɗaɗa wannan tsarin ta ƙungiyoyin shiga huɗu: pain001.loaders, pain001.validators, pain001.schemes, da pain001.writers. pain001-loader-xlsx yana yin rijista ta wannan hanya kuma ana gano shi kai tsaye bayan shigarwa; pain001-loader-mt101 ɗakin karatu ne mai zaman kansa na karanta fayiloli da ake amfani da shi kai tsaye (haka kuma kayan aikin convert_mt101 na sabar MCP yana amfani da shi). Wani maɓallin kashewa — PAIN001_DISABLE_PLUGINS=1 — yana kashe gano plugins na waje gaba ɗaya a muhallai masu tsauraran ƙa'idoji.

6. Ƙofofin Inganci#

Ana haɓaka ɗakin karatu na tushe bisa ƙofofi masu tsauri da ake iya tabbatarwa: rufin gwaji na kashi 100% na layuka da na rassa da ake tilastawa a CI (--cov-fail-under=100), tsauraran nau'ika na mypy, kashi 100% na docstring, da binciken tsaro (Bandit, pip-audit). Ana samar da SBOM na CycloneDX ga kowace fitarwa.

Ci gaba da Jagorar Shigarwa, sabar MCP don wakilan AI, ko ƙamus ɗin biyan kuɗi.