Consulta de Detracciones (SPOT)

POST/sunat/detracciones

Consulta los pagos/comprobantes del Sistema de Pago de Obligaciones Tributarias (SPOT, "detracciones") registrados a nombre del RUC autenticado, en un rango de fechas — directo contra el portal de SUNAT usando una sesión de Clave SOL, sin necesidad de certificado digital.

Esto NO pasa por sendBill/billService (el SOAP que usa Emisión de comprobantes) ni por la misma sesión SOL que usan Descarga de CDR/Comprobantes de Retención: las Detracciones viven en la "Nueva Plataforma" de SUNAT (e-plataformaunica.sunat.gob.pe, menú cl-ti-itmenu2), que exige un login OAuth2 distinto (otro client UUID, otro flujo de "state" dinámico). Ver el docblock de SunatWebClient::loginNuevaPlataforma() en el código fuente de la API para el detalle técnico completo.

Parámetros (body, form-urlencoded)

Nombre	Requerido	Descripción
`fecha_desde`	Sí	Formato `dd/mm/yyyy`.
`fecha_hasta`	Sí	Formato `dd/mm/yyyy`.
`tipo_cuenta`	Opcional	Por defecto `1` (único valor confirmado en la fuente pública usada para reconstruir este endpoint).
`tipo_consulta`	Opcional	Por defecto `pagosIndividuales` (único valor confirmado en la fuente pública).
`periodo`	Opcional	Periodo tributario a filtrar. Puede dejarse vacío.
`ruc` / `usuario_sol` / `clave_sol`	Opcional	Si no las envías, se usan las credenciales SOL guardadas en tu cuenta; si tampoco tienes, se usa la cuenta SOL general del negocio.

Ejemplo

curl -X POST https://mblapirest.com/api/v1/sunat/detracciones \
  -H "Authorization: Bearer TU_API_TOKEN" \
  -d "fecha_desde=01/03/2026" -d "fecha_hasta=31/03/2026"

{
  "success": true,
  "total_registros": 1,
  "data": [
    {
      "num_pres": "12345678",
      "usuario_sol": "USUARIOSOL",
      "proveedor": "PROVEEDOR SAC",
      "tipo_comprobante": "01",
      "ruc_proveedor": "20123456789",
      "periodo_tributario": "202603",
      "fecha_pago_desc": "15/03/2026",
      "numero_npd": "001",
      "adquiriente": "MI EMPRESA SAC",
      "numero_constancia": "12345678901",
      "tipo_bien": "019",
      "tipo_operacion": "01",
      "tipo_doc_adquiriente": "6",
      "numero_doc_adquiriente": "20987654321",
      "monto_deposito_desc": "120.50",
      "numero_cuenta": "00-000-000000",
      "monto_deposito": 120.5,
      "numero_comprobante": "451",
      "fecha_pago": "2026-03-15 10:30:00",
      "numero_serie": "F001",
      "origen": "WEB",
      "tipo_cuenta": "1"
    }
  ],
  "message": "Se consulto con exito las detracciones."
}

Origen, alcance y honestidad de este endpoint

Este endpoint viene de la misma investigación que Comprobantes de Retención: un módulo del proceso Node hermano (wha/app/Controllers/Http/Apiperu/DownloadDetraccionController.js) que nunca había sido expuesto en ningún endpoint activo. A diferencia de Retenciones, ese código legacy propio solo daba la URL final de consulta (GET .../v1/recaudacion/tributaria/declapago/detracciones/t/consultar) sin el mecanismo de login, porque requiere una sesión OAuth2 distinta a la del resto de la API.

Se completó con una segunda ronda de investigación, esta vez con fuentes públicas externas (repositorios de GitHub de otros desarrolladores peruanos, no código propio):

El cuerpo completo de esa misma URL de consulta (query string y forma exacta de la respuesta JSON) se encontró en producción, real, en github.com/jfrancito/merge.
El client UUID de OAuth2 que usa el login de la "Nueva Plataforma" (cl-ti-itmenu2) — distinto al que usa el resto de la API — aparece idéntico en 4+ repositorios públicos independientes (ej. DavidSanchezz2004/Proyecto---ucv, santi1475/front-WJ, Gianpierre-dev/Sistema-de-automatizaciones-Sunat-, u20231e277/MomWork), junto con el mecanismo exacto (2 pasos, "state" dinámico) para loguearse ahí.
crafter-research/sunat-cli documenta, con reconocimiento en vivo (navegador real, marzo 2026), que entrar directo a esa página exige reCAPTCHA v2, pero hacer login SOL "viejo" primero evita ese captcha.

Lo que NO se pudo verificar (no se probó con credenciales reales — no las tenemos, y no corresponde pedirlas al cliente por chat para una prueba interna): si SUNAT igual exige el reCAPTCHA para este login cuando se hace por cURL puro (sin navegador real "calentando" la sesión antes). Si esto falla en producción, la causa más probable es esa, y la solución requiere una prueba manual en vivo, no más lectura de código. Tampoco se replica un header idcache que la fuente pública usa (ver docblock de consultarDetracciones() para el detalle) porque no hay forma honesta de generarlo desde este flujo de login.

Los otros 3 módulos pendientes de la investigación original (RHE, Liquidación de Compra, Percepción) siguen sin endpoint público verificable — ver el docblock de RecibosSunatController (código fuente de la API) para el detalle completo de qué se buscó y qué falta de cada uno.

Referencia oficial

El Sistema de Pago de Obligaciones Tributarias (SPOT / "detracciones") está normado por el Decreto Legislativo N.° 940 y sus modificatorias. La consulta que expone este endpoint corresponde al buscador de "Consulta de pagos" de la Nueva Plataforma de Declaraciones y Pagos de SUNAT, no documentado formalmente por SUNAT como API pública.

Última actualización: 03/09/2026