Comprobantes de Retención

POST/sunat/retenciones

Consulta los Comprobantes de Retención electrónicos (Catálogo 01 de SUNAT, tipo 20) emitidos o recibidos por un RUC, en un rango de fechas — directo contra el portal de SUNAT usando una sesión SOL (Clave SOL), sin necesidad de certificado digital.

Esto NO pasa por sendBill/billService (el SOAP que usa Emisión de comprobantes) — es una consulta contra el portal web de SUNAT (ol-ti-itcpretencion) con las mismas credenciales de Clave SOL, igual mecanismo que ya usa Descarga de CDR y Validación de comprobantes.

Parámetros (body, form-urlencoded)

Nombre	Requerido	Descripción
`fecha_desde`	Sí	Formato `dd/mm/yyyy`.
`fecha_hasta`	Sí	Formato `dd/mm/yyyy`.
`tipo_comprobante`	Opcional	Código de SUNAT para filtrar por tipo de comprobante de retención (`opcionTipoCompReten` del portal). Por defecto `000` (todos).
`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/retenciones \
  -H "Authorization: Bearer TU_API_TOKEN" \
  -d "fecha_desde=01/03/2026" -d "fecha_hasta=31/03/2026"

{
  "success": true,
  "total_registros": 2,
  "data": [
    {
      "ruc_emisor": "20123456789",
      "tipo_cpe": "20",
      "serie": "R001",
      "numero": "45",
      "tipo_doc_receptor": "6",
      "numero_documento_receptor": "20987654321",
      "fecha_emision": "05/03/2026",
      "regimen_retencion": "01",
      "observacion": "",
      "total_retenido": 120.50,
      "estado_cpe": "1",
      "procedencia": "",
      "comprobante_fisico": "",
      "ticket": "",
      "correo_receptor": ""
    }
  ],
  "message": "Se consulto con exito las retenciones."
}

Origen y alcance de este endpoint

Este endpoint viene de una migración puntual de un módulo del proceso Node hermano (wha/app/Controllers/Http/Apiperu/DownloadRetencionController.js) que nunca había sido expuesto en ningún endpoint activo. Al investigarlo junto con sus 4 archivos vecinos (RHE, Liquidación de Compra, Detracción, Percepción) se encontró que ninguno de los 5 usa el SOAP oficial de SUNAT — los 5 automatizan un navegador headless que hace login con Clave SOL en el portal web de SUNAT y luego, ya autenticado, consultan páginas/endpoints internos no documentados por SUNAT.

De los 5, este (Retenciones) fue el primero en migrarse: es el único cuyo código legacy propio deja ver, de forma completa y explícita, tanto el cuerpo exacto de la consulta como la forma de la respuesta — y reutiliza el mismo mecanismo de login SOL que Phalcon ya tenía reconstruido y probado (App\Library\Peru\SunatWebClient). Después, con una segunda ronda de investigación usando fuentes públicas externas, también se pudo migrar Detracciones — ver esa página para el detalle.

Los otros 3 (RHE, Liquidación de Compra, Percepción) quedan pendientes a propósito, sin inventar ningún endpoint: en cada uno, la parte crítica de la consulta la arma el propio Javascript de la página de SUNAT en tiempo real (o, en el caso de Percepción, el código legacy tiene un bug de copy-paste y en realidad nunca llegó a consultar percepciones). Verificarlos requeriría inspeccionar en vivo el tráfico real contra el portal de SUNAT, no solo leer el código Puppeteer heredado ni buscar en repositorios públicos (se buscó activamente y no se encontró nada citable para estos 3). El detalle técnico completo de cada uno está documentado en el docblock de App\Controllers\RecibosSunatController (código fuente de la API).

Referencia oficial

El Comprobante de Retención Electrónico (tipo 20 del Catálogo 01) está normado por la Resolución de Superintendencia N.° 274-2015/SUNAT (régimen de retenciones del IGV) y sus modificatorias. La consulta que expone este endpoint corresponde al buscador de comprobantes emitidos/recibidos del portal SOL de SUNAT (ol-ti-itcpretencion), no documentado formalmente por SUNAT como API pública.

Última actualización: 03/09/2026