Guía · España · Marca de deuda tributaria

Lista de morosos de Hacienda por API: consulta si una empresa figura en el listado de deudores de la AEAT

Q: ¿Cómo sé cómo se identificó a una empresa?

Cada marca trae identifier_source: direct_read si el identificador se leyó directamente de la fuente, name_corroborated si se reconstruyó y se contrastó con el nombre de la empresa, con name_match_score. Puede filtrar por él si solo quiere entradas leídas directamente.

Q: ¿Cubre personas físicas u otros países?

No. La marca tax_debt es solo de España y se sirve sobre fichas de empresa; las personas físicas del listado no se sirven. El listado es anual.

Q: ¿Cómo listo todas las empresas que llevan la marca?

Llame a GET /companies/search con country=ES y risk_flag_type=tax_debt (o has_risk_flag=true). No hace falta nombre. Pagine con next_cursor y lea cada marca con include=risk_flags sobre la empresa.

La Agencia Tributaria publica el listado de deudores con deudas superiores a 600.000 euros. La API lo cruza con las fichas de empresa por NIF y devuelve cada coincidencia como una marca de riesgo, con el importe, la fecha de referencia y el enlace a la fuente oficial. Es una foto a una fecha, no un saldo actual, y cada marca indica cómo se leyó su identificador.

Publicado el 30 de septiembre de 2026 · English version

Qué es el listado y qué sirve la API

La Agencia Tributaria (AEAT) publica, conforme al artículo 95 bis de la Ley General Tributaria, el listado de deudores a la Hacienda Pública con deudas superiores a 600.000 euros. Es lo que en el buscador se conoce como la «lista de morosos de Hacienda». Prometiam lo lee cuando se publica, cruza cada entrada con una ficha de empresa por NIF y sirve la coincidencia como una marca de riesgo tax_debt sobre esa empresa. Es solo de España y se actualiza una vez al año.

La marca se lee con include=risk_flags en la ficha de empresa. Para listar todas las empresas con marca se usa has_risk_flag o risk_flag_type=tax_debt en la búsqueda. Ambas llamadas se muestran más abajo.

Consultar si una empresa debe a Hacienda: qué responde la API y qué no

La API responde a una pregunta concreta: ¿figura esta empresa en el listado publicado? No responde a «¿cuánto debe hoy?». El listado recoge saldos a una fecha pasada, así que una coincidencia es lo que la AEAT publicó, no el estado actual de la deuda. Para la situación de hoy, lo habitual es pedir a la propia empresa su certificado de estar al corriente de las obligaciones tributarias.

Lea esto antes de fiarse de una coincidencia

Es un dato a una fecha, no un saldo actual. El listado recoge los saldos a 31 de diciembre del año anterior y se publica unos seis meses después. La marca indica lo que la AEAT publicó para una fecha de referencia, no lo que la empresa debe hoy.
La inclusión es recurrible. Una empresa puede impugnar su entrada, y su situación puede haber cambiado desde la fecha de referencia. Toda marca trae as_of, is_point_in_time: true y un source_url; verifique en la fuente antes de actuar.
Solo figuran deudas superiores a 600.000 euros. No es un registro de todas las deudas tributarias, así que la ausencia de marca nunca significa que la empresa no deba nada.
Los identificadores se leen por OCR. La fuente es un PDF escaneado. Cada identificador se valida con su dígito de control y se cruza por NIF exacto, nunca por nombre, a costa de la exhaustividad para proteger la precisión: algunas empresas del listado no llevan marca. El criterio es preferir una marca que falta a una marca equivocada.
Cada marca dice cómo se leyó. identifier_source es direct_read si el identificador se leyó directamente de la fuente y name_corroborated si se reconstruyó y se contrastó con el nombre de la empresa; en ese caso name_match_score trae la puntuación. Filtre por él si solo quiere entradas leídas directamente.
Solo empresas. Solo se sirven las entradas que corresponden a una ficha de empresa; las personas físicas del listado no.

Comprobar una empresa por NIF

Dos llamadas: la primera resuelve el NIF al id de la empresa; la segunda pide las marcas de esa empresa.

# 1. NIF -> id de la empresa
curl -H "Authorization: Bearer $PROMETIAM_API_KEY" \
  "https://api.prometiam.com/functions/v1/risk-api/companies/search?nif=$NIF&country=ES"

# 2. Las marcas de riesgo de esa empresa
curl -H "Authorization: Bearer $PROMETIAM_API_KEY" \
  "https://api.prometiam.com/functions/v1/risk-api/companies/$COMPANY_ID?country=ES&include=risk_flags"

Respuesta ilustrativa y recortada de una empresa ficticia. Los valores son inventados:

{
  "data": {
    "id": 123456,
    "nif": "B00000000",
    "company_name": "EJEMPLO, S.L.",
    "status": "active",
    "risk_flags": [
      {
        "flag_type": "tax_debt",
        "severity": "medium",
        "amount_eur": 1250000,
        "reference_date": "2025-12-31",
        "published_date": "2026-06-30",
        "source": "AEAT_95bis",
        "source_url": "<enlace a la publicación oficial de la AEAT>",
        "extraction": "ocr",
        "identifier_source": "direct_read",
        "name_match_score": null,
        "as_of": "2025-12-31",
        "is_point_in_time": true,
        "note": "Point-in-time snapshot from an official published list, not a live balance. Verify at source_url before acting on it."
      }
    ]
  }
}

Campo	Qué contiene
`flag_type`	`tax_debt` para este listado. En una empresa española el array también puede traer la entrada `registry_compliance`, así que elija la marca por tipo y no por posición.
`amount_eur`	El importe que publica el listado, en euros.
`reference_date`, `as_of`	La fecha a la que se refieren los saldos del listado. `as_of` la repite.
`published_date`	Cuándo se publicó el listado.
`source_url`	La fuente oficial, para que verifique en ella.
`identifier_source`, `name_match_score`	Cómo se leyó el identificador: `direct_read`, o `name_corroborated` con una puntuación de coincidencia de nombre.
`is_point_in_time`, `note`	Siempre `true`, y una advertencia en claro de que es una foto a una fecha.

Listar todas las empresas que llevan la marca

risk_flag_type=tax_debt funciona solo, sin nombre ni identificador. has_risk_flag=true devuelve las empresas con cualquier marca de riesgo publicada, que hoy es este listado, y es solo para España. Se pagina con pagination.next_cursor.

curl -H "Authorization: Bearer $PROMETIAM_API_KEY" \
  "https://api.prometiam.com/functions/v1/risk-api/companies/search?country=ES&risk_flag_type=tax_debt&limit=50"

La señal de que una empresa ha dejado de presentar sus cuentas (la hoja registral cerrada del BORME, por ejemplo) es otra marca, con otro significado; está explicada en inglés.

Úsela en código

const API = 'https://api.prometiam.com/functions/v1/risk-api'
const headers = { Authorization: 'Bearer ' + process.env.PROMETIAM_API_KEY }

// Marcas del listado de deudores de la AEAT para una empresa española, por NIF.
// [] significa sin marca: no es información, ni mucho menos un «limpio».
export async function marcasDeudaTributaria(nif) {
  const busqueda = await fetch(API + '/companies/search?country=ES&nif=' + encodeURIComponent(nif), { headers })
  if (!busqueda.ok) throw new Error('búsqueda fallida: ' + busqueda.status)
  const { data } = await busqueda.json()
  if (!data.length) return null                        // el NIF no está en el registro

  const res = await fetch(API + '/companies/' + data[0].id + '?country=ES&include=risk_flags', { headers })
  if (!res.ok) throw new Error('ficha fallida: ' + res.status)
  const empresa = (await res.json()).data
  return (empresa.risk_flags || [])
    .filter((f) => f.flag_type === 'tax_debt')
    .map((f) => ({
      importe_eur: f.amount_eur,
      a_fecha: f.as_of,                                // fecha de la foto, no hoy
      publicado: f.published_date,
      leido_directamente: f.identifier_source === 'direct_read',
      fuente: f.source_url,
    }))
}

import os
import requests

API = 'https://api.prometiam.com/functions/v1/risk-api'
HEAD = {'Authorization': 'Bearer ' + os.environ['PROMETIAM_API_KEY']}

def marcas_deuda_tributaria(nif, solo_lectura_directa=False):
    """Marcas del listado de deudores de la AEAT. None: el NIF no está en el registro."""
    busqueda = requests.get(API + '/companies/search', params={'country': 'ES', 'nif': nif},
                            headers=HEAD, timeout=30)
    busqueda.raise_for_status()
    filas = busqueda.json()['data']
    if not filas:
        return None

    ficha = requests.get(API + '/companies/' + str(filas[0]['id']),
                         params={'country': 'ES', 'include': 'risk_flags'}, headers=HEAD, timeout=30)
    ficha.raise_for_status()
    marcas = [f for f in ficha.json()['data'].get('risk_flags', []) if f['flag_type'] == 'tax_debt']
    if solo_lectura_directa:
        marcas = [f for f in marcas if f['identifier_source'] == 'direct_read']
    return marcas

Qué hacer con una coincidencia es una decisión de política interna. Un criterio razonable es enviar la empresa a revisión, guardar as_of y source_url junto con la decisión y pedir a la empresa su situación actual. La ausencia de marca no es información, no es un «limpio». Los parámetros están en las secciones de ficha de empresa y búsqueda de la documentación, y la búsqueda de NIF gratuita sirve para encontrar el NIF antes.

Qué no es

No es la situación actual de la empresa con la AEAT. Para eso, pida a la empresa su certificado de estar al corriente de las obligaciones tributarias. Esta API recoge un listado publicado.
No es una puntuación de crédito. No hay rating ni probabilidad de impago. La marca es un hecho con su procedencia.
No es una comprobación de insolvencia. Los avisos de insolvencia de empresas son un endpoint aparte, solo de empresas, en dieciséis mercados (FR, DE, GB, AT, CH, NO, FI, US, NL, DK, HR, SE, ES, LV, EE, SG). Los concursos de acreedores de España están incluidos; véase concursos de acreedores por API.
No sirve fuera de España. La marca tax_debt existe solo para España.

Encaja en un expediente KYB junto a la ficha de empresa, los administradores del BORME y, si los criba, las sanciones (beta). Véase la verificación KYB, la diligencia debida de proveedores y cómo verificar el NIF de una empresa en Python.

Precio

Gratis — prueba de 14 días. 500 créditos, 10 peticiones por minuto, sin cobro hasta que termine la prueba. Al suscribirse, la misma clave sigue funcionando. Después Starter a 9,99 €/mes (1.000 créditos), Professional a 29,99 €/mes (10.000 créditos) y Scale a 99,99 €/mes (50.000 créditos), mensual o anual. Comprobar una empresa son dos llamadas. Consulte los precios.

Preguntas frecuentes

¿Qué es la lista de morosos de Hacienda?
Es el listado de deudores a la Hacienda Pública que publica la Agencia Tributaria (AEAT) conforme al artículo 95 bis de la Ley General Tributaria, con deudas superiores a 600.000 euros. Prometiam lo cruza con las fichas de empresa por NIF y sirve cada coincidencia como una marca de riesgo tax_debt.

¿Puedo consultar por API si una empresa debe a Hacienda hoy?
No. La API responde si la empresa figura en el listado publicado, que recoge los saldos a 31 de diciembre del año anterior y se publica unos seis meses después. No es un saldo actual. Para la situación de hoy, pida a la empresa su certificado de estar al corriente de las obligaciones tributarias.

¿Que no haya marca significa que la empresa no debe nada?
No. Solo figuran deudas superiores a 600.000 euros, el listado es anual y el cruce es por NIF exacto sobre identificadores leídos de un PDF escaneado, a costa de la exhaustividad para proteger la precisión. Algunas empresas del listado no llevan marca. La ausencia de marca no es información.

¿Cómo sé cómo se identificó a una empresa?
Cada marca trae identifier_source: direct_read si el identificador se leyó directamente de la fuente, name_corroborated si se reconstruyó y se contrastó con el nombre de la empresa, con name_match_score. Puede filtrar por él si solo quiere entradas leídas directamente.

¿Cubre personas físicas u otros países?
No. La marca tax_debt es solo de España y se sirve sobre fichas de empresa; las personas físicas del listado no se sirven. El listado es anual.

¿Cómo listo todas las empresas que llevan la marca?
Llame a GET /companies/search con country=ES y risk_flag_type=tax_debt (o has_risk_flag=true). No hace falta nombre. Pagine con next_cursor y lea cada marca con include=risk_flags sobre la empresa.

Regístrate Leer la documentación