eqlx-ebelge

Read Turkish e-Fatura (UBL-TR) and e-Defter (XBRL GL) files: clean data, a trial balance (mizan), and consistency checks that catch wrong totals, invalid tax ids, duplicate invoices and unbalanced journal entries. An optional MCP server lets AI agents such as Claude use the same functions, read-only.

Built by eqlx. Part of eqlx.org, open research and tools.

Status: alpha (0.1.1). Tested on synthetic documents and checked against GİB's public sample packages (e-Fatura, e-Arşiv, e-Defter): on those samples it raises no false alarms, and the findings it does raise are real inconsistencies in the samples. Please report any real-world file it reads wrongly (without sending the file itself).

Why

Lenders, factoring companies and finance teams receive invoices and ledgers as GİB XML and still read them by hand or through paid tools. This library turns them into data you can check and analyse, locally, with no network access.

Install

pip install "eqlx-ebelge[mcp] @ git+https://github.com/eqlx-ai/eqlx-ebelge"

Python 3.10+. The core needs only defusedxml; [mcp] adds the MCP server.

Command line

ebelge sample demo          # write 10 synthetic files to try it on
ebelge check demo           # every check, on files, folders or ZIP archives
ebelge invoices demo --csv  # one row per invoice
ebelge mizan demo           # trial balance from e-Defter journals (add --level sub)

$ ebelge check demo
10 documents: 9 invoices, 1 ledger files (7 entries). 2 errors, 1 warnings, 0 info.

severity  code                file                         message
error     payable             fatura_08_toplam_hatali.xml  TaxInclusiveAmount - withholding + rounding = 4682.88, PayableAmount is 99999.99 (gap 95317.11)
error     tax_id_check_digit  fatura_09_vkn_hatali.xml     supplier VKN 4477127821 fails its check digit
warning   possible_duplicate  fatura_02.xml                supplier 4477127820, same customer, 2026-10-07, payable 10140.12: EQX2026000000002 (fatura_02.xml), EQX2026000000007 (fatura_07.xml)

$ ebelge mizan demo
account  name             debit      credit     debit_bal  credit_bal
100      KASA             10000.00   8500.00    1500.00    0
102      BANKALAR         560000.00  10000.00   550000.00  0
120      ALICILAR         90000.00   60000.00   30000.00   0
...

ebelge check exits with code 1 when it finds an error, so it can gate a pipeline.

Python

from pathlib import Path
import eqlx_ebelge as eb

inv = eb.read_invoice(Path("fatura.xml").read_bytes(), "fatura.xml")
inv.supplier.tax_id, inv.totals.payable, [line.name for line in inv.lines]
eb.check_invoice(inv)  # list of Finding(code, severity, message, ...)

report = eb.scan(["inbox/", "archive.zip"])  # every document, every check, duplicates across all
report.summary()

ledgers = [eb.read_ledger(p.read_bytes(), p.name) for p in sorted(Path("edefter").glob("*.xml"))]
rows = eb.trial_balance(ledgers)  # e.g. twelve monthly journals -> one year's mizan

Amounts are Decimal, never floats.

Checks

Tolerances: one kuruş per comparison, plus half a kuruş per line where per-line rounding adds up.

MCP server (for Claude and other agents)

The server exposes four read-only tools: list_documents, check, read_invoices and trial_balance. It reads only inside the folder you give it; .., absolute paths and symlinks that point outside are refused.

Claude Code:

claude mcp add ebelge -- ebelge mcp --root /path/to/invoices

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "ebelge": { "command": "ebelge", "args": ["mcp", "--root", "/path/to/invoices"] }
  }
}

Then ask, for example: "Bu klasördeki faturaları kontrol et, sorunlu olanları ve mükerrerleri göster."

Safety and privacy

• Runs locally. No network access, no telemetry.
• XML with a DOCTYPE is refused, which blocks entity-expansion and external-entity (XXE) attacks.
• ZIP archives are read in memory with limits on size, file count and compression ratio.
• From e-Defter it keeps only what the checks and the trial balance need; entry comments, document numbers and people's names are not read.
• Tests use synthetic documents only. ebelge sample writes the same kind of made-up files.

See LIMITS.md for what it does not do.

Development

uv sync --all-extras
uv run pytest
uv run ruff check . && uv run ruff format --check . && uv run mypy src

Contributions are welcome; see CONTRIBUTING.md.

License

Apache-2.0. See LICENSE and NOTICE. GİB schemas are not included.