Guía de la API y el MCP de Licitaciones365

Introducción

Licitaciones365 ofrece dos puertas a los mismos datos y a la misma cuenta, con los permisos y los límites de tu plan:

La API está en https://api.licitaciones365.es/v1. Con ella puedes buscar licitaciones con los mismos filtros que el buscador de la app, ver su ficha por secciones y sus documentos; gestionar las favoritas y las descartadas del equipo, la nota, las tareas y los recordatorios de cada licitación y la agenda de plazos; crear, probar y ajustar alertas; consultar los contratos que vencen, los órganos de contratación, los adjudicatarios y estadísticas de mercado; y usar la IA de Licitaciones365 sobre cada licitación. La referencia recoge todas las operaciones.

Si buscas usar Licitaciones365 desde ChatGPT o Claude sin programar, tienes los pasos en ChatGPT y Claude.

Autenticación con API key

Cada petición lleva una API key en la cabecera Authorization:

Authorization: Bearer l365_tu_clave

Si tu herramienta solo te deja indicar el nombre de una cabecera (Copilot Studio, Power Automate…), envíala en X-API-Key: l365_tu_clave.

Crear una clave

1. Entra en la app y ve a Perfil → Integraciones (ir a Integraciones).
2. En API keys, crea una clave: ponle un nombre que te ayude a reconocerla (por ejemplo, «ERP de ofertas»), elige el equipo con el que trabajará (o todos tus equipos) y su permiso: solo lectura o lectura y escritura. Si quieres, ponle una caducidad (de 1 a 730 días).
3. Copia la clave: solo se muestra una vez. Empieza por l365_.

• Planes: las API keys están incluidas en los planes Pro y Enterprise de pago. No están en la prueba gratuita. Si el plan del equipo baja de Pro, sus claves dejan de funcionar (error plan_insuficiente) hasta que vuelva a subir.
• Las crea el propietario del equipo. Solo el propietario, que es quien paga el plan, crea, usa y revoca las API keys de su equipo. El resto del equipo las ve en la app y trabaja con su propio asistente. Hasta 5 claves activas por equipo.
• Un equipo o todos los tuyos. La clave trabaja con el equipo que elegiste, sin depender del que tengas abierto en la app. Si la creas para todos tus equipos, cada petición elige equipo con la cabecera X-Equipo: <id> (los ids salen en GET /cuenta). Sin ella, trabaja con el equipo con el que la creaste.
• Permisos: con una clave de solo lectura, cualquier petición que cambie datos responde solo_lectura. Empieza con solo lectura si no necesitas más.
• Revocación: revoca una clave desde la misma pantalla y deja de funcionar al momento. Cerrar todas las sesiones de tu cuenta, suspenderla o borrarla también revoca tus claves.
• Guárdala como una contraseña: en variables de entorno o en un gestor de secretos, nunca en el código ni en una web. La API no admite llamadas desde el navegador (no tiene CORS): llámala desde tu servidor. De la clave solo guardamos su huella (hash), así que no podemos recuperarla: si la pierdes, revócala y crea otra.

Primera petición

Guarda tu clave en la variable de entorno L365_API_KEY (la usan todos los ejemplos) y comprueba que funciona con GET /cuenta, que no consume cuota diaria:

curl https://api.licitaciones365.es/v1/cuenta \
  -H "Authorization: Bearer $L365_API_KEY"

{
  "data": {
    "usuario": { "id": 1234, "email": "ana@empresa.es", "nombre": "Ana García" },
    "equipo": { "id": 567, "nombre": "Licitaciones", "plan": "Pro", "rol": "owner" },
    "credencial": { "tipo": "api_key", "nombre": "ERP de ofertas", "escritura": false },
    "cuotas_api_hoy": {
      "busquedas_dia": { "limite": 1000, "usado": 37 },
      "fichas_dia": { "limite": 2000, "usado": 112 },
      …
    },
    "datos_actualizados": "2026-10-13T21:47:12+02:00",
    …
  }
}

La respuesta dice con qué usuario, equipo y plan trabaja la clave, si puede escribir y cuánto has usado hoy de cada cuota.

Servidor MCP

El servidor MCP permite a un asistente de IA buscar licitaciones y trabajar con los datos del equipo en nombre del usuario. Usa el transporte HTTP en streaming (Streamable HTTP) en:

https://api.licitaciones365.es/mcp

Autenticación con OAuth (ChatGPT, Claude y otros asistentes)

Es lo que usa el botón «Conectar» de los asistentes. El usuario no comparte su contraseña: inicia sesión en Licitaciones365, elige el equipo y si el asistente puede hacer cambios o solo consultar, y autoriza. Disponible en los planes Plus, Pro y Enterprise y en la prueba gratuita.

• OAuth 2.1 con código de autorización y PKCE (S256), con registro dinámico de clientes (RFC 7591) en /oauth/register.
• Descubrimiento en /.well-known/oauth-protected-resource y /.well-known/oauth-authorization-server. Una petición sin token recibe un 401 con la cabecera WWW-Authenticate que apunta a esos metadatos.
• Se aceptan las direcciones de vuelta de Claude (claude.ai, claude.com), ChatGPT (chatgpt.com, chat.openai.com) y las locales (localhost, 127.0.0.1), que usan clientes de escritorio y de terminal como Claude Code.
• Los tokens de acceso duran poco y el cliente los renueva solo. El usuario puede desconectar el asistente cuando quiera en Perfil → Integraciones.

Autenticación con API key

En clientes que permiten cabeceras propias, puedes conectar el MCP con una API key (planes Pro y Enterprise de pago). Por ejemplo, en Claude Code:

claude mcp add --transport http licitaciones365 https://api.licitaciones365.es/mcp \
  --header "Authorization: Bearer l365_..."

La clave trabaja con su equipo y su permiso, igual que en la API. Los pasos para conectar Claude y ChatGPT con OAuth están en ChatGPT y Claude.

Herramientas

Los nombres y las descripciones de las herramientas están en español, para que el asistente sepa cuándo usar cada una. Cada conexión ve solo las que su plan y su permiso permiten: con permiso de solo lectura no aparecen las que escriben. Lo marcado como «Pro y Enterprise» también está en la prueba gratuita.

Cada herramienta declara si solo consulta, si añade algo o si modifica o borra (las marcas readOnlyHint y destructiveHint del protocolo), y los asistentes se basan en ellas: lo que solo consulta lo ejecutan sin preguntar, para añadir piden permiso salvo que el usuario lo haya dejado permitido, y antes de modificar o borrar piden confirmación. El detalle depende de cómo tenga configurados los permisos cada asistente.

Atajos

El servidor ofrece también estos atajos (prompts del MCP), que el asistente muestra para lanzar una tarea completa con un clic:

• buscar_oportunidadesBuscar oportunidades para mi empresa. Licitaciones abiertas que encajan con tu actividad, tu zona y el importe que te interesa, con su plazo y por qué encajan.
• analizar_licitacionAnalizar una licitación. Alcance, importes, plazos, criterios, solvencia, riesgos y si encaja con tu empresa.
• preparar_ofertaPreparar la oferta de una licitación. Plan de trabajo para presentarse: documentación, tareas con fechas, responsables y recordatorios.
• novedadesNovedades y próximos plazos. Lo que ha llegado por tus alertas, los cambios en tus favoritas y los plazos y tareas que tienes por delante.

En el MCP, los errores (plan, permisos, límites, parámetros) llegan como resultado de la herramienta, con un mensaje en español para que el asistente se lo explique al usuario. Las llamadas del MCP cuentan en las mismas cuotas diarias del equipo que la API.

Límites y cuotas

Los límites dependen del plan del equipo. Los de por minuto cuentan por credencial (cada API key o cada asistente conectado); los diarios, por equipo, sumando todas sus credenciales, y se renuevan a medianoche (hora de Madrid).

• El plan Plus y la prueba gratuita usan estos límites a través del MCP: las API keys son de Pro y Enterprise de pago.
• Crear favoritas y alertas, probar alertas y consultar a la IA tienen además topes diarios propios. Todas las cuotas, con lo usado hoy, están en cuotas_api_hoy de GET /cuenta (en el MCP, la herramienta contexto_cuenta).
• Al pasarte de un límite recibes 429 limite_superado con la cabecera Retry-After en segundos.
• Búsquedas: hasta 100 resultados por página y los primeros 5.000 de cada búsqueda. Una búsqueda que tarda demasiado se corta con busqueda_demasiado_amplia: acótala con más filtros.
• Los intentos con credenciales no válidas se limitan por dirección IP.
• Son cifras de partida: pueden ajustarse durante la beta.

Respuestas y paginación

Todas las respuestas son JSON con los datos en data y, cuando hay información adicional (paginación, filtros aplicados…), en meta:

{
  "data": [ … ],
  "meta": {
    "paginacion": { "pagina": 1, "por_pagina": 25, "total": 312, "total_es_minimo": false, "hay_mas": true },
    "filtros": { … }
  }
}

• Las claves van en español y en minúsculas con guion bajo: importe_sin_iva.
• Los códigos llevan su nombre: {"codigo": "PUB", "nombre": "En plazo"}.
• Fechas con hora en ISO 8601 y hora de Madrid (2026-10-02T09:15:00+02:00); fechas sin hora como AAAA-MM-DD.
• Importes en euros y sin IVA, salvo los campos que acaban en _con_iva.
• Si no hay dato, el valor es null; en algunas secciones de la ficha, la clave sin dato no aparece.
• Los filtros de lista van separados por comas en la URL: estado=PUB,EV.
• Pagina con pagina y por_pagina; sigue pidiendo mientras meta.paginacion.hay_mas sea true.
• url_app abre la licitación en la app de Licitaciones365; url_origen, en el portal oficial.
• Tareas largas (IA): responden 202 con estado: "en_curso" y se recogen después con su GET. Con el parámetro esperar (hasta 25 segundos), la misma llamada espera a que terminen.
• Estabilidad: en /v1 podemos añadir recursos y campos nuevos, así que ignora los que no conozcas. Un cambio incompatible iría en una versión nueva de la API.

Errores

Los errores llevan el estado HTTP que corresponde y este cuerpo. Usa code en tu código: es estable. message está en español para mostrarlo a una persona y puede cambiar.

HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/json

{
  "error": {
    "code": "limite_superado",
    "message": "Demasiadas peticiones: con el plan Pro cada credencial puede hacer 120 consultas por minuto. Vuelve a intentarlo en 42 s."
  }
}

{
  "error": {
    "code": "parametros_invalidos",
    "message": "El campo por_pagina debe ser como máximo 100.",
    "details": {
      "por_pagina": ["El campo por_pagina debe ser como máximo 100."]
    }
  }
}

Si recibes un código que no está en la lista, trátalo según su estado HTTP.

Documentos: enlaces al portal oficial

Los pliegos, anexos y anuncios de cada licitación se devuelven como enlaces al portal oficial donde se publicaron (la Plataforma de Contratación del Sector Público o el portal autonómico), igual que en la app. Ni la API ni el MCP descargan, guardan ni sirven su contenido.

• Cada documento tiene un identificador compuesto (pliego_adm:…, pliego_tec:…, anexo:…, general:…, anuncio:…, modweb:…), su tipo, nombre, fecha y el dominio del portal (fuente).
• Si un documento se publicó varias veces, sale solo su última versión. Los que el órgano ha retirado llegan con retirado: true.
• Algunos portales detectan accesos automáticos o necesitan un navegador. Si tu programa o tu asistente no puede abrir un enlace, ábrelo tú en el navegador.

Privacidad

• Adjudicatarios que son personas físicas: salen como «Persona física», sin nombre ni NIF y con persona_fisica_protegida: true. Solo se muestran el nombre y el NIF de empresas identificadas con certeza; en caso de duda, se protegen. Lo mismo vale en el MCP: estos datos acaban en sistemas de terceros.
• Datos del equipo: una credencial solo ve los datos de su equipo (favoritas, notas, tareas, alertas). Nunca los de otros equipos.
• Sin sesiones ni dispositivos: las API keys y los asistentes conectados no ocupan plazas del límite de dispositivos ni aparecen como sesiones.
• Registro de cambios: guardamos qué cambios hace cada credencial (quién, con qué clave o asistente, qué acción y sobre qué).
• Más detalle en la política de privacidad.

Condiciones de uso de la API

Además de los términos y condiciones de Licitaciones365, al usar la API o el MCP aceptas estas condiciones:

• Ni reventa ni redistribución. Los datos que obtienes son para tu actividad y tus propias integraciones. No puedes revenderlos, cederlos ni redistribuirlos a terceros, por ejemplo publicándolos en otra web o servicio o montando con ellos una base de datos para otros.
• Atribución. Los datos proceden de información del sector público reutilizada conforme a la Ley 37/2007 (RISP). Cuando muestres información obtenida de la API, cita su origen: «Fuente: Plataforma de Contratación del Sector Público y plataformas autonómicas, vía Licitaciones365». La ficha de cada licitación lo trae en el campo fuente.

Ejemplos de código

Los casos más comunes, en curl, Python (con requests) y JavaScript (Node.js 18 o superior, con fetch). Al elegir un lenguaje, se elige en todos los ejemplos de la página.

curl -G "https://api.licitaciones365.es/v1/licitaciones" \
  --data-urlencode "cpv=77310000" \
  --data-urlencode "comunidad=ES52" \
  --data-urlencode "estado=PUB" \
  --data-urlencode "por_pagina=100" \
  --data-urlencode "pagina=1" \
  -H "Authorization: Bearer $L365_API_KEY"

import os

import requests

API = "https://api.licitaciones365.es/v1"
CABECERAS = {"Authorization": f"Bearer {os.environ['L365_API_KEY']}"}


def licitaciones_en_plazo(cpv, comunidad):
    """Devuelve una a una las licitaciones en plazo, página a página."""
    pagina = 1
    while True:
        respuesta = requests.get(
            f"{API}/licitaciones",
            params={
                "cpv": cpv,
                "comunidad": comunidad,
                "estado": "PUB",
                "por_pagina": 100,
                "pagina": pagina,
            },
            headers=CABECERAS,
            timeout=30,
        )
        cuerpo = respuesta.json()
        if not respuesta.ok:
            raise RuntimeError(f"{cuerpo['error']['code']}: {cuerpo['error']['message']}")
        yield from cuerpo["data"]
        if not cuerpo["meta"]["paginacion"]["hay_mas"]:
            return
        pagina += 1


for licitacion in licitaciones_en_plazo("77310000", "ES52"):
    plazo = licitacion["plazo_presentacion"] or {}
    print(licitacion["id"], licitacion["titulo"], licitacion["importe_sin_iva"], plazo.get("fecha"))

const API = "https://api.licitaciones365.es/v1";
const cabeceras = { Authorization: `Bearer ${process.env.L365_API_KEY}` };

async function* licitacionesEnPlazo(cpv, comunidad) {
  for (let pagina = 1; ; pagina++) {
    const params = new URLSearchParams({
      cpv,
      comunidad,
      estado: "PUB",
      por_pagina: "100",
      pagina: String(pagina),
    });
    const respuesta = await fetch(`${API}/licitaciones?${params}`, { headers: cabeceras });
    const cuerpo = await respuesta.json();
    if (!respuesta.ok) throw new Error(`${cuerpo.error.code}: ${cuerpo.error.message}`);
    yield* cuerpo.data;
    if (!cuerpo.meta.paginacion.hay_mas) return;
  }
}

for await (const licitacion of licitacionesEnPlazo("77310000", "ES52")) {
  console.log(licitacion.id, licitacion.titulo, licitacion.importe_sin_iva, licitacion.plazo_presentacion?.fecha);
}

curl -G "https://api.licitaciones365.es/v1/catalogos/cpv" \
  --data-urlencode "texto=limpieza de edificios" \
  -H "Authorization: Bearer $L365_API_KEY"

import os

import requests

respuesta = requests.get(
    "https://api.licitaciones365.es/v1/catalogos/cpv",
    params={"texto": "limpieza de edificios"},
    headers={"Authorization": f"Bearer {os.environ['L365_API_KEY']}"},
    timeout=30,
)
respuesta.raise_for_status()
for cpv in respuesta.json()["data"]:
    print(cpv["codigo"], cpv["descripcion"])

const params = new URLSearchParams({ texto: "limpieza de edificios" });
const respuesta = await fetch(`https://api.licitaciones365.es/v1/catalogos/cpv?${params}`, {
  headers: { Authorization: `Bearer ${process.env.L365_API_KEY}` },
});
const { data } = await respuesta.json();
for (const cpv of data) console.log(cpv.codigo, cpv.descripcion);

curl -G "https://api.licitaciones365.es/v1/licitaciones/4815162" \
  --data-urlencode "secciones=general,condiciones,documentos" \
  -H "Authorization: Bearer $L365_API_KEY"

import os

import requests

respuesta = requests.get(
    "https://api.licitaciones365.es/v1/licitaciones/4815162",
    params={"secciones": "general,condiciones,documentos"},
    headers={"Authorization": f"Bearer {os.environ['L365_API_KEY']}"},
    timeout=30,
)
respuesta.raise_for_status()
ficha = respuesta.json()["data"]

print(ficha["titulo"], "·", ficha["estado"]["nombre"])
for criterio in (ficha["condiciones"] or {}).get("criterios_adjudicacion", []):
    print("Criterio:", criterio.get("descripcion"), criterio.get("peso"))
for documento in ficha["documentos"]:
    if not documento["retirado"]:
        print(documento["tipo"], documento["url"])

const params = new URLSearchParams({ secciones: "general,condiciones,documentos" });
const respuesta = await fetch(`https://api.licitaciones365.es/v1/licitaciones/4815162?${params}`, {
  headers: { Authorization: `Bearer ${process.env.L365_API_KEY}` },
});
const { data: ficha } = await respuesta.json();

console.log(ficha.titulo, "·", ficha.estado.nombre);
for (const criterio of ficha.condiciones?.criterios_adjudicacion ?? []) {
  console.log("Criterio:", criterio.descripcion, criterio.peso);
}
for (const documento of ficha.documentos.filter((d) => !d.retirado)) {
  console.log(documento.tipo, documento.url);
}

# 1. La pregunta (espera hasta 20 s a la respuesta)
curl -X POST "https://api.licitaciones365.es/v1/licitaciones/4815162/ia/preguntas" \
  -H "Authorization: Bearer $L365_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pregunta": "¿Qué solvencia técnica piden y cómo se acredita?", "esperar": 20}'

# 2. Si responde 202 (estado "en_curso"), recoge la respuesta con su run_id
curl "https://api.licitaciones365.es/v1/ia/consultas/98231?esperar=20" \
  -H "Authorization: Bearer $L365_API_KEY"

import os

import requests

API = "https://api.licitaciones365.es/v1"
CABECERAS = {"Authorization": f"Bearer {os.environ['L365_API_KEY']}"}


def datos(respuesta):
    cuerpo = respuesta.json()
    if not respuesta.ok:
        raise RuntimeError(f"{cuerpo['error']['code']}: {cuerpo['error']['message']}")
    return cuerpo["data"]


consulta = datos(requests.post(
    f"{API}/licitaciones/4815162/ia/preguntas",
    json={"pregunta": "¿Qué solvencia técnica piden y cómo se acredita?", "esperar": 20},
    headers=CABECERAS,
    timeout=60,
))
while consulta["estado"] == "en_curso":
    consulta = datos(requests.get(
        f"{API}/ia/consultas/{consulta['run_id']}",
        params={"esperar": 20},
        headers=CABECERAS,
        timeout=60,
    ))

print(consulta.get("respuesta") or consulta.get("mensaje"))

const API = "https://api.licitaciones365.es/v1";
const cabeceras = {
  Authorization: `Bearer ${process.env.L365_API_KEY}`,
  "Content-Type": "application/json",
};

async function datos(peticion) {
  const respuesta = await peticion;
  const cuerpo = await respuesta.json();
  if (!respuesta.ok) throw new Error(`${cuerpo.error.code}: ${cuerpo.error.message}`);
  return cuerpo.data;
}

let consulta = await datos(
  fetch(`${API}/licitaciones/4815162/ia/preguntas`, {
    method: "POST",
    headers: cabeceras,
    body: JSON.stringify({ pregunta: "¿Qué solvencia técnica piden y cómo se acredita?", esperar: 20 }),
  }),
);
while (consulta.estado === "en_curso") {
  consulta = await datos(fetch(`${API}/ia/consultas/${consulta.run_id}?esperar=20`, { headers: cabeceras }));
}

console.log(consulta.respuesta ?? consulta.mensaje);

# -i muestra las cabeceras: ante un 429, mira Retry-After
curl -i "https://api.licitaciones365.es/v1/cuenta" \
  -H "Authorization: Bearer $L365_API_KEY"

import os
import time

import requests

CABECERAS = {"Authorization": f"Bearer {os.environ['L365_API_KEY']}"}


def get_con_reintentos(url, params=None, intentos=3):
    for _ in range(intentos):
        respuesta = requests.get(url, params=params, headers=CABECERAS, timeout=30)
        if respuesta.status_code != 429:
            return respuesta
        espera = int(respuesta.headers.get("Retry-After", "5"))
        if espera > 120:
            # Cuota diaria agotada: se renueva a medianoche (hora de Madrid).
            raise RuntimeError(respuesta.json()["error"]["message"])
        time.sleep(espera)
    return respuesta

const cabeceras = { Authorization: `Bearer ${process.env.L365_API_KEY}` };

async function getConReintentos(url, intentos = 3) {
  for (let intento = 0; intento < intentos; intento++) {
    const respuesta = await fetch(url, { headers: cabeceras });
    if (respuesta.status !== 429) return respuesta;
    const espera = Number(respuesta.headers.get("Retry-After") ?? 5);
    if (espera > 120) {
      // Cuota diaria agotada: se renueva a medianoche (hora de Madrid).
      throw new Error((await respuesta.json()).error.message);
    }
    await new Promise((resolver) => setTimeout(resolver, espera * 1000));
  }
  throw new Error("Demasiados reintentos");
}