API v1

Documentació de l'API

Una crida retorna el valor fiscal d'un vehicle segons les taules del BOE i l'ITP que correspon pagar a qualsevol de les 17 comunitats de règim comú, amb l'Ordre aplicada citada a la mateixa resposta.

Base: https://valorvenal.dr-techsolutions.com/api/v1 · Totes les respostes són JSON UTF-8.

Autenticació

Envia la teva clau a la capçalera Authorization (o, si ho prefereixes, a X-Api-Key). Les claus comencen per vv_live_ i es mostren una sola vegada en emetre-les.

Authorization: Bearer vv_live_xxxxxxxxxxxxxxxxxxxxxxxx

Primera crida

curl "https://valorvenal.dr-techsolutions.com/api/v1/valuate\
?brand=SEAT&model=IBIZA%201.0%20Eco%20TSI%20S%26S%20FR%20DSG\
&first_registration_date=2016-06-15&ccaa=andalucia" \
  -H "Authorization: Bearer vv_live_..."

{
  "fiscalValue": {
    "basis": "exact_model",
    "baseFirstYearEur": 15400,
    "depreciation": { "completedYears": 10, "pct": 17,
                      "bracket": "Mas de 10 años hasta 11 años",
                      "method": "exact_dates" },
    "valueEur": 2618
  },
  "itp": {
    "ccaaName": "Andalucía", "method": "rate", "rate": 0.04,
    "taxableBaseEur": 2618, "itpEur": 104.72, "ruleId": "default"
  },
  "boe": { "order": "HAC/1501/2025", "reference": "BOE-A-2025-26357" }
}

GET /valuate

Valoració fiscal i ITP en una sola crida. També accepta POST amb cos JSON i els mateixos noms de camp.

Paràmetre	Tipus	Descripció
`brand`	string, requerit	Marca, p. ex. VOLKSWAGEN
`model`	string, requerit	Model. Si envies la cadena exacta de l'Annex I es valora aquella línia; si només envies «GOLF» es retorna la mitjana del model
`first_registration_date`	data	Recomanat. Data de 1a matriculació (AAAA-MM-DD o DD/MM/AAAA). Amb aquesta dada, year és opcional
`transfer_date`	data	Data de la meritació. Per defecte, avui
`year`	int	Any de matriculació (1980–2027). Requerit si no envies la data
`fuel`	string	gasolina · diesel · electrico · hibrido · phev · glp (s'accepten sinònims)
`version`	string	Acabat (GTI, AMG…): afegeix una passada de cerca de l'acabat
`ccaa`	string	Slug de comunitat (madrid, catalunya…) o all per a les 17
`price_eur`	number	Preu pactat: si supera el valor de taules, és la base imposable

GET /brands · GET /models?brand=

Catàleg per autocompletar: 174 marques i els prefixos de model de cadascuna.

GET /itp/rates?ccaa=

La taula de tipus i quotes de l'ITP per comunitat, amb la norma i la data de verificació de cada regla. Sense paràmetre retorna les 17.

GET /usage

Consum del mes en curs per a la clau que fa la crida.

La resposta

fiscalValue — el valor que aplica Hisenda. basis diu sobre què s'ha calculat: exact_model, version o model. depreciation retorna el tram de l'Annex IV, el percentatge i si prové de dates reals o és estimat.
itp — mètode (tipus o quota fixa), base imposable, import i la norma autonòmica citada.
summary — mín/mitjà/màx de les variants trobades, ja depreciades.
comparables — fins a 20 variants amb el seu valor.
actualYear i yearsDriftFromRequested — si no hi ha files per a l'any demanat, es fa servir el més proper disponible.
warnings i warningCodes — avisos no bloquejants, p. ex. que la depreciació és una estimació per any natural.
boe — Ordre i any dels valors aplicats: traçabilitat a cada resposta.

Exactitud del càlcul

Hisenda compta els anys d'utilització de data a data, des de la primera matriculació fins a la meritació, no per anys naturals. El mateix cotxe transmès al març o al setembre del mateix any pot caure en trams diferents de l'Annex IV. Per això first_registration_date és el paràmetre que més canvia el resultat.

Els nostres resultats estan verificats al cèntim contra el simulador oficial de l'Agència Tributària d'Andalusia. Els territoris forals (Navarra i País Basc) no estan suportats: apliquen les seves pròpies taules i retornem un 422 explícit en lloc d'un número incorrecte.

Errors

{ "error": { "code": "quota_exceeded", "message": "...", "docs": "..." } }

HTTP	code	Quan
400	`invalid_params`	Falten paràmetres o són invàlids
401	`unauthorized`	Clau absent o invàlida
402	`quota_exceeded`	Quota mensual del pla esgotada
404	`not_found`	Marca inexistent (a /models)
422	`region_not_supported`	Territori foral: fa servir les seves pròpies taules
429	`rate_limited`	Més de 5 peticions/segon sostingudes

Límits i atribució

5 peticions per segon sostingudes per clau. La quota mensual depèn del pla. El pla gratuït requereix un enllaç visible «Dades: ValorVenal» al costat dels resultats; els plans de pagament no requereixen atribució.

Veure plans i preus →