Documentación de la API

Introducción

La API de PriceVault es REST sobre HTTPS, con peticiones y respuestas en JSON. Todos los endpoints programáticos viven bajo el prefijo /v1. Esta página documenta los endpoints destacados; para la referencia exhaustiva de todos los endpoints y esquemas dispones de la especificación OpenAPI:

• Swagger UI — interactivo, prueba endpoints desde el navegador.
• ReDoc — referencia completa, limpia y legible.

Autenticación

Cada petición se autentica con tu API key en la cabecera X-API-Key. Genera y gestiona tus claves desde el dashboard. Trátalas como un secreto: nunca las publiques en el frontend ni en repositorios.

curl "https://pricevault.es/v1/offers" \
  -H "X-API-Key: TU_API_KEY"

• API key inválida o inactiva → 401 Unauthorized.
• Cuenta desactivada → 403 Forbidden.

Scopes

Cada API key puede limitarse a un conjunto de scopes (permisos). Si llamas a un endpoint sin el scope requerido, la respuesta es 403 con el scope que falta.

Claves vinculadas a una asesoría

Una API key puede estar vinculada a una sola asesoría. Cuando lo está, el parámetro client_id de las consultas se fuerza a esa asesoría; pasar otro distinto devuelve 403. Es el detalle que más confusión genera al integrar.

Convenciones

Paginación

Los listados aceptan limit (1–200, por defecto 50) y offset. La respuesta envuelve los datos: { "total", "limit", "offset", "results": [...] }.

Estado de los registros

Por defecto solo se devuelven registros activos; usa include_inactive=true para incluir los desactivados. El borrado (DELETE) sobre ofertas, asesorías y comercializadoras es lógico (is_active = false), no físico.

Códigos de error

Límites de uso

Rate limit de uso razonable (anti-abuso), no una cuota: las llamadas no se facturan. Escala con el plan en dos niveles — un techo por cuenta y, para las keys atadas a una asesoría concreta (client_id), un sub-límite por cliente. Con una key de cuenta (sin client_id) solo aplica el techo. Al superarlo, la API responde 429.

Servidor MCP

Además de REST, PriceVault expone un servidor MCP (Model Context Protocol) para que un agente de IA use la API como herramienta nativa, sin que escribas la integración. Es la misma API /v1 de esta página: cada herramienta re-entra por el mismo control de autenticación, scopes y límites de uso.

• Transporte Streamable HTTP; autenticación con la cabecera X-API-Key, igual que en REST.
• Solo lectura. Solo se exponen endpoints de consulta y cálculo, y la key dedicada de MCP lleva exactamente offers:read, commissions:read y catalog:read.
• Incluido en todos los planes: las llamadas no se facturan y comparten el rate limit de la sección anterior.

Guía completa del servidor MCP — herramientas disponibles y cómo configurar Claude, n8n u otro cliente.

Listar tarifas

curl "https://pricevault.es/v1/offers?supply_type=LUZ&tariff_type=2.0TD&territory=peninsula&limit=20" \
  -H "X-API-Key: $PV_KEY"

{
  "total": 134,
  "limit": 20,
  "offset": 0,
  "results": [
    {
      "id": 412,
      "offer_name": "Tarifa Hogar 2.0TD",
      "supply_type": "LUZ",
      "tariff_type": "2.0TD",
      "is_indexed": false,
      "company": {
        "id": 12, "name": "Energía X", "logo_url": "https://...",
        "client": { "id": 3, "name": "Asesoría Norte", "image_url": null }
      },
      "e1": 0.142, "e2": 0.108, "e3": 0.085,
      "p1": 0.084, "p2": 0.012,
      "commission": 25.0, "commission_type": "fixed",
      "acepta_dni": true, "acepta_cif": true, "acepta_cdad_propietarios": true,
      "is_active": true,
      "created_at": "2026-04-02T10:11:00Z",
      "updated_at": "2026-05-30T08:00:00Z"
    }
  ]
}

Oferta más eficiente

curl -X POST "https://pricevault.es/v1/offers/efficient" \
  -H "X-API-Key: $PV_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "supply_type": "LUZ",
    "energia": { "e1": 1200, "e2": 800, "e3": 600 },
    "potencia": { "p1": 4.6, "p2": 4.6 },
    "fee_energia": 5,
    "fee_potencia": 3,
    "w": 0.5,
    "tariff_type": "2.0TD",
    "limit": 10
  }'

curl -X POST "https://pricevault.es/v1/offers/efficient" \
  -H "X-API-Key: $PV_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "supply_type": "GAS",
    "consumo_gas": 12000,
    "impuesto_hidrocarburos": 0.00234,
    "fee_energia": 3,
    "w": 0.5,
    "tariff_type": "RL.1",
    "limit": 10
  }'

{
  "w": 0.5,
  "total": 48,
  "excluded_count": 3,
  "mas_barata_id": 412,
  "mas_comision_id": 533,
  "mas_eficiente_id": 488,
  "results": [
    {
      "offer": {
        "id": 488, "offer_name": "Tarifa Óptima",
        "company": { "id": 12, "name": "Energía X", "logo_url": "..." }
      },
      "cost": { "energia": 312.4, "impuesto": 0.0, "potencia": 145.0, "fijo": 0.0, "excedentes": 0.0, "servicios": 0.0, "total": 457.4 },
      "commission": { "energia": 18.0, "potencia": 6.0, "total": 24.0 },
      "nota": 8.7, "nota_precio": 9.1, "nota_comision": 8.3,
      "is_optimal": true
    }
  ]
}

Recomendar por consumo y potencia

curl "https://pricevault.es/v1/offers/recommend?consumption_mwh=10&power_kw=4.6&supply_type=LUZ&tariff_type=2.0TD&limit=10" \
  -H "X-API-Key: $PV_KEY"

Comparar ofertas

curl "https://pricevault.es/v1/offers/compare?ids=412&ids=488&ids=533" \
  -H "X-API-Key: $PV_KEY"

Calcular comisión de una oferta

curl "https://pricevault.es/v1/offers/412/commission-calculator?consumption_mwh=10&power_kw=4.6" \
  -H "X-API-Key: $PV_KEY"

{
  "offer_id": 412,
  "consumption_mwh": 10,
  "power_kw": 4.6,
  "consumption_commission": {
    "value": 25.0, "commission_type": "fixed", "matched_tier": null
  },
  "power_commission": {
    "value": 6.0, "commission_type": "fixed",
    "matched_tier": { "power_from": 0, "power_to": 10 }
  }
}

Detalle de una oferta

curl "https://pricevault.es/v1/offers/412" \
  -H "X-API-Key: $PV_KEY"

Crear y editar ofertas

Operaciones de escritura sobre una oferta individual. El borrado es lógico: la oferta queda inactiva, no se elimina.

curl -X POST "https://pricevault.es/v1/offers" \
  -H "X-API-Key: $PV_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": 12,
    "offer_name": "Tarifa Hogar 2.0TD",
    "supply_type": "LUZ",
    "tariff_type": "2.0TD",
    "territory_peninsula": true,
    "e1": 0.142, "e2": 0.108, "e3": 0.085,
    "p1": 0.084, "p2": 0.012,
    "commission": 25, "commission_type": "fixed",
    "acepta_dni": true, "acepta_cif": true, "acepta_cdad_propietarios": true,
    "commission_tiers": [
      { "consumption_from": 0,  "consumption_to": 10, "commission": 3, "commission_type": "fixed" },
      { "consumption_from": 10, "consumption_to": 50, "commission": 5, "commission_type": "fixed" }
    ]
  }'

Carga y edición masiva

Dos formas de actualizar muchas ofertas a la vez. Ambas son todo-o-nada: si una fila falla, no se aplica ningún cambio.

Edición masiva por JSON

curl -X POST "https://pricevault.es/v1/offers/bulk-patch" \
  -H "X-API-Key: $PV_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "offer_ids": [412, 488, 533],
    "updates": { "is_active": false, "commission": 30 }
  }'

Carga por archivo XLSX

curl -X POST "https://pricevault.es/v1/offers/bulk-update" \
  -H "X-API-Key: $PV_KEY" \
  -F "file=@tarifas.xlsx"

¿Necesitas la plantilla? Descárgala (precargada con tus ofertas) desde GET /v1/offers/bulk-template y /bulk-template-indexed (parámetro client_id).

Precios indexados

Histórico mensual de precios de las ofertas indexadas (is_indexed: true). El upsert crea o reemplaza el mes indicado en reference_month (formato YYYY-MM-DD).

curl -X POST "https://pricevault.es/v1/offers/488/indexed-prices" \
  -H "X-API-Key: $PV_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_month": "2026-06-01",
    "e1": 0.154, "e2": 0.143, "e3": 0.121,
    "p1": 0.079, "p2": 0.065
  }'

Comercializadoras

Las comercializadoras pertenecen a una asesoría (client_id). La lectura requiere el scope companies:read; la escritura, companies:write.

curl -X POST "https://pricevault.es/v1/companies" \
  -H "X-API-Key: $PV_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "client_id": 3, "name": "Energía X", "logo_url": null }'

Asesorías (clientes)

Las asesorías son el primer nivel de tu organización: agrupan comercializadoras y ofertas. La lectura requiere el scope clients:read; la escritura, clients:write.

Estadísticas y exportación

curl "https://pricevault.es/v1/offers/stats" \
  -H "X-API-Key: $PV_KEY"

Catálogo compartido

El catálogo central de ofertas y empresas reutilizables al que se suscriben tus asesorías. Aquí cubrimos la lectura; la escritura (scope catalog:write, límite 120/min por key) está en la referencia completa.

curl "https://pricevault.es/v1/catalog/offers?supply_type=LUZ&client_type=cif" \
  -H "X-API-Key: $PV_KEY"

Cuenta

Datos de la organización propietaria de la API key. Estos endpoints funcionan con cualquier API key válida (sin scope específico).

curl "https://pricevault.es/v1/account" \
  -H "X-API-Key: $PV_KEY"

{
  "id": 3,
  "name": "Asesoría Norte",
  "email": "info@asesorianorte.es",
  "is_active": true,
  "created_at": "2026-01-15T09:00:00Z"
}

Cambiar la contraseña

curl -X POST "https://pricevault.es/v1/account/password" \
  -H "X-API-Key: $PV_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "••••••••",
    "new_password": "••••••••"
  }'

Respuesta 204 No Content si el cambio es correcto; 401 si la contraseña actual no coincide.

Suscripción

El plan actual de la cuenta y sus límites. Devuelve 404 si la cuenta no tiene suscripción activa.

{
  "id": 7,
  "plan": "pro",
  "status": "active",
  "clients_limit": 25,
  "trial_ends_at": null,
  "current_period_end": "2026-07-15T00:00:00Z",
  "created_at": "2026-01-15T09:00:00Z"
}

Uso de la API

Telemetría de tus llamadas: registro detallado y resumen agregado. Útil para depurar integraciones y vigilar el consumo.

curl "https://pricevault.es/v1/usage/summary" \
  -H "X-API-Key: $PV_KEY"

{
  "total_calls": 18432,
  "calls_by_endpoint": [
    { "endpoint": "GET /v1/offers", "calls": 12045 },
    { "endpoint": "POST /v1/offers/efficient", "calls": 3210 }
  ],
  "p95_response_time_ms": 86
}

Cargas

Seguimiento de las cargas de archivos. Tanto las subidas desde el dashboard como las cargas masivas por API (bulk-update) quedan registradas aquí.

curl "https://pricevault.es/v1/uploads?status=completed&limit=20" \
  -H "X-API-Key: $PV_KEY"