Skip to main content

EQinvoice

Electronic invoices and credit notes for Ecuador's SRI (offline scheme 1.1.0): build the voucher, sign it XAdES-BES with the issuer's .p12, send it, read the authorization back and print the RIDE. Use it as a library inside your own system, or as an MCP server that lets an assistant draft, preview, issue and follow one issuer's vouchers.

PyPI · Library · Claude Code plugin · MCP server

[your system] ──values──> [eqinvoice] ──signed XML──> [SRI reception] ──> [SRI authorization]
[assistant]   ──MCP────> [eqinvoice-mcp] ──> the book (clients, drafts, vouchers)

Install

pip install eqinvoice           # the library
pip install "eqinvoice[mcp]"    # with the MCP server

Python 3.11 or newer. In Claude Code, the plugin installs everything in one step.

Capabilities

  • Vouchers: invoices (factura) and credit notes (nota de crédito), checked against the SRI's own XSD before they leave.
  • Access key: the 49-digit clave de acceso with its modulo 11 check digit, and the issue date on the SRI's clock.
  • Signature: XAdES-BES with the issuer's .p12 and its password, refused with a reason when it is missing, unreadable or out of date.
  • SRI web services: reception and authorization, in the test environment (celcer) or in production (cel).
  • Taxpayer registry: a RUC looked up in the SRI's public registry (legal name, standing, regime, accounting duty, establishments), and the issuer its vouchers name.
  • Priced lines: a line's subtotal and IVA worked out to the cent from its quantity, unit price, discount and the SRI's rate code.
  • Printed copy (RIDE): an A4 page or an 80 mm strip, with the SRI's full block of totals and the access key as a barcode (page) or a QR code (strip).
  • Logo: a picture, or a mark and a name drawn as vectors, set beside each other as a lockup.
  • Labels: the printed words are data. Spanish by default, as the SRI prints them; any file of the same shape replaces them.
  • Simulation: a simulated signature, SRI and registry that answer on the spot, for development and tests.

Library

from datetime import UTC, datetime
from decimal import Decimal
from pathlib import Path

from eqinvoice import (
    Buyer,
    BuyerKind,
    Environment,
    Issuer,
    Payment,
    SriWebServices,
    Voucher,
    VoucherKind,
    access_key,
    issue_date,
    price_line,
    read,
    read_credential,
    sign_voucher,
)
from eqinvoice.ride import ImageLogo, Layout, render

issuer = Issuer(
    legal_name="ACME COMERCIAL S.A.S.",
    ruc="1790011223001",
    head_office_address="AV. AMAZONAS N10-20, QUITO",
    keeps_accounts=True,
)
credential = read_credential(Path("signature.p12"), "p12 password")
now = datetime.now(UTC)
issued_on = issue_date(now)
line = price_line("SKU-1", "Cafe molido (500 g)", Decimal("1"), Decimal("10.00"), "4")
voucher = Voucher(
    kind=VoucherKind.INVOICE,
    environment=Environment.TEST,
    access_key=access_key(
        issued_on, VoucherKind.INVOICE, issuer.ruc, Environment.TEST, "001", "001", 1
    ),
    establishment="001",
    point="001",
    sequential=1,
    establishment_address="AV. AMAZONAS N10-20, QUITO",
    issued_on=issued_on,
    buyer=Buyer(BuyerKind.CEDULA, "1710034065", "Ana Perez", "ana@example.com"),
    lines=(line,),
    payments=(Payment("01", Decimal("11.50")),),
)

document = sign_voucher(voucher, issuer, credential, now)
sri = SriWebServices(Environment.TEST)
reception = sri.send(document)
answer = sri.authorize(voucher.access_key)

if answer is not None and answer.authorized:
    issued = read(answer.record)
    page = render(issued, Layout.PAGE, logo=ImageLogo(Path("logo.png")))
    strip = render(issued, Layout.TICKET, logo=ImageLogo(Path("logo.png")))
  • What to keep: answer.record is the authorized XML, the voucher with tax validity. Store it: read(record) gives the voucher back and render prints it whenever it is needed.
  • Still processing: authorize gives None while the SRI has not answered yet; ask again later with the same access key.
  • Sent twice: reception.already_there is true when the SRI already holds that access key, so its answer waits at the authorization service.
  • Numbering: the establishment, the emission point and the sequential belong to the caller's system. A sequential is never reused, and a voucher sent again keeps its access key.
  • Signed documents: read_voucher(document) gives back the voucher a signed or unsigned document carries.
Amounts and codes
  • Lines: subtotal is the line before IVA (quantity times unit price minus discount) and vat its tax, both to two decimals. price_line(code, description, quantity, unit_price, rate_code, discount) works them out, rounding halves up. The voucher adds them up per rate.
  • IVA rate codes (rate_code): the SRI's table, for example "4" for 15 %, "0" for 0 %, "6" not subject to IVA, "7" exempt.
  • Payment forms (Payment.form): the SRI's table, for example "01" without the financial system (cash), "16" debit card, "19" credit card, "20" other with the financial system (transfer). Payments of the same form are added up.
  • Credit notes: modified=Modified(number, issued_on, reason) names the invoice they correct; credit notes carry no payments.
  • Final consumer: Buyer(BuyerKind.FINAL_CONSUMER). The voucher writes the SRI's own name and number for it.
When something fails
  • SriUnavailable: the SRI could not be reached or failed on its side. Nothing is lost: send the same document again later.
  • VoucherInvalid: the voucher breaks the SRI's schema (the message names every reason) or the record holds no voucher. Fix the data; sending it would only be returned.
  • CredentialRefused: the signature cannot sign. problem says why: missing, unreadable (wrong password or not a .p12) or out_of_date.
  • Turned down: answer.authorized is false and answer.messages carry the SRI's codes and texts, as it wrote them.

Taxpayer registry

from eqinvoice import SriRegistry

taxpayer = SriRegistry().find("1791234567001")
if taxpayer is not None and taxpayer.active:
    issuer = taxpayer.issuer(trade_name="Acme Shop")
  • Nobody holds it: find gives None. A registry that cannot be reached raises SriUnavailable.
  • The issuer: taxpayer.issuer() names the head office address the registry lists. A withholding agent or a special taxpayer passes its resolution or number (withholding_agent=, special_taxpayer=), which the registry does not publish.
  • A mark and a name: MarkLogo(mark=Path("mark.svg"), name=Path("name.svg"), font=Path("Brand.ttf")). The mark is an SVG of rectangles and straight paths; the name is an SVG <text> whose runs carry their colours (a <tspan> for a second colour), set in the font given. They sit as a lockup: for a mark 28 high the name is 17 and the gap 8, the proportion name_size and gap change, and the name's own glyphs (ascenders and descenders included) are centred on the mark.
  • A picture: ImageLogo(Path("logo.png")), drawn at the logo's height keeping its proportions. ImageLogo(path, one_ink_path=Path("logo-black.png")) gives the thermal strip its own black version.
  • No logo: leave logo out and the issuer's box takes the space.

On the A4 page the logo goes above the issuer's box, in colour. On the strip it goes on top, in one ink.

Labels

default_labels() holds the Spanish words the SRI prints. To change them, copy src/eqinvoice/labels/es.json, edit the values and pass labels=read_labels(Path("labels.json")) to render. The keys stay as they are.


Claude Code plugin

/plugin install eqinvoice --marketplace jahirxtrap/eqinvoice

Or add the marketplace once and install it from there:

claude plugin marketplace add jahirxtrap/eqinvoice
claude plugin install eqinvoice@eqinvoice

On enabling it, Claude Code asks for the book folder, the .p12 signature and its password; the password goes to the system's secure storage. The plugin starts the MCP server with uvx from PyPI (it needs uv): the first start installs it, later ones take a couple of seconds. Its tools show up as mcp__plugin_eqinvoice_eqinvoice__*.

MCP server

eqinvoice-mcp serves one issuer over stdio. It keeps everything in a folder, the book, and signs with the issuer's .p12. Without the plugin, register it by hand:

claude mcp add --scope user eqinvoice \
  -e EQINVOICE_BOOK=/path/to/book \
  -e EQINVOICE_P12=/path/to/signature.p12 \
  -e EQINVOICE_P12_PASSWORD=... \
  -- uvx --from "eqinvoice[mcp]" eqinvoice-mcp
  • Issuer: configure_issuer takes a RUC, the environment (test or production), the establishment and the emission point. The legal name, the address, the accounting duty, the RIMPE regime and the establishment's trade name come from the SRI's registry. A withholding agent or a special taxpayer adds its resolution number, which the registry does not publish, and the RUC of the invoicing system's provider can go on every voucher.
  • Clients: register_client keeps a buyer and its email. A RUC is named as the registry holds it; a cédula or a passport brings its name.
  • Drafts first: every voucher starts as a draft with the voucher it would become and a printed preview (a PDF). Nothing reaches the SRI until the draft is issued.
  • Issuing: issue_draft numbers the draft, signs it, sends it and files it as the SRI leaves it: authorized (with its record and its printed copy), refused (with the SRI's messages) or pending, which check_voucher asks for again.
  • Numbering: each environment, kind, establishment and point numbers its own series, and a number is taken for good once a voucher is signed with it.
Tools
Tool What it does
look_up_taxpayer A RUC as the SRI's registry holds it
configure_issuer Who issues, from which establishment and point, in which environment
show_issuer The issuer as it is configured
register_client, list_clients, forget_client The clients in the book
draft_invoice An invoice for a client, with its printed preview
draft_credit_note A credit note against an authorized invoice, whole or by lines
list_drafts, discard_draft The drafts waiting to be issued
issue_draft The approved draft numbered, signed and sent to the SRI
list_vouchers Every voucher numbered in the current environment
check_voucher A pending voucher sent again and asked for
The book
Path What it holds
profile.json The issuer, its establishment and point, and the environment
clients/<identification>.json One client each
drafts/<id>.json, drafts/<id>.pdf A draft and its printed preview
vouchers/<environment>/<kind>/<number>/ signed.xml, then authorized.xml and printed.pdf, or refused.json
brand/ The logo of the printed copies: mark.svg, name.svg and a .ttf, or logo.png. An optional lockup.json ({"name_size": 0.76}) sizes the name or the gap for this brand
Environment variables
Variable What it does
EQINVOICE_BOOK The folder the server keeps the book in
EQINVOICE_P12 The issuer's .p12 signature
EQINVOICE_P12_PASSWORD Its password

Development

python3.11 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/ruff check src tests scripts
.venv/bin/mypy
.venv/bin/pytest

Two scripts drive the live services:

EQINVOICE_P12=signature.p12 EQINVOICE_P12_PASSWORD=... \
  .venv/bin/python scripts/smoke_sri.py setup.json out
.venv/bin/python scripts/smoke_registry.py 1791234567001
  • smoke_sri.py: a real round trip against the SRI's test environment. It signs a $1.00 invoice to a final consumer, sends it, waits for the authorization, reads it back and prints both layouts. setup.json holds issuer (the Issuer fields), establishment, point and establishment_address; use an emission point no other system numbers with.
  • smoke_registry.py: a RUC looked up in the SRI's live registry, with its establishments and the issuer it would be.

A tag (1.2.0) publishes that version to PyPI and opens its release with CHANGELOG.md. The version lives in pyproject.toml and, the same, in the plugin's manifest, its marketplace entry and the package its .mcp.json launches; tests/test_plugin.py keeps them in agreement.

License

MIT, see LICENSE.

Metadata

Release files for eqinvoice 1.1.2

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

Source distribution (sdist)

Source distribution for eqinvoice 1.1.2
File Size Uploaded Provenance Actions
eqinvoice-1.1.2.tar.gz 62.4 kB Without provenance Details for eqinvoice-1.1.2.tar.gz

Built distribution (wheel)

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

Total release size: 118.8 kB

Release files / eqinvoice-1.1.2.tar.gz

Download URL eqinvoice-1.1.2.tar.gz
Size 62.4 kB
Tags Source
SHA-256 checksum
How to use checksums
fd7891f4eda988ce659da58fd2e05d61fbd38a421ee32a7f8dd3704c32d48494
BLAKE2b-256 checksum
How to use checksums
dc98eddc035c900752eac84b59eab4fcb6eb4bbf3337c20b9f21aa2d982f764b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / eqinvoice-1.1.2-py3-none-any.whl

Download URL eqinvoice-1.1.2-py3-none-any.whl
Size 56.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b12c42c27e74b6806416bcb03ee7fed904a3fac78e0fb33793b1adce939560de
BLAKE2b-256 checksum
How to use checksums
ef08275aca801cca0087d39ece4ed146fdbc46ace7b0e59d033c46e3db4d67c5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for eqinvoice 1.1.2

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.

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