Documentación de la API

Autenticación

Todas las rutas exigen un token. Se envía en la cabecera Authorization, tal cual, sin el prefijo Bearer. La URL base y el token se entregan al dar de alta el acceso; en los ejemplos aparecen como $BASE y $TOKEN.

curl "$BASE/api/auctions/SUB-JA-2026-000000" \
  -H "Authorization: $TOKEN" \
  -H "Accept: application/json"

Sin token, o con uno incorrecto, la respuesta es un 401. ¿Aún no tienes uno? Solicita acceso.

Convenciones

Identificadores

Cada subasta se identifica con el mismo código que usa el portal, por ejemplo SUB-JA-2026-266546. En la API ese valor es auction_number. El blog explica cómo se lee ese identificador.

Bloques de la ficha serializados

En el listado y en la ficha, los bloques general_information, managing_authorities, properties, lots, related y bids llegan como una cadena que contiene JSON. Hay que decodificarlos una segunda vez. La ruta de pujas y la de cambios devuelven objetos directamente.

const subasta = await respuesta.json();
const bienes = JSON.parse(subasta.properties ?? '[]');
const general = Object.assign({}, ...JSON.parse(subasta.general_information));
console.log(general['Valor subasta'], bienes[0]?.superficie);

Importes y fechas

Los importes se conservan como los publica el portal, en texto con formato español: "199.407,52 €". Las fechas de la ficha incluyen su equivalente ISO con huso horario: "19-10-2026 18:00:00 CET (ISO: 2026-10-19T18:00:00+02:00)". Ese valor ISO es la referencia exacta para la hora de cierre. El campo concludes_at expresa esa misma hora en horario peninsular español. Las marcas de tiempo del sistema (created_at, updated_at, bids_refreshed_at, changed_at) van en UTC.

Datos de terceros

La ficha reproduce lo que publica el portal, incluidos nombres de acreedores y direcciones de los bienes. Quien integre la API es responsable del uso que haga de esos datos.

Listado de subastas

GET/api/auctions

Devuelve todas las subastas registradas, paginadas de 500 en 500.

{
  "current_page": 1,
  "data": [ /* hasta 500 subastas, con la forma de la ficha */ ],
  "per_page": 500,
  "total": 15422,
  "last_page": 31,
  "next_page_url": "…/api/auctions?page=2",
  "prev_page_url": null
}

Ficha de una subasta

GET/api/auctions/{auction_number}

La provincia y la localidad se leen de cada bien, dentro de properties[].property; el campo province_id de la raíz está reservado y no debe usarse para filtrar.

Si el identificador no existe, la respuesta es un 404.

Estado de las pujas

GET/api/auctions/{auction_number}/bids

La ruta más ligera para seguir una subasta abierta. En las subastas en curso el estado se comprueba aproximadamente cada hora.

{
  "auction_number": "SUB-JA-2026-000000",
  "bids": {
    "tipo": "oculta",
    "importe": null,
    "mensaje": "La subasta ha recibido alguna puja. Para ver su importe debe acceder como usuario registrado.",
    "lotes": []
  },
  "bids_refreshed_at": "2026-09-30T12:56:03.000000Z"
}

Valores de bids.tipo

Mientras la subasta está abierta, el portal no publica importes: lo habitual es pasar de sin_pujas a oculta y, al concluir, a puja_maxima_final con el importe; el blog lo explica con un caso en primeros pasos con la API. En las subastas por lotes, lotes es una lista de objetos { lote, importe } donde importe es el texto que muestra el portal para ese lote.

Histórico de cambios

GET/api/changes

Cada vez que el sistema refresca una subasta abierta compara los valores con los anteriores y anota las diferencias. Esta ruta las devuelve, de la más reciente a la más antigua salvo que se indique otro orden.

Campos con histórico

fecha_conclusion, puja_minima, tramos_entre_pujas, valor_subasta, tasacion, importe_deposito, bids.tipo, bids.importe y, en subastas por lotes, bids.lote.N, donde N es el número de lote.

{
  "count": 2,
  "changes": [
    {
      "id": 2791,
      "auction_number": "SUB-JA-2026-000000",
      "field": "bids.tipo",
      "old_value": "sin_pujas",
      "new_value": "oculta",
      "changed_at": "2026-09-30T13:42:03.000000Z"
    },
    {
      "id": 2764,
      "auction_number": "SUB-AT-2026-00R0000000000",
      "field": "fecha_conclusion",
      "old_value": "30-09-2026 18:00:00 CET (ISO: 2026-09-30T18:00:00+02:00)",
      "new_value": "30-09-2026 18:53:12 CET (ISO: 2026-09-30T18:53:12+02:00)",
      "changed_at": "2026-09-30T16:20:04.000000Z"
    }
  ],
  "has_more": true,
  "before_id_next": 2764
}

Paginación

Cuando has_more es true, repite la petición añadiendo before_id con el valor de before_id_next. El cursor está pensado para el orden descendente.

Valores nulos

Un new_value nulo indica que el dato ha dejado de aparecer en la ficha. Ocurre, por ejemplo, con la fecha de conclusión cuando la autoridad gestora cancela la subasta. Sobre los cambios de hora de cierre, véase por qué se prorroga una subasta.

Errores

En un 400, details indica qué parámetro falla y por qué: un limit mayor de 500, una fecha ilegible o un campo que no tiene histórico.