Skip to content
Back to search

ValidadorInteligenteFacturasDian

Intelligent validator for Colombian DIAN e-invoices (UBL 2.1): deterministic rules + Claude where it adds value, MCP server, evals in CI

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jtrejos05--validadorinteligentefacturasdian/badge.svg)](/listings/jtrejos05--validadorinteligentefacturasdian)

HTML

<a href="/listings/jtrejos05--validadorinteligentefacturasdian"><img src="/api/listings/jtrejos05--validadorinteligentefacturasdian/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requirements: Python 3.11+ with [uv](https://docs.astral.sh/uv/), and Node 20+.

# Backend (http://127.0.0.1:8000, docs at /docs)
cd backend
uv sync
uv run uvicorn app.main:app --reload

# Frontend (http://localhost:5173), in another terminal
cd frontend
npm install
npm run dev

**No API key is needed.** Without one, the app uses a deterministic mock LLM, so the full demo works offline. To use Claude:

export ANTHROPIC_API_KEY=sk-ant-...   # or create backend/.env from .env.example

The UI ships **28 sample invoices**: valid ones, ones with each defect sown in, semantic cases, and PDF+XML cases. Pick one from the dropdown or download its XML/PDF.

Live demo (Vercel)

**https://dian-validator.vercel.app** runs with the mock LLM, so anyone can try it at no cost.

It is deployed as two Vercel projects from this repo:

| Project | Root | What it is | |---|---|---| | `dian-validator` | `frontend/` | Vite static build. `vercel.json` rewrites `/api/*` to the API, so the app is same-origin and needs no CORS | | `dian-validator-api` | `backend/` | FastAPI, auto-detected by Vercel (`app/main.py`), Python 3.12 |

Serverless functions have no persistent disk, so the API stores reports in Postgres when `DATABASE_URL` (or `POSTGRES_URL`) is set, for example Neon from the Vercel Marketplace. Without it, it falls back to SQLite (locally in `data/`, on Vercel in an ephemeral `/tmp`).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 175 lines
  1. # Intelligent DIAN Invoice Validator
  2. This tool validates Colombian electronic invoices (*factura electrónica de venta*, DIAN, UBL 2.1) before an accounts-payable team pays them. Deterministic code handles everything that can be computed, and an LLM handles the few things only reading and judgment can do. A human decides whenever the system is unsure.
  3. > **Python · FastAPI · Claude API · MCP · React + TypeScript · SQLite · GitHub Actions**
  4. ---
  5. ## 1. The problem
  6. In Colombian AP teams, an analyst checks each supplier invoice before payment. Typical problems:
  7. - **Tampered or miscalculated invoices.** The CUFE (the invoice's SHA-384 fingerprint) does not match the data.
  8. - **Wrong NIT or check digit.** The IVA cannot be deducted, so the invoice has to be reissued.
  9. - **Arithmetic and tax errors.** Line totals, IVA rates (19 / 5 / 0 %), or a payable amount that does not add up.
  10. - **Numbering resolution issues.** An expired resolution, a number outside the authorized range, a wrong prefix, or another issuer's resolution.
  11. - **Semantic errors.** Medicines or basic foods charged 19% IVA, or consulting billed at 0%. These are valid arithmetic but wrong tax treatment, and no simple rule catches them.
  12. - **PDF vs XML mismatch.** People pay from the PDF, but the XML is the legal document.
  13. A manual check takes several minutes per invoice and is error-prone. The goal is to auto-resolve the clear cases, approving the clean ones and rejecting the broken ones, and to send only the ambiguous ones to a person with a plain-language explanation.
  14. ## 2. Approach: choose the right intervention per check
  15. The request "an agent that validates invoices" was treated as a hypothesis. Breaking the process down showed that most checks are exact computations. → [ADR 0001](docs/adr/0001-deterministic-core-llm-at-the-edges.md)
  16. ```
  17. ┌──────────────────────── deterministic ────────────────────────┐
  18. XML ──► parse (XXE-safe) ──► rules: structure · NIT DV · CUFE · totals · │
  19. │ tax rates · dates · numbering resolution │
  20. │ │ │
  21. PDF/img ─► LLM extraction ──► cross-check vs XML (warning) ──┐ │
  22. │ │ ├─► decision ──┼─► LLM explanation
  23. lines ───► LLM semantic tax review (warning) ──┘ │ policy │ (Spanish, for AP)
  24. └──────────────────────────────────────────────────┴──────────────┘
  25. │
  26. needs_review ──► human review queue (UI / API)
  27. ```
  28. | Layer | What it does | Why this tool |
  29. |---|---|---|
  30. | **Rules** (`app/rules/`) | CUFE recomputation per Anexo Técnico 1.9, NIT check digit, totals, allowed rates, resolution range and validity, mandatory fields | Exact, free, instant, auditable |
  31. | **LLM: semantic review** (`app/ai/tax_review.py`) | Does the IVA rate fit the product described? | Needs reading comprehension plus tax knowledge |
  32. | **LLM: extraction** (`app/ai/extractor.py`) | Reads the PDF or image the supplier sent | Perception; layouts vary per supplier |
  33. | **LLM: explanation** (`app/ai/explainer.py`) | Turns findings into next steps for an accountant | Language generation |
  34. | **Policy** (`pipeline.decide`) | Rule error → reject · any warning → review · else approve | Must be predictable and auditable |
  35. | **Human in the loop** | Review queue with approve/reject plus audit note | Final say on anything uncertain |
  36. **Guardrails** ([ADR 0002](docs/adr/0002-ai-findings-are-warnings-human-in-the-loop.md))
  37. - AI findings are capped at *warning*, so the model can escalate an invoice but can never reject or approve one.
  38. - All model output is schema-constrained JSON.
  39. - Invoice content is treated as untrusted data in every prompt, as a prompt-injection defense.
  40. - The XML parser has external entities and network access disabled (XXE).
  41. - Upload size and type limits are enforced.
  42. - Validation degrades gracefully if the model is down.
  43. ## 3. Quickstart
  44. Requirements: Python 3.11+ with [uv](https://docs.astral.sh/uv/), and Node 20+.
  45. ```bash
  46. # Backend (http://127.0.0.1:8000, docs at /docs)
  47. cd backend
  48. uv sync
  49. uv run uvicorn app.main:app --reload
  50. # Frontend (http://localhost:5173), in another terminal
  51. cd frontend
  52. npm install
  53. npm run dev
  54. ```
  55. **No API key is needed.** Without one, the app uses a deterministic mock LLM, so the full demo works offline. To use Claude:
  56. ```bash
  57. export ANTHROPIC_API_KEY=sk-ant-... # or create backend/.env from .env.example
  58. ```
  59. The UI ships **28 sample invoices**: valid ones, ones with each defect sown in, semantic cases, and PDF+XML cases. Pick one from the dropdown or download its XML/PDF.
  60. ### Live demo (Vercel)
  61. **https://dian-validator.vercel.app** runs with the mock LLM, so anyone can try it at no cost.
  62. It is deployed as two Vercel projects from this repo:
  63. | Project | Root | What it is |
  64. |---|---|---|
  65. | `dian-validator` | `frontend/` | Vite static build. `vercel.json` rewrites `/api/*` to the API, so the app is same-origin and needs no CORS |
  66. | `dian-validator-api` | `backend/` | FastAPI, auto-detected by Vercel (`app/main.py`), Python 3.12 |
  67. Serverless functions have no persistent disk, so the API stores reports in Postgres when `DATABASE_URL` (or `POSTGRES_URL`) is set, for example Neon from the Vercel Marketplace. Without it, it falls back to SQLite (locally in `data/`, on Vercel in an ephemeral `/tmp`).
  68. ## 4. API
  69. | Method | Path | Description |
  70. |---|---|---|
  71. | `POST` | `/api/validate` | Multipart: `xml` and/or `attachment` (PDF/PNG/JPG). Returns the report |
  72. | `GET` | `/api/reports?review_status=pending` | History and review queue |
  73. | `POST` | `/api/reports/{id}/review` | Human decision `{decision, note}` |
  74. | `GET` | `/api/metrics` | Auto-resolution rate, AI cost and latency, top findings, business case |
  75. | `GET` | `/api/samples` · `POST /api/samples/{name}/validate` | Demo data |
  76. ## 5. MCP server (agent integration)
  77. The validator is also an MCP server, so agents (Claude Code, AP bots, n8n) can call it as tools. → [ADR 0004](docs/adr/0004-mcp-server-for-agent-integration.md)
  78. ```bash
  79. claude mcp add dian-validator -- uv --directory /path/to/repo/backend run python mcp_server.py
  80. ```
  81. Tools:
  82. - `validate_invoice(xml, use_ai)`
  83. - `run_dian_rules(xml)`
  84. - `check_nit(nit, check_digit)`
  85. - `recompute_cufe(xml, technical_key)`
  86. ## 6. Quality: tests and evals
  87. ```bash
  88. cd backend
  89. uv run pytest -q # 85 unit / integration tests
  90. uv run python -m evals.run_evals # offline evals with quality gates
  91. uv run python -m evals.run_evals --live # same evals against Claude
  92. ```
  93. The eval set (`evals/cases.py`) is **28 labeled synthetic invoices**, each with known defects. The harness reports:
  94. | Metric | Gate | What it protects |
  95. |---|---|---|
  96. | Rule precision / recall | 1.0 | Every sown defect is caught, with no false alarms |
  97. | AI recall (semantic + PDF cases) | ≥ 0.66 | The model catches what rules cannot |
  98. | AI false-positive rate | ≤ 0.10 | The model does not flood reviewers |
  99. | Decision accuracy | ≥ 0.90 | End-to-end behavior |
  100. | Cost and latency per invoice | Tracked | Unit economics |
  101. CI ([.github/workflows/ci.yml](.github/workflows/ci.yml)) runs lint, tests, offline evals and the frontend build on every push and PR. Live evals run on `main` when an `ANTHROPIC_API_KEY` secret is configured.
  102. Note: the mock passes the AI evals by construction. Offline AI scores prove the plumbing; the live run measures the model ([ADR 0003](docs/adr/0003-llm-gateway-structured-outputs-and-mock.md)).
  103. ## 7. Observability and business case
  104. Every LLM call is traced: purpose, model, input/output tokens, latency, estimated USD cost and errors. Traces are stored with each report and aggregated on the **Metrics** page:
  105. - Share of invoices resolved without a human. This is the efficiency lever.
  106. - AI cost per invoice. Typically one or two low-effort calls; zero when rules reject or nothing is found.
  107. - Estimated analyst hours and COP saved. The assumptions are editable and shown on screen: `DIAN_MANUAL_MINUTES_PER_INVOICE` (default 6) and `DIAN_ANALYST_COST_COP_PER_HOUR` (default 35,000).
  108. ## 8. Repository layout
  109. ```
  110. backend/
  111. app/
  112. rules/ deterministic DIAN checks (cufe, nit, totals, dates, structure)
  113. ai/ llm gateway + tax_review, extractor, explainer
  114. parsing/ hardened UBL 2.1 parser
  115. pipeline.py orchestration + decision policy
  116. main.py FastAPI
  117. synthetic.py invoice generator with defect injection
  118. mcp_server.py MCP tools
  119. evals/ labeled cases + harness
  120. tests/
  121. frontend/ React + TypeScript (Vite)
  122. docs/adr/ architecture decision records
  123. ```
  124. ## 9. Limitations and next steps
  125. - **No XAdES signature check.** The XML digital signature is not verified yet; that would be the next deterministic rule. The CUFE check already detects data tampering when the technical key is known.
  126. - **No live DIAN lookup.** Technical keys come from a local catalog (`app/data/resolutions.json`). In production they would come from the DIAN enablement service, and the CUFE status from the DIAN web service.
  127. - **Partial document coverage.** Credit and debit notes (CUDE), INC/ICA edge cases, withholdings (*retenciones*), and foreign currency are partially covered.
  128. - **Semantic tax review is advisory.** Colombian IVA rules have many exceptions; the review flags cases for a tax specialist and is not tax advice.
  129. - **Synthetic eval data.** The next step is a sample of real, anonymized supplier invoices with labels from the AP team.
  130. - **Integrations.** Possible next steps: an email inbox listener, an ERP push (SAP / Siigo) on approval, and webhooks on review decisions.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.