Una cadena retail con cuarenta sucursales en Perú genera unos seiscientos reclamos al mes a través del libro virtual. Sin API, esa data vive aislada en el SaaS del libro y el equipo de atención la replica manualmente en el CRM corporativo. Con API, el reclamo entra en HubSpot al instante, dispara un caso en Salesforce, suma un ticket en el ERP y cierra el ciclo cuando el supervisor responde dentro del plazo legal. La diferencia, medida en horas-hombre, sale en seis cifras al año.
Esta guía explica qué resuelve la API del libro virtual, qué endpoints suele exponer, cómo se integra con SAP, Salesforce y HubSpot, cómo se automatiza la exportación a SIREC, qué consideraciones de seguridad importan y cómo se autentica. La audiencia es gerencia de TI y desarrolladores. El nivel técnico es claro pero sin pretensión: lo que un equipo necesita para evaluar viabilidad antes de pedir un piloto.
Por qué una empresa con muchas sucursales necesita API
El libro virtual con interfaz web cumple con la norma. La Ley 29571, el DS 011-2011-PCM y la Ley 32495 no exigen integración por API. Lo exige la operación. Cuando una cadena tiene veinte o más sucursales, el equipo de atención no puede entrar al panel del SaaS por cada reclamo, copiar el caso al CRM y volver a salir. Una API elimina ese paso, reduce errores de transcripción y mantiene un único flujo de gestión.
El segundo motivo es trazabilidad. El reclamo recibido por libro virtual debe convertirse en una acción operativa: contactar al cliente, identificar la sucursal responsable, asignar al supervisor regional, registrar la solución, responder dentro de los quince días hábiles que fija la Ley 31435. Sin API, cada paso pasa por correo manual. Con API, cada paso queda registrado con timestamp en el sistema corporativo, lo que protege al negocio durante una fiscalización de Indecopi.
El tercero es reporting consolidado. La gerencia comercial quiere ver reclamos cruzados con ventas, devoluciones, fidelización y NPS. Esos datos viven en distintos sistemas (POS, ERP, CRM, BI). Una API que entrega los reclamos en JSON o XML los integra al data lake corporativo y los hace cruzables con el resto. Sin API, los reclamos quedan como una hoja Excel aparte que rara vez se mira hasta que aparece un problema.
Endpoints típicos que expone un libro virtual con API
Una API REST de libro virtual suele organizar sus endpoints alrededor de tres recursos: reclamos, sucursales y catálogo de respuestas. El endpoint principal es la creación de reclamo, normalmente un POST que recibe en el cuerpo un JSON con los campos del Anexo I del DS 011-2011-PCM: identificación del consumidor, descripción del hecho, tipo (reclamo o queja), pedido del consumidor, fecha y canal. La respuesta devuelve el código único de reclamo generado.
El segundo endpoint clave es el listado, un GET que devuelve los reclamos del establecimiento filtrables por sucursal, estado, rango de fechas y motivo. Suele paginarse para evitar respuestas pesadas. El tercer endpoint es la actualización, normalmente un PUT o PATCH que permite registrar la respuesta del negocio, la fecha de cierre y el resultado (aceptado, rechazado, parcial). El cuarto es la exportación, un GET que devuelve el lote en formato compatible con SIREC u otro reportador sectorial.
Algunos SaaS exponen también endpoints auxiliares: subir adjuntos (fotos del producto, copia de la boleta), consultar el estado de un reclamo individual y obtener notificaciones por webhook cuando cambia el estado. Los webhooks evitan polling: el sistema del cliente recibe un POST en una URL configurada cada vez que entra un reclamo nuevo o se actualiza uno existente. Esa arquitectura escala mejor que consultar el listado cada cinco minutos.
Integración con SAP, Salesforce y HubSpot
Con SAP, la integración pasa típicamente por el módulo de Customer Service o por una capa intermedia como SAP Cloud Platform Integration. El reclamo entrante se convierte en un caso (notification) dentro del módulo de Service. La trazabilidad se gana porque el caso queda vinculado al cliente, al material vendido y a la sucursal de venta. La respuesta del libro se genera desde SAP y se devuelve al libro virtual con un PUT a la API.
Con Salesforce, la integración usa Service Cloud. El reclamo entrante crea un Case con el tipo Reclamo Virtual y el Origen Libro de Reclamaciones. Las reglas de asignación de Salesforce derivan automáticamente al equipo de la sucursal responsable. Cuando el caso se cierra dentro de Salesforce, un flujo (Flow) envía la respuesta al libro virtual y marca el reclamo como respondido. El SLA se mide con los timers nativos de Service Cloud.
Con HubSpot, el reclamo se recibe en el Service Hub como ticket. El pipeline de tickets se configura con etapas que reflejan el flujo legal: recibido, en análisis, respuesta enviada, cerrado. La integración usa Operations Hub para sincronizar campos personalizados o, en su versión más simple, se monta sobre Zapier o Make con el endpoint webhook del libro virtual. Para una pyme con HubSpot básico, esa segunda ruta es suficiente y no exige desarrollo.
Exportación a SIREC y reportes sectoriales
SIREC es el sistema de reporte de reclamos que Indecopi habilita para que los proveedores notifiquen los reclamos recibidos. La obligación de reporte aplica a ciertos sectores y volúmenes, definidos en el DS 058-2017-PCM y normas complementarias. Una API del libro virtual debería ofrecer un endpoint de exportación que entregue los reclamos en el formato esperado por SIREC, idealmente listo para cargar sin transformación manual.
La frecuencia de reporte a SIREC depende del sector. Para algunos rubros, el reporte es mensual; para otros, trimestral. Una API bien diseñada permite generar el archivo de exportación con una llamada GET parametrizada por rango de fechas y entregarlo en CSV o XML, según la versión vigente del esquema SIREC. La empresa programa la generación cada mes y la carga manual al portal del regulador, o automatiza la subida si el sistema lo permite.
Otros reportes sectoriales pueden requerir formatos distintos. SBS, Sutran y Minsa tienen plantillas propias para reclamos en sus respectivos sectores. La API del libro virtual no resuelve esos reportes automáticamente, pero entrega la data limpia que el equipo de cumplimiento transforma al formato del regulador. Una empresa de transporte interprovincial, por ejemplo, exporta los reclamos del libro virtual y los mapea al reporte trimestral que Sutran exige.
Seguridad y autenticación
La autenticación estándar de una API de libro virtual es OAuth 2.0 con flujo de credenciales de cliente para integraciones servidor-a-servidor. La empresa recibe un client_id y un client_secret, los intercambia por un access_token y usa ese token en el header Authorization de cada llamada. Los tokens caducan en horas o días, según política del proveedor, y se renuevan con un refresh_token.
Algunas APIs ofrecen una alternativa más simple: API key estática que se envía como header personalizado. Funciona para pruebas o integraciones internas, pero presenta más riesgo si la key se filtra. Para producción, OAuth 2.0 con tokens rotativos es la opción recomendable. Adicionalmente, el proveedor suele limitar las direcciones IP desde donde se aceptan llamadas, lo que reduce el riesgo de uso indebido si la credencial se compromete.
Los datos del libro de reclamaciones son datos personales del consumidor (nombre, DNI, correo, descripción del incidente). La transmisión debe cifrarse con TLS 1.2 o superior. El almacenamiento de la API key o del client_secret nunca debe quedar en código versionado: va en un gestor de secretos (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) o, como mínimo, en variables de entorno restringidas. La Ley 29733 de Protección de Datos Personales aplica al tratamiento que la empresa haga con esa información, y el incumplimiento abre un frente sancionatorio adicional.
Casos de uso y limitaciones reales de la integración
Caso A: cadena de farmacias con cien sucursales. El libro virtual recibe reclamos por dispensación errónea, vencimiento de productos y atención del personal. La API entrega los reclamos a un sistema interno que cruza con la base de ventas del POS para identificar al farmacéutico de turno. La gerencia de operaciones recibe un dashboard semanal con sucursales en zona roja. El tiempo de respuesta promedio bajó de doce a cuatro días desde la implementación.
Caso B: cadena de educación con quince sedes. Los reclamos del libro virtual entran a HubSpot como tickets. El pipeline tiene cinco etapas con SLA propio. El coordinador académico de cada sede ve solo los tickets de su sede. La respuesta a través de la API actualiza el reclamo y lo cierra. El equipo legal monitorea el panel de SLA y escala al gerente cuando un ticket supera los diez días sin respuesta, antes de llegar al límite legal de quince.
Limitación importante: la API estándar de un libro virtual no resuelve la conciliación con sistemas legacy mal documentados. Si el ERP del cliente es un desarrollo a medida sin endpoints REST, la integración requiere un middleware (MuleSoft, Boomi, Talend) o un ETL programado contra una base de datos intermedia. Eso suma proyecto y costo. Conviene evaluar esa complejidad antes de prometer plazos al negocio. Para una empresa con SAP, Oracle o Salesforce estándar, la integración es de días. Para una con sistemas propios, son semanas.
Preguntas frecuentes
¿Toda empresa con libro virtual necesita usar la API?
No. Para una empresa con una o dos sucursales y bajo volumen de reclamos, la interfaz web del libro virtual basta. La API se justifica cuando hay multisucursal, volumen creciente o necesidad de consolidar reclamos con otros sistemas (CRM, ERP, BI). Como regla práctica, por encima de cinco sucursales o cincuenta reclamos al mes, la API empieza a pagar su costo de integración.
¿La API de un libro virtual reemplaza al portal de Indecopi?
No. La API automatiza el manejo interno de reclamos y, en algunos casos, genera el archivo de exportación a SIREC. Pero el reporte formal al regulador sigue siendo responsabilidad de la empresa y, y depende del sector, sigue y require carga manual al portal de Indecopi o del regulador correspondiente. La API ahorra trabajo, no transfiere la obligación.
¿Qué pasa si la API del libro virtual cae durante una contingencia?
El libro virtual debe seguir disponible para el consumidor a través de su interfaz web. La caída de la API impacta la integración interna, no el cumplimiento normativo. Una arquitectura razonable contempla colas (queues) en el sistema corporativo que reintentan las llamadas cuando la API regresa. Mientras tanto, el equipo de atención puede entrar al panel del SaaS y trabajar los casos manualmente. El plazo legal de quince días sigue corriendo, así que la contingencia debe resolverse rápido.
Empieza hoy con Reclama Virtual
Reclama Virtual ofrece API REST con autenticación OAuth 2.0, endpoints para creación, listado y actualización de reclamos, webhooks por estado y exportación a SIREC. Conecta con SAP, Salesforce, HubSpot y desarrollos a medida. Cumple con la Ley 29571, el DS 011-2011-PCM, la Ley 31435 y la Ley 32495.
Escríbenos a contacto@reclamavirtual.com o visita reclamavirtual.com para acceder a la documentación técnica y agendar una sesión con nuestro equipo de ingeniería. Te entregamos un sandbox para pruebas antes del piloto.
Fuentes
- Ley 29571, Código de Protección y Defensa del Consumidor, artículos 150 a 152.
- Ley 32495 (11 de noviembre de 2025), obligaciones para proveedores con canales digitales.
- Decreto Supremo 011-2011-PCM, Reglamento del Libro de Reclamaciones, Anexos I y III.
- Decreto Supremo 058-2017-PCM, modificaciones al Reglamento del Libro de Reclamaciones.
- Decreto Supremo 101-2022-PCM, regulación del libro de reclamaciones virtual.
- Ley 31435 (22 de marzo de 2022), plazo de quince días hábiles para responder reclamos.
- Decreto Supremo 301-2025-EF, UIT 2026 fijada en S/5,500.
- Indecopi, Sistema de Reporte de Reclamos (SIREC), consumidor.indecopi.gob.pe.
