Consulta de Adeudo — API Predial

ConsultaAdeudo

Devuelve los conceptos de adeudo del Impuesto Predial para el predio indicado, con base en los importes precalculados vigentes. Busca en una ventana de 5 años (el año en curso y los 4 anteriores) y devuelve un arreglo con un elemento por cada año dentro de esa ventana que tenga adeudo pendiente — los años sin adeudo simplemente no aparecen.

POST /api/predial/consulta-adeudo

Autenticación

requerido Authorization: Bearer <token> — obtenido en Login.

Cuerpo de la petición

{
  "id_mpio": 10,
  "id_tipo_predio": 1,
  "id_no_cuenta": "000123456"
}

Campo	Tipo	Descripción
`id_mpio`	int	requerido Clave del municipio
`id_tipo_predio`	int	requerido `1`=Urbano, `2`=Rústico, `3`=Suburbano
`id_no_cuenta`	string	requerido Número de cuenta catastral

Respuesta exitosa

fecha_vigencia y base_gravable de cada periodo se llenan a nivel periodo solo si es Anual; si es Bimestral se omiten ahí y cada elemento de adeudos trae las suyas (ver ejemplo Bimestral más abajo).

{
  "estatus_ejecucion": 1,
  "mensaje_ciudadano": "",
  "mensaje_tecnico": "",
  "total_general": 7920.00,
  "periodos": [
    {
      "periodo": 2023,
      "fecha_vigencia": "2023-04-30",
      "base_gravable": 450000.00,
      "superficie_terreno": 250.00,
      "superficie_construccion": 180.00,
      "total": 4320.00,
      "adeudos": [
        { "clase_pago": 1, "bimestre": 0, "concepto": 1, "nombre_concepto": "Impuesto", "importe": 3600.00, "concepto_espejo": 0 },
        { "clase_pago": 1, "bimestre": 0, "concepto": 3, "nombre_concepto": "Recargos", "importe": 720.00, "concepto_espejo": 0 }
      ]
    },
    {
      "periodo": 2026,
      "fecha_vigencia": "2026-04-30",
      "base_gravable": 450000.00,
      "superficie_terreno": 250.00,
      "superficie_construccion": 180.00,
      "total": 3600.00,
      "adeudos": [
        { "clase_pago": 1, "bimestre": 0, "concepto": 1, "nombre_concepto": "Impuesto", "importe": 3600.00, "concepto_espejo": 0 }
      ]
    }
  ]
}

Campo	Tipo	Descripción
`total_general`	float	Suma de `total` de todos los elementos de `periodos`
`periodo`	int	Año del periodo con adeudo
`fecha_vigencia`	string	Fecha límite de vigencia de ese periodo (`YYYY-MM-DD`), solo si es Anual; en Bimestral se omite y va por concepto dentro de `adeudos`
`base_gravable`	float	Base de cálculo del impuesto de ese periodo, solo si es Anual; en Bimestral se omite y va por concepto dentro de `adeudos`
`superficie_terreno`	float	Superficie de terreno del predio
`superficie_construccion`	float	Superficie de construcción del predio
`total`	float	Suma de `importe` de todos los elementos de `adeudos` de ese periodo
`adeudos`	array	Ver tabla de conceptos abajo, incluyendo `nombre_concepto`

Estructura de cada concepto

Campo	Tipo	Descripción
`clase_pago`	int	`1`=Anual, `2`=Bimestral
`bimestre`	int	`0`=anual, `1`–`6`=bimestre correspondiente
`concepto`	int	Ver tabla de conceptos abajo
`nombre_concepto`	string	Nombre legible del `concepto` (ver tabla de conceptos abajo)
`importe`	float	Importe del concepto (negativo para descuentos)
`fecha_vigencia`	string	Fecha límite de vigencia de este concepto (`YYYY-MM-DD`), solo presente cuando `clase_pago`=2 (Bimestral); en Anual se omite aquí y va en la raíz de la respuesta.
`base_gravable`	float	Base gravable de este concepto/bimestre, solo presente cuando `clase_pago`=2 (Bimestral); en Anual se omite aquí y va en la raíz.
`concepto_espejo`	int	Concepto al que aplica la reducción (ej. `1` para Impuesto); `0` si no aplica

¿Por qué cambia dónde viven fecha_vigencia y base_gravable? Un predio Anual tiene un único vencimiento (30 de abril) y una única base gravable, así que un solo valor en la raíz basta. Un predio Bimestral puede traer varios bimestres pendientes en la misma consulta, cada uno con su propio vencimiento (fin del primer mes del bimestre) y potencialmente su propia base — por eso ahí ambos campos van por elemento de adeudos y se omiten en la raíz. Esto respeta el contrato SPFA (PREDIAL.pdf p.2): fecha_vigencia es obligatorio por concepto y el consumidor "tomará la mínima fecha de vigencia" entre todos los renglones.

Ejemplo — predio Bimestral (dos bimestres pendientes)

{
  "estatus_ejecucion": 1,
  "mensaje_ciudadano": "",
  "mensaje_tecnico": "",
  "adeudos": [
    {
      "clase_pago": 2,
      "bimestre": 3,
      "concepto": 1,
      "nombre_concepto": "Impuesto",
      "importe": 600.00,
      "fecha_vigencia": "2026-05-31",
      "base_gravable": 120000.00,
      "concepto_espejo": 0
    },
    {
      "clase_pago": 2,
      "bimestre": 4,
      "concepto": 1,
      "nombre_concepto": "Impuesto",
      "importe": 600.00,
      "fecha_vigencia": "2026-07-31",
      "base_gravable": 120000.00,
      "concepto_espejo": 0
    }
  ]
}

Tabla de conceptos

`concepto`	`nombre_concepto`
`1`	Impuesto
`2`	Actualizaciones
`3`	Recargos
`4`	Reducción 50 %

Importes precalculados Los importes reflejan los valores vigentes capturados en el sistema catastral. El campo concepto: 4 (Reducción 50 %) se incluye cuando el predio tiene derecho a descuento; su importe es negativo e indica el concepto al que aplica mediante concepto_espejo.

Respuesta sin adeudos en la ventana de 5 años

Si la cuenta no existe en el catastro, mensaje_ciudadano lo indica explícitamente:

{
  "estatus_ejecucion": 0,
  "mensaje_ciudadano": "La cuenta predial ingresada no fue encontrada. Favor de verificar la información e intentar nuevamente.",
  "mensaje_tecnico": "No se han encontrado registros para la cuenta 12345 y el tipo_predio 1, corrobore la información.",
  "total_general": 0,
  "periodos": []
}

Si la cuenta sí existe pero no tiene adeudo pendiente en ninguno de los últimos 5 años:

{
  "estatus_ejecucion": 0,
  "mensaje_ciudadano": "Sin adeudos pendientes.",
  "mensaje_tecnico": "sin registros pendientes para tipo=1 cuenta=12345 entre 2022 y 2026",
  "total_general": 0,
  "periodos": []
}

ConsultaAdeudoAnterior

Devuelve los adeudos de años anteriores al actual (rezago histórico), sin ventana ni piso: siempre trae todo lo pendiente con periodo anterior al año en curso.

POST /api/predial/consulta-adeudo-anterior

Autenticación

requerido Authorization: Bearer <token> — obtenido en Login.

Cuerpo de la petición

Mismo cuerpo que ConsultaAdeudo: id_mpio, id_tipo_predio, id_no_cuenta.

Respuesta exitosa

fecha_vigencia y base_gravable siguen la misma regla que en ConsultaAdeudo: se llenan a nivel ejercicio solo si es Anual; si es Bimestral se omiten ahí y cada elemento de adeudos trae las suyas (ver ejemplo Bimestral de ConsultaAdeudo arriba).

{
  "estatus_ejecucion": 1,
  "mensaje_ciudadano": "",
  "mensaje_tecnico": "",
  "ejercicios": [
    {
      "periodo": 2023,
      "fecha_vigencia": "2023-04-30",
      "base_gravable": 450000.00,
      "adeudos": [
        { "clase_pago": 1, "bimestre": 0, "concepto": 1, "importe": 3600.00, "concepto_espejo": 0 },
        { "clase_pago": 1, "bimestre": 0, "concepto": 3, "importe": 720.00, "concepto_espejo": 0 }
      ]
    },
    {
      "periodo": 2024,
      "fecha_vigencia": "2024-04-30",
      "base_gravable": 450000.00,
      "adeudos": [
        { "clase_pago": 1, "bimestre": 0, "concepto": 1, "importe": 3600.00, "concepto_espejo": 0 }
      ]
    }
  ]
}

Campo	Tipo	Descripción
`periodo`	int	Año del ejercicio de rezago
`fecha_vigencia`	string	Fecha límite de vigencia de ese ejercicio (`YYYY-MM-DD`), solo si es Anual; en Bimestral se omite y va por concepto dentro de `adeudos`
`base_gravable`	float	Base de cálculo del impuesto de ese ejercicio, solo si es Anual; en Bimestral se omite y va por concepto dentro de `adeudos`
`adeudos`	array	Mismo formato de concepto que ConsultaAdeudo (ver tabla arriba)

Respuesta sin adeudos anteriores

Si la cuenta no existe en el catastro, mensaje_ciudadano lo indica explícitamente:

{
  "estatus_ejecucion": 0,
  "mensaje_ciudadano": "La cuenta predial ingresada no fue encontrada. Favor de verificar la información e intentar nuevamente.",
  "mensaje_tecnico": "No se han encontrado registros para la cuenta 12345 y el tipo_predio 1, corrobore la información.",
  "ejercicios": []
}

Si la cuenta sí existe pero no tiene rezago pendiente:

{
  "estatus_ejecucion": 0,
  "mensaje_ciudadano": "Sin adeudos de años anteriores.",
  "mensaje_tecnico": "sin periodos previos pendientes para tipo=1 cuenta=12345",
  "ejercicios": []
}