Lubeca.TECH

00 · Resumen ejecutivo

Dos relojes distintos:
lo que se vendió y lo que se declaró.

El aeropuerto necesita las ventas de cada local. Hay dos fuentes posibles y no compiten: miden cosas distintas, con relojes distintos. El diseño de VMall consiste en tomar las dos y cruzarlas.

Lo que se vendió · T+0

Capturado por el sniffer en la caja del local: USB, serial, TCP, spool de impresión. Tiempo real. No depende de la voluntad de nadie. Cubre boletas y facturas.

Lo que se declaró · T+1 … T+8

Obtenido de SUNAT vía SIRE / RVIE, con credenciales delegadas del local. Detalle por comprobante, boletas incluidas, actualizado todos los días. Valor probatorio fiscal.

La tesis

La diferencia entre los dos relojes es la métrica de control. Un local que vende y no declara aparece como divergencia. Un local que demora el envío aparece como latencia anómala. Ninguna de las dos fuentes, por sí sola, permite ver eso.

Las tres vías de captura

VíaQué mideFreshnessCobertura
A · Sniffer en el POSLo vendidoT+0Total
B · Ingest de XML + CDRLo declarado, firmadoT+0 / T+1Total, si el emisor colabora
C · Credenciales delegadas + SIRELo declaradoT+1 … T+8Total (01, 03, 07, 08)
Dos límites que hay que decir en voz alta

SUNAT no enumera comprobantes de terceros. No existe ese endpoint y no va a existir: lo impide la reserva tributaria. Todo acceso nace de una credencial que otorga el propio local.

SUNAT no puede mostrar lo que todavía no recibió. La latencia del dato fiscal la define el comercio, no el servicio. Ninguna API la arregla.

01 · El pedido y su límite legal

Qué quiere el operador, y qué le impide SUNAT

El concesionario necesita las ventas por tres motivos, y cada uno tolera una precisión y una latencia distintas. Separarlos es lo que permite no sobre-diseñar.

Renta variable

Alquiler como porcentaje de ventas. Necesita ser auditable y exacto, con cierre mensual. Acá el respaldo fiscal vale oro.

Control y anti-subdeclaración

Detectar el delta entre lo vendido y lo reportado. Necesita dos fuentes independientes que no se puedan manipular a la vez.

Estadística operativa

Tickets por hora, ticket promedio, mix por terminal, correlación con vuelos. Tolera aproximación. Necesita tiempo real.

Mix de comprobantes

Retail de aeropuerto es abrumadoramente boleta de venta (tipo 03): pasajero, consumidor final. Las facturas son minoría. Esto condiciona todo.

El muro: reserva tributaria

La información que un contribuyente presenta a SUNAT está protegida. SUNAT no la entrega a terceros — ni al arrendador. No existe un endpoint que liste los comprobantes de otro RUC.

Todo lo que SUNAT ofrece cae en dos categorías:

  • Puntual, con RUC propio Consulta de validez: le pasás RUC + tipo + serie + número + fecha + monto y responde si es válido. Verifica, no descubre.
  • Con credenciales del emisor getStatusCdr, SIRE, portal SOL. Solo el emisor — o quien él autorice — puede usarlos.
Traducción

Cualquier propuesta que prometa “bajamos todo de SUNAT” sin tocar al local es falsa. La vía de las credenciales es legítima y funciona — pero es una delegación que el local otorga, no un acceso que SUNAT concede.

02 · Modelo de entidades

Quién es quién en la cadena

El error más caro es asumir que “un local = un RUC = una caja”. En la práctica no se cumple casi nunca.

Concesionario arrendador · consume el dato Local comercial unidad del contrato terminal · nivel · m² Contribuyente (RUC) emisor electrónico establecimiento anexo otorga las credenciales Punto de emisión caja / POS serie: F001 · B001 · B002 correlativo propio CPE 01 factura · 03 boleta 07 NC · 08 ND XML UBL 2.1 firmado SUNAT CDR firmado propuesta RVIE (diaria) reserva tributaria VMall captura · concilia verifica · alerta arrienda 1..N opera 1..N RUC tiene 1..N cajas emite declara SIRE diario sniffer · T+0
Fig. 1 — Dos caminos hacia VMall: el sniffer directo desde la caja, y el SIRE desde SUNAT con credenciales del local.

Las trampas del modelo

Supuesto ingenuoRealidad en el aeropuerto
Un local = un RUCUn operador de food court maneja varias marcas bajo un RUC; una franquicia puede tener RUC distinto al del contrato.
Un RUC = un localLa cadena factura desde el mismo RUC en el aeropuerto y en 30 tiendas de calle. Sin código de establecimiento anexo no se pueden separar las ventas del aeropuerto.
Una serie = una cajaSuele cumplirse, pero hay POS que rotan series o emiten desde un servidor central. La serie es la mejor clave de partición disponible: hay que fijarla por contrato.
Duty free vende igualRégimen aduanero distinto, IGV cero, series dedicadas. Sub-dominio aparte.
Primer entregable real

El maestro de mapeo local ↔ RUC ↔ establecimiento anexo ↔ serie. Sin eso, ningún dato es atribuible, venga de donde venga. Es relevamiento y contrato, no software — y es la primera dependencia crítica.

03 · Las tres vías

Dónde pinchamos el cable

A · Sniffer en el POS USB · Serial · TCP · spool ESC/POS T+0 · no depende del local B · Ingest XML + CDR push del emisor u OSE dato fiscal firmado · T+0/T+1 C · Credenciales + SIRE propuesta RVIE, poll diario todos los CPE · T+1…T+8 Gateway VMall normaliza · deduplica idempotencia por CPE_KEY cola offline-first Ledger append-only VENDIDO (sniffer) DECLARADO (SIRE / CDR) ANULADO (NC / baja) → BI · renta variable · alertas
Fig. 2 — Tres entradas, un ledger. El estado de cada venta guarda las dos verdades por separado, nunca fusionadas.
CriterioA · SnifferB · IngestC · SIRE
Cubre boletas (03)
Tiempo realCasiNo
Valor probatorio fiscalIndirectoAlto (CDR)Alto
Detecta NC y anulacionesParcial
Independiente del localNoNo
Onboarding por localMedio (hardware)Medio (su proveedor)Bajo (2 credenciales)
Cómo se combinan

C para todos — es barato, escala con dos credenciales por local y da el respaldo fiscal. A en los locales de mayor facturación o renta variable alta — es la única fuente independiente y en tiempo real. B donde el emisor del local sea un proveedor serio, porque el CDR firmado es el mejor dato que existe.

04 · Vía A

Sniffer: la única fuente que no controla el local

Capturamos el flujo de impresión o el tráfico del POS y reconstruimos el comprobante en el momento de la venta. Es la vía que ya dominamos, y la única cuya latencia no la decide el comercio.

El QR hace el trabajo pesado

Toda representación impresa de un CPE peruano lleva un QR con contenido normalizado:

# Contenido del QR impreso
20123456789|03|B001|0004512|10.80|70.80|2026-07-13|1|45678912|Kx8f...=
   RUC       tipo  serie  número   IGV    total    fecha    tDoc  nroDoc   hash

Con eso ya tenemos todo lo que necesita la consulta de validez de SUNAT: RUC, tipo, serie, número, fecha y monto. El sniffer descubre; SUNAT confirma. Y el mismo dato se cruza después contra el SIRE.

POS del local imprime ESC/POS emite solo a SUNAT tap Agente VMall USB / Serial / TCP parsea QR + totales cola SQLite offline reintento idempotente HTTPS mTLS Gateway CPE_KEY dedupe + normaliza estado: VENDIDO encola verificación SUNAT · validarcomprobante → VÁLIDO | ANULADO | NO EXISTE (aún) Ledger + BI venta atribuida al local estado fiscal adjunto alerta si diverge dashboards en vivo
Fig. 3 — El sniffer descubre; la consulta de validez confirma. La confirmación es asíncrona y puede tardar días: no bloquea nada.

Las señales que esto habilita

  • Impreso y nunca declarado → pasada la ventana de gracia, es venta fuera del sistema.
  • Impreso y luego anulado → venta real con comprobante dado de baja. Clásico de subdeclaración.
  • Monto impreso ≠ monto validado → la consulta valida contra el monto; si no coincide, salta.
  • Caja activa sin emisión → o venta en negro, o falla del agente. Hay que poder distinguirlas.
Rendimiento

La consulta de validez es puntual y con throttling. Con miles de boletas diarias hay que verificar de forma asíncrona: muestreo en el caudal normal, verificación al 100% sobre lo que dispara alertas y en el cierre de renta variable. El grueso de la conciliación lo hace el SIRE, no esta API.

05 · Vía B

Ingest de XML + CDR: el dato con sello

Para locales con un emisor serio (cadena, ERP, OSE contratado), lo mejor es que nos manden copia del XML firmado y del CDR. Es el mismo artefacto que tiene SUNAT, con la firma del emisor y la constancia firmada por SUNAT o el OSE.

B1 · Push desde el emisor

Su sistema de facturación, al recibir el CDR, hace un POST al gateway de VMall con el par XML+CDR. Para su proveedor es un webhook trivial.

B2 · Relay desde el OSE

Si el local usa OSE, el OSE ya tiene todo. Con autorización escrita del local, se negocia un feed de copia. Un acuerdo cubre decenas de locales.

Emisor del local genera UBL 2.1 firma XMLDSig certificado propio sendBill SUNAT / OSE valida firma el CDR devuelve ZIP CDR aceptado B2 · relay OSE B1 · push del emisor · XML + CDR Gateway VMall verifica la firma del CDR valida cadena del certificado extrae total · IGV · fecha extrae cód. establecimiento mapea serie → local estado: DECLARADO idempotente por CPE_KEY Ledger oro puro
Fig. 4 — El CDR viene firmado por SUNAT. Si VMall verifica esa firma, el dato es prueba en sí mismo.
Ventaja decisiva

No hace falta ni consultar la API ni confiar en el local: el CDR está firmado digitalmente por SUNAT. Para el cálculo de renta variable es el estándar de oro, y llega en el momento — sin esperar la ventana del SIRE.

06 · Vía C

Credenciales delegadas: qué pedir y qué no

El aeropuerto va a exigirle al local que comparta acceso a SUNAT. Es viable — pero hay que pedir el artefacto correcto, y hay uno que no se pide nunca.

El certificado digital no es lo que parece

Quien viene de ARCA asume que el certificado es una credencial de acceso. En Perú no lo es.

ArtefactoPara qué sirve en Perú¿Se pide?
Usuario secundario SOLAutentica contra los web services. Este es el equivalente funcional del certificado WSAA.
client_id / client_secretCredencial OAuth2 para las APIs REST (SIRE).
Clave SOL principalAcceso total al RUC: declaraciones, devoluciones, emisión, datos del RUC.Nunca
Certificado digitalFirma el comprobante. Es la identidad fiscal: quien lo tiene emite facturas a nombre del local.Nunca
Sin excepciones

El certificado digital peruano no autentica nada y no sirve para leer. Solo sirve para emitir. Pedirlo sería asumir un riesgo enorme a cambio de cero funcionalidad.

Lo que el comercio genera para VMall

Clave SOL principal — todo abierto Consulta CPE SIRE Emitir facturas Anular CPE Declaraciones Devoluciones Datos del RUC Buzón SOL Credenciales API VMall respondería por todo lo que pase con ese RUC Usuario secundario — perfil acotado Consulta CPE SIRE (RVIE) y nada más Aun así, queda expuesto a: · revocación unilateral por el local · rotación de la contraseña · colisión de credenciales de API Aceptable. Requiere health-check por local.
Fig. 5 — Reducir la superficie no elimina el riesgo operativo, pero sí el riesgo catastrófico.

Dos artefactos, ambos generados por el titular desde su Clave SOL, ambos revocables:

  1. Usuario secundario SOL — el titular marca perfiles y opciones. Se le habilita solo consulta de CPE y el módulo SIRE.
  2. Credenciales de API SUNAT — registra la aplicación (VMall) y marca la casilla MIGE RCE y RVIE – SIRE. Salen client_id y client_secret.
# Token — grant password, con el usuario secundario
POST https://api-seguridad.sunat.gob.pe/v1/clientessol/{client_id}/oauth2/token/
Content-Type: application/x-www-form-urlencoded

grant_type=password
&scope=https://api-cpe.sunat.gob.pe
&client_id=...&client_secret=...
&username={RUC}{usuarioSecundario}
&password={clave del usuario secundario}
Spike bloqueante — antes de comprometer nada

Verificar en beta que un usuario secundario puede (a) generar credenciales de API y (b) consumir SIRE. La documentación habla del “contribuyente” de forma genérica. Si SUNAT exigiera el usuario principal, cambia todo el modelo de custodia. Es medio día de trabajo.

07 · SIRE / RVIE

El motor fiscal: diario, completo, con boletas

Este es el hallazgo que cambia la arquitectura. El SIRE (Sistema Integrado de Registros Electrónicos) es el reemplazo del PLE. Su módulo RVIE es el registro de ventas — y SUNAT lo arma sola, a partir de los CPE que recibió del emisor.

Lo importante

La propuesta del RVIE se publica desde el 2° día calendario de cada mes y se actualiza todos los días de forma automática con lo recibido el día anterior. No es un archivo de cierre: es un registro vivo del mes en curso, con detalle individualizado por comprobante — facturas, boletas, notas de crédito y de débito.

Es el FECompConsultar masivo que no existe en el billService

Es la única vía que enumera comprobantes sin conocerlos de antemano, y la única que trae boletas. Con credenciales del local, se poll-ea todos los días.

# Job diario, por cada RUC del aeropuerto
GET https://apisire.sunat.gob.pe/v1/contribuyente/migeigv/libros/rvie/
    propuesta/web/propuesta/202607/exportapropuesta
    ?fecDocumentoDesde=01/07/2026&fecDocumentoHasta=13/07/2026
Authorization: Bearer <token>

# Flujo asíncrono con ticket
→ numTicket                          // la descarga se encola
→ consultar estado del ticket        // hasta "Terminado"
→ descargar archivo (zip particionado)
→ diff contra el ledger por CPE_KEY  // RUC|tipo|serie|nro
Propuesta RVIE del periodo 202607 — crece todos los días día 212 CPE día 341 CPE día 478 CPE hoy1.204 CPE mañana+ lo de hoy poll diario · diff incremental · idempotente por CPE_KEY Qué trae cada fila tipo · serie · número fecha de emisión base imponible · IGV · total estado (incl. bajas y NC) Lo que NO trae las ventas que el local todavía no envió a SUNAT — ver sección 08
Fig. 6 — El SIRE no es un cierre mensual: es un ledger fiscal que se actualiza a diario y se consulta a diario.
El techo

La propuesta solo contiene lo que SUNAT ya recibió. Si el local no envió, no está. Diario no es lo mismo que tiempo real — y eso no lo arregla ninguna API.

08 · Latencia

Quién controla el reloj

Los 3 días para facturas y los 7 para el resumen diario de boletas son un techo legal, no un calendario. La fórmula real es:

lag = [ cuándo el comercio decide enviar ]  +  [ SUNAT lo incorpora ≈ +1 día ]
        ↑ variable, la controla él            ↑ fijo
Sniffer — no depende de nadie T+0 · instantáneo POS que envía al emitir T+1 · vendió ayer, lo ves hoy Resumen diario al cierre de caja T+1 / T+2 Resumen "cuando el contador puede" T+3 … T+5 Local que apura el plazo legal T+8 · el máximo T+0 +1 +2 +4 +8
Fig. 7 — La latencia del dato fiscal es una decisión del comercio. Los plazos son indicativos; confirmar contra la norma vigente.

En la práctica, la mayoría de los sistemas peruanos envían la factura en el momento y el resumen diario al cierre. Para el local promedio, sí: vendió ayer, hoy lo tenés. Pero es una consecuencia de cómo está configurado su software, no una garantía del sistema.

La ironía que hay que anticipar

El local que subdeclara también demora el envío. Los que peor freshness te dan son exactamente los que más querés vigilar. No se puede construir el control sobre una fuente cuya latencia la define el controlado.

Tres respuestas

  1. Cláusula de envío el mismo día. Le quita la discrecionalidad. Con eso, T+1 pasa a ser el caso normal, no el mejor caso. Es una línea de contrato y es gratis.
  2. El retraso, convertido en métrica. Un dashboard de días promedio entre venta y aparición en SIRE, por local señala a quien manipula el pipeline sin necesidad de detectar un solo sol mal declarado. Se le vende al aeropuerto como funcionalidad.
  3. El sniffer, que no depende de nadie. Único reloj que el local no controla.
Spike opcional

La norma menciona, además de la actualización con lo recibido el día anterior, una opción para actualizar la propuesta con lo enviado en el día. Si el API expone esa acción, para los CPE ya enviados se podría bajar a T+0. Vale medio día verificarlo en beta.

09 · Boletas

Dónde está el dinero, y por qué casi lo perdemos

El retail de aeropuerto vende sobre todo a pasajeros: boleta de venta, tipo 03. Ese es el 80–90% del volumen. Y las boletas son el punto donde la mayoría de las integraciones se rompen.

Participación en las ventas BOLETAS (03) FACTURAS (01) Vía SOAP · getStatusCdr CIEGO — el método solo cubre 01 / 07 / 08 VISIBLE Vía SIRE · exportapropuesta + sniffer VISIBLE — detalle por comprobante, boletas incluidas
Fig. 8 — La vía SOAP que parece obvia es ciega donde está el dinero. El SIRE y el sniffer, no.

Por qué getStatusCdr no alcanza

  • El método está pensado para facturas y sus notas (01, 07, 08). Las boletas no se consultan una por una con él.
  • Las boletas viajan a SUNAT en resumen diario, y el CDR del resumen no detalla boleta por boleta.

Por qué el SIRE sí

La propuesta del RVIE se construye a partir de todos los CPE que SUNAT recibió — incluidas las boletas informadas por resumen diario — y las expone con detalle individualizado. Es la única vía de descubrimiento que las cubre.

Y el sniffer cierra el círculo

El sniffer captura la boleta en la caja con su QR. La consulta de validez —a diferencia de getStatusCdrsí acepta boletas, siempre que se le den serie, número, fecha y monto: exactamente lo que el sniffer extrajo. Verificación puntual disponible desde el minuto cero, con la salvedad de que hasta que el local no envíe el resumen, SUNAT responderá que no existe. La lógica de alertas debe esperar la ventana antes de gritar fraude.

10 · Métodos de web service

Qué se llama, exactamente

1 · SIRE / RVIE — REST · credenciales del local

El motor de la vía C. Descubre y enumera. Detalle por comprobante, actualización diaria.

ServicioUso
oauth2/token (clientessol)Token con grant_type=password + client_id/secret + usuario secundario.
exportapropuestaDescarga la propuesta del RVIE del periodo, filtrable por rango de fechas. Devuelve ticket.
consultar estado ticketHasta “Terminado”; devuelve el nombre del archivo generado.
descargar archivoBaja el ZIP particionado con el detalle.

2 · Consulta de validez — REST · credenciales de VMall

Verificación puntual. Quien consulta es VMall con su propio RUC, no el local. Se usa para confirmar lo que trajo el sniffer.

POST https://api-seguridad.sunat.gob.pe/v1/clientesextranet/{client_id}/oauth2/token/
POST https://api.sunat.gob.pe/v1/contribuyente/contribuyentes/{RUC_VMALL}/validarcomprobante
{
  "numRuc": "20123456789", "codComp": "03", "numeroSerie": "B001",
  "numero": "4512", "fechaEmision": "13/07/2026", "monto": "70.80"
}
// → estadoCp: aceptado | anulado | no existe ;  estadoRuc ;  condDomiRuc

Acepta boletas. No cubre guías de remisión ni percepciones/retenciones.

3 · billService — SOAP · credenciales del local

MétodoPara quéNos sirve
getStatusCdrRecupera el CDR de un comprobante ya enviado: RUC + tipo + serie + número.Complemento. Solo 01/07/08. Permite walk del correlativo para descubrir facturas nuevas en horas.
sendBill · sendSummary · getStatusEmisión.No aplica — VMall no emite.
Lo que no existe

No hay listarComprobantes para terceros. No hay webhook de SUNAT hacia un tercero. No hay endpoint masivo de validez. Todo descubrimiento pasa por el SIRE, con credenciales que otorga el local.

11 · Lo complicado

Los riesgos, sin maquillaje

Esta es la sección que hay que llevar a la reunión. Un proveedor que solo muestra el camino feliz pierde credibilidad ante un operador aeroportuario.

Credenciales

RiesgoPor qué dueleMitigación
Colisión de credenciales de API SUNAT inhabilita las credenciales anteriores cuando se solicitan nuevas. Si el contador o el proveedor de facturación del local regenera las suyas, la integración de VMall muere en silencio. En ARCA podés tener certificados conviviendo; acá no. Health-check diario por local. Alerta inmediata ante fallo de token. Cláusula que obligue a avisar antes de regenerar.
Rotación de la clave SOL El local cambia la contraseña cuando quiere. Un certificado dura años; una contraseña dura lo que dura la paciencia del dueño. El churn de credenciales va a ser mucho mayor que en Argentina. Presupuestar soporte de onboarding continuo. Dashboard de “locales sin datos” visible para el aeropuerto.
Clave SOL principal Acceso total al RUC. VMall pasaría a custodiar un riesgo fiscal ajeno. Prohibida por política. Solo usuario secundario con perfil acotado.
Certificado digital Permite emitir facturas a nombre del local. No se pide. No se necesita para ninguna de las tres vías.
VMall como honeypot Con credenciales de N locales, VMall concentra un riesgo que antes estaba disperso. El aeropuerto exige, pero VMall custodia. Vault, cifrado en reposo, aislamiento por tenant, redacción en logs. Límite de responsabilidad explícito en el contrato.

Técnicos

  • Sin API masiva de validez. Consultas de a una, con throttling. El grueso de la conciliación lo hace el SIRE.
  • Disponibilidad de SUNAT. Se cae, y no hay plan B. El ledger tiene que seguir operando con estado VENDIDO y verificar cuando pueda.
  • Cambios normativos. Catálogos y validaciones cambian por resolución con fechas de corte. Todo parser tiene que estar versionado.
  • POS cerrados. Algunas cadenas internacionales no imprimen localmente o cifran el tráfico: ahí la vía A no aplica y hay que ir a B o C.
  • Establecimiento anexo ausente. Si el CPE no trae el código, no se distingue la venta del aeropuerto de la de la sucursal del centro. Se exige por contrato o se resuelve por serie.
  • El SIRE también se corrige. El local puede complementar o reemplazar la propuesta. Lo que leíste ayer puede cambiar hoy. El ledger debe ser append-only y reprocesar.

Legales

  • Reserva tributaria. Toda autorización nace del local, por escrito. SUNAT no entrega nada de terceros.
  • Protección de datos. Los CPE llevan el documento del comprador. Para contar ventas ese dato no hace falta: descartarlo en la ingesta es la mejor decisión de compliance disponible.
  • Confidencialidad comercial. Un local nunca debe poder ver las ventas de otro. Aislamiento por tenant desde el día uno.

12 · Cláusulas contractuales

Lo que no se resuelve con ingeniería

La palanca real es el contrato de arrendamiento. Casi todos los contratos de centro comercial ya obligan a reportar ventas; lo que falta es el cómo. Estas son las cláusulas que hay que pedir, en orden de importancia.

1 · Medio de reporte obligatorio

El local adhiere a al menos una de las tres vías: agente de captura en caja, push de XML+CDR, o credenciales delegadas. Sin esta cláusula, la cobertura depende de la buena voluntad de cada inquilino — y ahí el proyecto se muere.

2 · Envío el mismo día

El local se obliga a enviar sus CPE y su resumen diario a SUNAT el mismo día de emisión, sin agotar el plazo legal. Colapsa la latencia de T+8 a T+1. Es gratis y es la mejor línea del contrato.

3 · Credenciales acotadas

Se entrega usuario secundario SOL con perfil limitado + credenciales de API. Se prohíbe expresamente la entrega de la Clave SOL principal y del certificado digital. Obligación de avisar antes de regenerar credenciales.

4 · Identificación del establecimiento

El local declara y mantiene actualizado el mapeo RUC ↔ establecimiento anexo ↔ series usadas en el aeropuerto, y notifica todo cambio de serie o de sistema de facturación.

5 · Tratamiento de datos

Encargo de tratamiento, finalidad limitada al control de ventas, confidencialidad y límite de responsabilidad de VMall respecto de las credenciales custodiadas.

6 · Acceso físico

Para la vía A: acceso a la caja para instalar y mantener el agente, y prohibición de desconectarlo. Un agente apagado es una señal, pero es mejor que no pase.

Lo que hay que pedirle al aeropuerto

Que la adhesión sea obligatoria en la renovación de contrato. Es la única dependencia que no se resuelve con software, y es la que decide si el proyecto cubre el 30% o el 95% de los locales.

13 · Arquitectura y fases

Lo que proponemos construir

CAPTACIÓN Agente sniffer (T+0)USB/Serial/TCP · cola SQLite · mTLS Poller SIRE (diario)token · exportapropuesta · ticket · zip Webhook XML + CDRpush del emisor o relay del OSE GATEWAY · SPRING BOOT Ingesta idempotenteCPE_KEY NormalizadorUBL + TXT del SIRE, versionados Verificador de firmaXMLDSig del CDR Vault de credencialespor tenant · health-check NÚCLEO Ledger append-onlyVENDIDO · DECLARADO · ANULADO Motor de conciliaciónventana de gracia · divergencias Métricas de cumplimientolatencia de declaración por local CONSUMO Dashboards en vivo Renta variable Alertas de control
Fig. 9 — El ledger guarda las dos verdades por separado. La conciliación es un proceso, no un campo.

Reglas de diseño no negociables

  • Ledger append-only. Una venta no se sobrescribe: acumula eventos. El BI lee la proyección; la auditoría lee los eventos.
  • Ventana de gracia antes de alertar. “No existe en SUNAT” a las 2 horas es normal; a los 10 días es una señal. Umbral configurable por tipo de comprobante.
  • Reproceso obligatorio. Toda venta se re-verifica pasada la ventana y otra vez en el cierre. Las notas de crédito llegan tarde y restan.
  • El cierre de renta variable es un corte versionado, no un “último dato”: el mes se sigue moviendo después de cerrado.

Fases

FaseAlcanceDepende de
0 · SpikesValidar en beta: usuario secundario → credenciales API → SIRE. Y si existe la actualización intradía.Un RUC de prueba.
1 · MaestroRelevamiento y mapeo local ↔ RUC ↔ establecimiento ↔ serie.Acceso a los contratos.
2 · SIREPoller diario + ledger + dashboards de ventas declaradas. Cobertura amplia con esfuerzo bajo por local.Credenciales delegadas.
3 · SnifferAgente en los locales de mayor facturación. Aparece el eje “vendido vs declarado”.Acceso físico a las cajas.
4 · Ingest fiscalWebhook XML+CDR para cadenas grandes; relay con uno o dos OSE.Cláusula de reporte.
5 · EscalaTodo el aeropuerto. Renta variable automatizada y auditable.Adhesión obligatoria en renovaciones.
El mensaje de cierre

El aeropuerto no necesita una integración con SUNAT. Necesita saber cuánto vende cada local y poder probarlo. El SIRE le da lo que el local declaró, todos los días. El sniffer le da lo que el local vendió, en el momento. VMall es la única propuesta que le entrega las dos cosas — y la diferencia entre ambas.

14 · Anexo técnico

Referencia rápida

Endpoints

ServicioURL
Token · APIs del contribuyente (SIRE)https://api-seguridad.sunat.gob.pe/v1/clientessol/{client_id}/oauth2/token/
Token · API externa (validez, RUC de VMall)https://api-seguridad.sunat.gob.pe/v1/clientesextranet/{client_id}/oauth2/token/
SIRE · RVIEhttps://apisire.sunat.gob.pe/v1/contribuyente/migeigv/libros/rvie/…
Consulta de validezhttps://api.sunat.gob.pe/v1/contribuyente/contribuyentes/{RUC}/validarcomprobante
billService (producción)https://e-factura.sunat.gob.pe/ol-ti-itcpfegem/billService?wsdl
billService (beta)https://e-beta.sunat.gob.pe/ol-ti-itcpfegem-beta/billService
user: {RUC}MODDATOS · pass: MODDATOS
Consulta manual (web)https://e-consulta.sunat.gob.pe/ol-ti-itconsvalicpe/ConsValiCpe.htm

Tipos de comprobante

CódigoDocumentoSerieEnvío a SUNAT¿En SIRE?
01FacturaF###Individual
03Boleta de ventaB###Resumen diario
07Nota de créditoF### / B###Sigue al afectado
08Nota de débitoF### / B###Sigue al afectado
09Guía de remisiónT###API REST propiaNo

Clave natural del comprobante

CPE_KEY = RUC_EMISOR | TIPO_DOC | SERIE | CORRELATIVO
// ejemplo
20123456789|03|B001|0004512

Es la clave de idempotencia del gateway y coincide con el nombre de archivo que exige SUNAT (20123456789-03-B001-4512.xml). Se usa igual en las tres vías, para que converjan sin ambigüedad.

Bibliotecas de referencia

  • Greenter (PHP) — implementación de referencia del ecosistema; su documentación es la mejor fuente no oficial sobre UBL peruano.
  • olanaso/sunat-web-services (Java) — cliente SOAP con builders para getStatusCdr. Encaja con el stack Spring Boot.
  • thegreenter/consulta-cpe-openapi — spec OpenAPI de la consulta de validez, para generar el cliente REST.
  • Manuales oficiales de Servicios Web API SIRE Ventas — la fuente de verdad para el poller.

A verificar antes de la reunión

  • Plazos vigentes de envío de facturas y de resumen diario (cambian por resolución).
  • Resolución 000048-2026/SUNAT: nuevas validaciones y catálogos con vigencia desde agosto de 2026.
  • Calendario de obligatoriedad del SIRE por régimen y tamaño de contribuyente.
  • Que un usuario secundario pueda generar credenciales de API y consumir SIRE.
Sobre este documento

Preparado por Lubeca.TECH para la presentación de VMall al operador del Aeropuerto Internacional Jorge Chávez. Los plazos regulatorios y umbrales citados deben confirmarse contra la normativa vigente al momento de la firma. Archivo HTML autocontenido.

00 / 14