Skip to main content

pyefris

Python client for the URA EFRIS (Electronic Fiscal Receipting and Invoicing Solution) system-to-system API, per Interface Design for EFRIS v24.0.1.

Features:

  • Full wire protocol: {data, globalInfo, returnStateInfo} envelope, one POST endpoint, dataDescription encryption flags per interface.
  • Online-mode crypto exactly as URA requires: content = base64(AES-ECB/PKCS7(json)), signature = base64(SHA1withRSA(content)), T104 session-key unwrap (RSA/PKCS1), auto-refresh on returnCode 401/402.
  • Offline-mode payload profile (base64 content, empty signature).
  • ACID outbox: every submission is recorded atomically in a SQLite (WAL, synchronous=FULL) store before it goes on the wire — idempotent retries, crash-safe replay, append-only audit log.
  • Typed pydantic v2 models for the core ~40 interfaces; client.call(code, ...) generic escape hatch for the rest of the 74-code registry.
  • Sync EfrisClient and AsyncEfrisClient (httpx).
  • Python ≥ 3.10. Dependencies: httpx, pydantic>=2, cryptography.

Install

pip install -e .          # local
pip install -e ".[dev]"   # with test/lint tooling

Quickstart

from pyefris import EfrisClient, EfrisConfig

cfg = EfrisConfig(
    tin="1000029771",
    device_no="TCS9e0df01728335239",
    private_key_path="keys/taxpayer_private.pem",  # RSA-2048, registered w/ URA
    environment="test",                            # or "prod"
    store_path="pyefris.db",
)

with EfrisClient(cfg) as client:
    client.sync_clock()                     # T101: requestTime within ±10min
    result = client.invoicing.upload_invoice(invoice, reference_no="INV-0001")
    doc = result.model.exist_invoice_list[0]
    print(doc.invoice_no, doc.antifake_code, doc.qr_code)

Domain services: client.session (T101–T105), .taxpayer (T119/T137/T138/T180), .dictionary (T115/T123–T126/T134/T146), .goods (T127/T128/T130/T144), .stock (T131/T139/T145/T147–T149/T160), .invoicing (T106–T114/T116–T118/T120–T122/T129). Unmodeled interfaces: client.call("T167", {...}).

ACID guarantees

Property Mechanism
Atomicity intent (PENDING) + sealed envelope (SEALED) written in one BEGIN IMMEDIATE tx before network I/O; outcome + audit row in a second tx
Consistency UNIQUE(tin, device_no, interface_code, reference_no) blocks double-fiscalization; CHECK on status enum
Isolation WAL + busy_timeout; claims are compare-and-swap UPDATE ... WHERE status=? — threads/processes can't double-send
Durability synchronous=FULL; sealed envelope persisted before send; append-only audit_log (triggers forbid UPDATE/DELETE)

Recovery: client.relay_pending() re-sends the byte-identical stored envelope (same dataExchangeId, signature) so URA can dedupe. Run it on a schedule or client.start_worker() for a background thread. Retries use exponential backoff (RetryPolicy) for transport failures; business rejections (EfrisReturnCodeError) are terminal by design.

result = client.invoicing.upload_invoice(inv, reference_no="INV-1")          # raises on dup
result = client.invoicing.upload_invoice(inv, reference_no="INV-1",
                                         on_duplicate="return")            # returns stored record

Config reference

EfrisConfig(tin, device_no, private_key_pem|_path, environment="test"|"prod", mode="online"|"offline", endpoint=..., store_path=..., timeout_seconds=30, retry=RetryPolicy(...), server_public_key_pem=...). Also EfrisConfig.from_env() reads PYEFRIS_* variables. CLI: python -m pyefris server-time|login| sync-dictionaries|relay|call.

Security notes

  • SHA1withRSA signatures and AES-ECB are required by the URA spec, not a design choice of this package.
  • The decrypted AES session key is cached in the SQLite kv_state table — protect the store file with filesystem permissions.
  • RedactingFilter (pyefris.logging) scrubs keys/blobs from log records.
  • T102's white-box clientPriKey/keyTable decryption is AP01-only and not implemented (S2S/AP04 uses your own registered keypair).

Spec caveats captured in code

  • passowrdDes, buyerPlaceOfBusi, VehichleNo keep the spec's spellings.
  • T113/T114/T105/T120/T122 return unencrypted responses even though the request is encrypted.
  • InvoiceUpload allows spec additions via extra="allow" — unknown fields round-trip instead of being dropped.

Development

python -m pytest tests/          # 50 tests, no network needed
python -m ruff check src tests
python -m mypy src/pyefris       # strict mode

See AGENTS.md for architecture notes.

Metadata

Release files for pyefris 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyefris 1.0.1
File Size Uploaded Provenance Actions
pyefris-1.0.1.tar.gz 2.5 MB With provenance Details for pyefris-1.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pyefris 1.0.1
File Interpreter ABI Platform Actions
pyefris-1.0.1-py3-none-any.whl Python 3 none any Details for pyefris-1.0.1-py3-none-any.whl

Total release size: 2.6 MB

Release files / pyefris-1.0.1.tar.gz

Download URL pyefris-1.0.1.tar.gz
Size 2.5 MB
Tags Source
SHA-256 checksum
How to use checksums
112ca09a158860462e6441ceed3ee295cc647bfabd8422acbcec77b897bb5094
BLAKE2b-256 checksum
How to use checksums
d5fff13481f13c3a79b9f10b58dcfb68b644159d4146cdc6807add2688464c64
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / pyefris-1.0.1-py3-none-any.whl

Download URL pyefris-1.0.1-py3-none-any.whl
Size 65.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
dc9c43127e6fda1e317fdaff540b1428acb9bbc335d3edb97d659e09f1563fc9
BLAKE2b-256 checksum
How to use checksums
b2bde415c5edadd56c61f3a509af6857febc74924d7ed7743047b2c426e6af85
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Security for pyefris 1.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pyefris-1.0.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page