dgt-petete 0.2.0

Cliente y CLI de la API interna del buscador PETETE de la DGT (consultas vinculantes de Tributos)

dgt-petete

Client and CLI for PETETE, the binding-rulings search engine of the Spanish tax authority (DGT). Docs are in Spanish, as is the subject matter.

Cliente + CLI para el buscador PETETE de la Dirección General de Tributos (petete.tributos.hacienda.gob.es), que publica las consultas vinculantes del sistema tributario español. Busca y descarga el texto oficial de las consultas (p. ej. las del Art. 36 / 39.7 LIS que fundamentan la deducibilidad de gastos en incentivos fiscales culturales).

PETETE no expone una API pública; este paquete replica los tres endpoints internos de su buscador por HTTP, así que no hace falta navegador ni servidor.

Instalación

Nada que instalar si usas uv: ejecútalo al vuelo desde este repo.

uvx --from git+https://github.com/hulahoop-media/dgt-petete dgt-petete search \
  --normativa "Ley 27/2014" --freetext "producciones cinematográficas"

O instálalo como paquete:

pip install git+https://github.com/hulahoop-media/dgt-petete
# después:
dgt-petete download V2144-18 V0189-20 --out ./corpus

Uso: CLI

# Buscar (combina campos; devuelve una línea "Nº<TAB>docid" por consulta)
dgt-petete search --normativa "Ley 27/2014" --freetext "artes escénicas y musicales"

# Descargar el texto verbatim de una o más consultas a .txt
dgt-petete download V2144-18 V0189-20 --out ./corpus

Flags de search: --freetext, --normativa, --cuestion, --hechos, --num, --tab (1=generales, 2=vinculantes, por defecto 2).

Uso: librería

from dgt_petete import search, download

hits = search(normativa="Ley 27/2014", freetext="producciones cinematográficas")
# -> [("V0006-17", "54874"), ("V0018-17", "54885"), ...]

texto = download("V2144-18")   # texto oficial completo de la consulta

Plugin de Claude Code

El repo es también un marketplace de plugins de Claude Code. Instala el plugin y tu Claude podrá buscar y descargar consultas DGT a demanda (sin MCP):

/plugin marketplace add hulahoop-media/dgt-petete
/plugin install dgt-petete@dgt-petete

El plugin (plugins/dgt-petete/) empaqueta un skill que envuelve esta CLI y la ejecuta vía uvx desde este mismo repo, sin que haga falta clonar nada.

Cómo funciona (API interna, ingeniería inversa)

El buscador de PETETE (Knosys) llama a tres endpoints:

Endpoint	Qué hace
GET /consultas/do/form	Establece la sesión (cookie)
POST /consultas/do/search	Busca. Devuelve HTML con viewDocument(<docid>, <tab>) y updateNumResults("2","<total>")
POST /consultas/do/document	Texto completo de una consulta (requiere el docid)

Detalles no obvios (sin ellos no funciona):

• /do/document responde 401 sin cabeceras de AJAX (X-Requested-With: XMLHttpRequest + Referer).
• El operador entre campos es OPCMP_n=.Y (con punto inicial), no Y.
• Los valores van doble-codificados: el JS hace encodeURI sobre un string ya serializado, así que hay que quote_plus(v) y luego escapar los %. Sin esto, combinar dos campos devuelve HTTP 400.
• tab: 1 = consultas generales, 2 = consultas vinculantes.
• El servidor no envía el certificado intermedio de su cadena TLS (FNMT-RCM), así que curl y requests no lo validan de serie. El paquete incluye la cadena pública de la FNMT (dgt_petete/fnmt-chain.pem) y verifica contra ella por defecto; se puede sobrescribir con new_session(verify=...).

Desarrollo

git clone https://github.com/hulahoop-media/dgt-petete
cd dgt-petete
uv sync            # instala el paquete + dependencias de desarrollo
uv run pytest      # tests
uv run ruff check .

Ver CONTRIBUTING.md para la convención de commits y cómo proponer cambios.

Aviso

Herramienta no oficial que consulta datos públicos de la sede electrónica de la Agencia Tributaria. Úsala con moderación (las descargas ya espacian las peticiones). No afiliada a la AEAT ni a la DGT.

Licencia

MIT. Ver LICENSE.

---

Hecho por Hulahoop Media 🎪