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.

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

{
  "estatus_ejecucion": 1,
  "mensaje_ciudadano": "",
  "mensaje_tecnico": "",
  "fecha_vigencia": "2024-12-31",
  "base_gravable": 450000.00,
  "adeudos": [
    {
      "clase_pago": 1,
      "bimestre": 0,
      "concepto": 1,
      "importe": 3600.00,
      "concepto_espejo": 0
    },
    {
      "clase_pago": 1,
      "bimestre": 0,
      "concepto": 2,
      "importe": 180.00,
      "concepto_espejo": 0
    },
    {
      "clase_pago": 1,
      "bimestre": 0,
      "concepto": 4,
      "importe": -1890.00,
      "concepto_espejo": 1
    }
  ]
}

Campo	Tipo	Descripción
`fecha_vigencia`	string	Fecha límite de vigencia (`YYYY-MM-DD`), solo presente cuando `clase_pago`=1 (Anual). Si el predio no tiene `fecha_vencimiento` en BD, se usa 30 de abril del año consultado como fallback. En Bimestral se omite aquí — cada elemento de `adeudos` trae su propia `fecha_vigencia` (los distintos bimestres del año pueden vencer en fechas distintas).
`base_gravable`	float	Base de cálculo del impuesto, solo presente cuando `clase_pago`=1 (Anual). En Bimestral se omite aquí — cada elemento de `adeudos` trae su propia `base_gravable`.

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
`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,
      "importe": 600.00,
      "fecha_vigencia": "2026-05-31",
      "base_gravable": 120000.00,
      "concepto_espejo": 0
    },
    {
      "clase_pago": 2,
      "bimestre": 4,
      "concepto": 1,
      "importe": 600.00,
      "fecha_vigencia": "2026-07-31",
      "base_gravable": 120000.00,
      "concepto_espejo": 0
    }
  ]
}

Tabla de conceptos

`concepto`	Descripción
`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 pendientes

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.",
  "adeudos": []
}

Si la cuenta sí existe pero no tiene adeudo pendiente del año en curso (ej. ya pagado):

{
  "estatus_ejecucion": 0,
  "mensaje_ciudadano": "Sin adeudos pendientes.",
  "mensaje_tecnico": "sin registros pendientes para tipo=1 cuenta=12345",
  "adeudos": []
}

ConsultaAdeudoAnterior

Devuelve los adeudos de años anteriores al actual (rezago histórico). A diferencia de ConsultaAdeudo —que solo cotiza el ejercicio en curso y usa el rezago únicamente para bloquear el pago si el tenant tiene activo predio_pref.bloquear_pago_periodos_previos— esta ruta ignora ese bloqueo y siempre devuelve todo lo pendiente con periodo anterior al año actual.

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": []
}