Autenticación y separación entre clientes
Los endpoints de lectura del panel requieren la cookie de sesión HttpOnly del usuario conectado. Los propietarios con correo verificado pueden emitir tokens de portador de solo lectura vinculados a un proyecto, que se muestran una sola vez y se almacenan como hashes, con una caducidad máxima de 90 días. read:reports permite summary/trend/search; read:journeys permite además leer eventos sin procesar y recorridos. Los tokens nunca autorizan acceso a la cuenta ni modificaciones. Los propietarios pueden modificar sus propios proyectos; los Viewers verificados y aceptados pueden leer proyectos compartidos, pero no cambiar ajustes, facturación ni conexiones. Los identificadores de proyecto y del rastreador público sirven para dirigir solicitudes, no para autenticar. No copies una sesión del navegador en código cliente público.
Las escrituras de la API requieren JSON y comprobaciones de mismo origen. Los orígenes exactos permitidos del sitio se aplican a la recogida pública. Las cookies son Secure en producción. Una sesión ausente devuelve 401; los proyectos inaccesibles, 404. Los controles de consulta no válidos devuelven 400.
Política de navegación automática
startPageviews({mode, routes, initial}) activa explícitamente la automatización de vistas de página con correspondencias configuradas. mode es history (predeterminado) o hash; routes es un objeto obligatorio de entre 1 y 50 rutas seguras exactas o prefijos terminados en /*, asociados a etiquetas estáticas seguras de páginas. initial es true por defecto. stopPageviews() detiene únicamente la automatización de navegación; consent(false) detiene toda recogida y borra el seudónimo almacenado.
pushState/replaceState y popstate del historial solo se observan mientras existe consentimiento. El modo hash también gestiona cambios #/route. Las cadenas de consulta se ignoran para identificar páginas; los fragmentos normales del historial no se convierten en páginas. Repetir una configuración equivalente o recibir señales de navegación duplicadas no añade eventos. track(pageview) manual es independiente, por lo que no debes combinarlo con vistas automáticas para una misma visita.
GPC=true bloquea las concesiones de consentimiento, las vistas de página, los eventos con nombre y el acceso al identificador de visitante. Una señal GPC observada por primera vez retira el seguimiento activo y cancela solicitudes pendientes cuando es posible. Desactivar GPC no restablece silenciosamente el consentimiento. Es un comportamiento de la implementación, no una afirmación de cumplimiento legal universal.
Recogida en el navegador con consentimiento
El rastreador nunca concede consentimiento automáticamente. Conecta la concesión y la retirada a tu gestor de consentimiento. Page es una etiqueta explícita de ruta no personal; no se recoge la URL completa, la consulta de búsqueda ni el fragmento. No incluyas nombres, identificadores de cuenta ni tokens en etiquetas de ruta. Referrer, si se proporciona, debe ser un nombre de host; device es una categoría declarada general opcional, no una huella digital. No se infiere el país a partir de datos del navegador.
reylin.consent(true); // only after the visitor permits it
await reylin.track('pageview', {page:'/pricing', device:'desktop'});
await reylin.track('signup', {page:'/signup'});
// On withdrawal:
reylin.consent(false);Resumen y embudo ordenado
GET /api/projects/:id/summary acepta days (1–366), currency (código ISO en mayúsculas), source, steps (nombres separados por comas) y conversionHours (1, 24 o 168). Los días terminan en la hora UTC actual. Usa page:/pricing para vistas de páginas declaradas exactas o page:/docs/* para un prefijo seguro de ruta declarada, combinados con objetivos con nombre y un $payment final. Un embudo exige marcas de tiempo estrictamente ordenadas; cualquier entrada válida puede iniciar un recorrido y cada visitante seudónimo se cuenta una vez. Source se aplica a la entrada. La falta de consentimiento o de vínculo del visitante no puede crear una conversión de pago.
El paso final reservado $payment solo lee pagos completados del registro financiero. Un evento del navegador llamado purchase o payment nunca es una prueba financiera. Los reembolsos no borran las conversiones de pagos completados. Los totales de ingresos usan unidades menores enteras del proveedor; las monedas nunca se mezclan ni se convierten implícitamente.
Consultas por dimensiones y paginación
GET /api/projects/:id/events acepta marcas de tiempo ISO from/to (intervalo máximo de 366 días), limit (1–1000), cursor, groupBy y filters como JSON codificado para URL. Dimensiones: source, type, page, referrer, country, device. Los valores ausentes son Unknown, no se adivinan. Operadores: is, is_not, contains, not_contains. Se combinan hasta diez filtros con AND; la comparación contains no distingue mayúsculas y minúsculas.
Omite groupBy para obtener eventos individuales en orden cronológico; indícalo para recuentos de eventos y visitantes distintos. Las respuestas incluyen los límites normalizados from/to y nextCursor. Reutiliza exactamente esos límites y filtros en las solicitudes posteriores, ya que mover la hora final cambia la consulta. Los cursores están vinculados a la consulta, no son credenciales de acceso.
const query = new URLSearchParams({
from:'2026-10-01T00:00:00Z', to:'2026-10-31T23:59:59Z',
groupBy:'page', limit:'100',
filters:JSON.stringify([{dimension:'source',operator:'contains',value:'Google'}])
});
const response = await fetch('/api/projects/PROJECT_ID/events?' + query);Recorridos seudónimos de visitantes
GET /api/projects/:id/journey acepta visitorId, from/to, limit y cursor. Devuelve hechos de eventos consentidos, pagos completados vinculados y estados de reembolsos de esos pagos en orden cronológico. No determina una persona, un correo, un grafo de dispositivos ni una identidad entre sitios. Un visitante ausente devuelve un recorrido vacío en lugar de un historial inventado. Los importes de reembolso se mantienen separados por moneda y los estados siguen visibles.
Semántica de conexión e importación del proveedor
La analítica de clientes de Stripe y tu suscripción a Reylin son ámbitos de confianza separados. La incorporación de la conexión verifica la cuenta del proveedor, crea un borrador con un endpoint de webhook estable y después activa el secreto de firma cifrado. Las firmas validan los bytes originales de la entrega; el dinero se concilia a partir del objeto actual del proveedor y se deduplica.
La importación histórica limitada de pagos de 7 o 30 días no reconstruye visitantes históricos, todos los reembolsos ni disputas. Los avisos de cobertura permanecen visibles. Los ingresos de un proveedor desconectado no están disponibles; un recuento de pagos almacenados de cero no demuestra que no haya ventas reales. La prueba de aceptación con el proveedor real sigue siendo un requisito previo del despliegue.
Los datos de búsqueda no son ingresos
La integración de Search Console proporciona informes de búsqueda de solo lectura autorizados por separado. Clics, impresiones, CTR y posición son métricas de búsqueda de Google, no pagos ni visitantes únicos del sitio. Los límites de fechas de Google usan la hora del Pacífico, a diferencia de la ventana UTC de los informes de eventos. Los resultados de la API pueden omitir filas y devolver las principales; una paginación limitada nunca demuestra una exportación exhaustiva. La provisión de OAuth y la autorización de una cuenta real requieren una integración configurada por separado.
Configuración guardada e informes por calendario
GET y POST /api/projects/:id/config/:kind admiten segment, funnel, goal, note y preferences. Las actualizaciones usan /:id y los borrados usan POST {action: delete}. Solo los propietarios modifican datos. Las notas son exclusivas del propietario; los Viewers compartidos pueden leer las demás definiciones guardadas. Las claves de eventos de objetivos no pueden cambiar; las etiquetas visibles nunca reescriben el historial de eventos. Las preferencias se guardan explícitamente y se aplican al informe actual cuando se solicita.
GET /api/projects/:id/trend acepta from, to, timezone, bucket hour/day/week/month, currency y compare=true. Su intervalo semiabierto [from,to) evita contar dos veces los límites. Las agrupaciones siguen los límites reales del calendario local, incluidos los cambios de horario de verano; las semanas empiezan el lunes. La comparación con el periodo anterior tiene igual duración transcurrida, y una base cero devuelve null como variación porcentual.
Suscripciones de clientes y contratos recurrentes
La analítica de clientes puede conciliar eventos customer.subscription.created, customer.subscription.updated y customer.subscription.deleted. De los eventos firmados desencadenantes solo se conservan los identificadores de suscripción; el estado actual de la suscripción se obtiene de la cuenta verificada correspondiente. Las instantáneas de suscripciones nunca crean entradas de cobros en el registro financiero.
GET /api/projects/:id/subscriptions devuelve importes recurrentes mensuales brutos contratados, separados por moneda, antes de descuentos e impuestos. Solo se admiten conceptos recurrentes de licencia fija: las instantáneas pausadas, por consumo, escalonadas, transformadas, desconocidas u obsoletas se excluyen con avisos de cobertura. Los equivalentes de prueba se separan del MRR activo. La agregación racional exacta se redondea una vez por moneda, con los empates hacia arriba. La normalización mes/año/semana/día se informa explícitamente.
Las suscripciones conocidas se actualizan en lotes limitados en segundo plano. Las lecturas fallidas excluyen inmediatamente esa suscripción; las instantáneas de más de 24 horas no se presentan como actuales. Los propietarios pueden iniciar una búsqueda reanudable en Recurring contracts. Su finalización significa que se paginaron las suscripciones actuales disponibles, no que se reconstruyeron todos los ciclos de vida históricos o registros cambiantes del proveedor. La búsqueda requiere permiso de lectura para listar y recuperar suscripciones.
Objetivos declarativos y colas seguras
Después del consentimiento explícito, data-reylin-event en un elemento pulsable envía un objetivo con nombre por clic. data-reylin-view-event envía una sola vez cuando al menos la mitad del elemento es visible por cada concesión de consentimiento. El atributo opcional data-reylin-page proporciona una etiqueta de ruta segura explícita. Nunca se extraen valores de formularios, destinos de enlaces ni texto del DOM. La retirada desconecta los observadores y cancela solicitudes pendientes cuando se admite.
Las entradas de cola anteriores a la carga y las de consentimiento denegado se descartan, no se reproducen después. Tras la carga, reylinQueue.push([track, eventName, dimensions]) solo envía mientras el consentimiento actual es true. No se añade ninguna vista de página ni consentimiento automáticos.
Sesiones observadas y búsqueda privada de visitantes
GET /api/projects/:id/session-metrics informa sobre una cohorte de entradas de sesión dentro de [from,to). Las sesiones agrupan eventos consentidos por identificador seudónimo del navegador y una separación estrictamente superior a 30 minutos. El historial previo almacenado evita crear una sesión nueva artificial solo porque empiece una ventana de informe; la conservación y el borrado aún pueden eliminar pruebas de continuidad.
Un rebote es una sesión cerrada por inactividad con exactamente una vista de página y ningún evento de otro tipo. Las sesiones abiertas quedan fuera del denominador del rebote. La duración media observada es la diferencia entre el primer y el último evento registrados, no el tiempo en el sitio ni una estimación de atención. La primera vista de página observada y la última etiqueta de página observada no prueban el comportamiento real de entrada y salida. Los datos ausentes son Unknown, no geolocalización ni un perfil de navegador inventado.
GET /api/projects/:id/visitors es privado y requiere una sesión con acceso al proyecto, un Viewer o un token read:journeys. Admite source, eventType, customerStatus all/paid/unpaid, búsqueda por identificador, limit y cursor vinculado a la consulta. Los filtros de fuente y tipo de evento deben coincidir en el mismo evento observado. Los recuentos describen los eventos observados de ese visitante en la ventana elegida. Paid significa pagos vinculados del registro financiero en esa misma ventana; los eventos purchase del navegador no lo demuestran. Los recuentos de pagos se separan por moneda.
Las métricas agregadas de sesión permiten tokens read:reports y nunca incluyen identificadores individuales de visitantes. Las filas de visitantes son observaciones seudónimas, no personas verificadas, correos, coincidencias de identidad ni perfiles de CRM.
Dimensiones de adquisición e ingresos fijados
Las dimensiones explícitas de eventos pueden incluir campaign, medium, content y term como identificadores cortos no personales en minúsculas de hasta 64 caracteres, hostname como nombre de host DNS y categorías generales de navegador y sistema operativo. Son etiquetas declaradas: Reylin no las infiere de una huella digital ni captura automáticamente consultas de búsqueda sin procesar. Las dimensiones ausentes siguen siendo Unknown. Los campos existentes page, referrer y device siguen admitidos.
Los nuevos registros de pagos verificados fijan la instantánea de dimensiones del primer contacto consentido dentro de la ventana de atribución configurada. Un evento posterior, el borrado del historial de eventos o un cambio de metadatos del proveedor no pueden reescribirla. Los pagos antiguos sin instantánea de dimensiones siguen siendo Unknown para esa dimensión; no se inventa atribución histórica.
GET /api/projects/:id/acquisition acepta dimension, metric, from, to y currency. Es una lectura agregada para sesiones y Viewers del proyecto y tokens read:reports. El informe usa una cohorte de pagos: pagos dentro del intervalo semiabierto y sus reembolsos completados elegibles anteriores al final del intervalo, limitados por pago. No es un informe de movimientos de caja por reembolsos. El dinero se mantiene separado por moneda. La conversión requiere un visitante consentido observado en el mismo grupo de dimensión y ventana; las proporciones con denominador cero no están disponibles, no se inventan ceros.
Los informes devuelven un máximo de 100 grupos ordenados más recuentos y totales explícitos de grupos omitidos. Los visitantes pueden aparecer en varios grupos de dimensiones, por lo que la suma de visitantes de los grupos no tiene por qué coincidir con los visitantes únicos globales. Los segmentos guardados de consultas de eventos admiten las mismas dimensiones declaradas de adquisición y plataforma.
Propiedades categóricas de objetivos
Los propietarios primero declaran esquemas solo de enum en Goal properties, por ejemplo signup → plan → starter o growth. Las claves de esquemas de eventos y propiedades usan snake case en minúsculas de hasta 32 caracteres; se permiten como máximo 20 esquemas de eventos, 8 propiedades por esquema y 20 valores por propiedad. Las etiquetas son identificadores cortos en minúsculas, nunca identificadores personales ni secretos. Pertenecer a un enum no demuestra anonimato: el propietario del proyecto es responsable de que las etiquetas no sean personales. Las claves o valores desconocidos se rechazan antes de guardarlos y consumir cupo.
Envía las propiedades como tercer argumento del rastreador, por ejemplo reylin.track("signup", {page:"/pricing"}, {plan:"starter"}). Se requiere consentimiento. No se recogen automáticamente texto del DOM ni valores de formularios. El servidor valida con el esquema actual de ese proyecto. Los cambios de esquema afectan a eventos futuros, no a registros históricos.
GET /api/projects/:id/goal-properties acepta eventType, property, from y to (intervalo UTC semiabierto). Las categorías configuradas y un grupo distinto para valores ausentes contienen recuentos de eventos y visitantes únicos, nunca identificadores de visitantes. Las categorías históricas eliminadas cuentan como excludedEvents/excludedVisitors sin devolver sus etiquetas eliminadas. Los propietarios, Viewers y tokens read:reports pueden leer este agregado; solo los propietarios pueden ejecutar GET/POST /property-schemas. Las propiedades sin procesar siguen formando parte de las lecturas de eventos con alcance de recorridos.
Trabajos de limpieza de visitantes del propietario
GET /api/projects/:id/visitor-erasure lista los estados depurados de los trabajos de ese propietario; añade el identificador del trabajo para obtener un estado. POST a la colección inicia un trabajo con visitorId, un requestId aleatorio estable y retainFinancialRecords:true. El seudónimo original del visitante debe ir en el cuerpo JSON, nunca en una URL. Solo se permiten sesiones de propietarios verificados; los Viewers y los tokens de portador de API no pueden iniciar ni inspeccionar estos trabajos.
El mismo identificador de solicitud y destino es idempotente; un destino conflictivo se rechaza. El estado público omite hashes de supresión y tokens de procesos de trabajo. La finalización preserva el dinero y la atribución fijada mientras desvincula el seudónimo conocido; no garantiza borrado legal, físico ni del lado del proveedor. Lee la guía del ciclo de vida de los datos y la aceptación de datos conservados antes de usarlo.
La recogida y las escrituras financieras se pausan para el proyecto afectado mientras se ejecutan barreras locales de transacción y lotes reanudables. Los trabajos que esperan envíos inciertos permanecen visiblemente pendientes. La conservación manual y el borrado de proyectos o cuentas no pueden competir con una limpieza activa. Los límites de alcance incluyen registros de recepción antiguos sin índice, notas o etiquetas de usuarios, copias externas y copias de seguridad.
Inventario de exportación de datos del propietario
GET /api/account/data-export devuelve las secciones locales admitidas, los campos seleccionados, la disponibilidad y las exclusiones. Añade section, el projectId opcional de un proyecto del propietario, limit (1–100) y cursor para leer una página. El servidor determina el propietario a partir de la sesión autenticada, nunca de un identificador de propietario proporcionado. Los roles Viewer y los tokens de API de solo lectura no autorizan esta ruta de cuenta.
El cursor está vinculado a sección, propietario y proyecto. Las filas se seleccionan mediante SQL estático y listas permitidas de campos JSON; no existe un parámetro arbitrario de base de datos, tabla, ruta o columna. El almacenamiento ausente o con esquema incompatible devuelve cobertura explícitamente no disponible. Se omiten hashes de credenciales, textos cifrados, tokens originales y detalles internos de procesos de trabajo. El resultado no es una instantánea atómica ni una afirmación de exhaustividad universal.
Informes y alertas del propietario
Los propietarios de proyectos pueden activar un informe semanal con día de la semana, hora UTC y moneda explícitos, o alertas de eventos con nombre. Los mensajes se envían solo al correo verificado de la cuenta; no existe un campo de destinatario arbitrario. Las nuevas alertas de objetivos empiezan desde el punto de control de recepción del servidor, por lo que activar una regla nunca reproduce eventos anteriores. Un evento tardío puede generar una alerta si llega después de activar la regla. Los objetivos del navegador no prueban ingresos.
La entrega está desactivada de forma independiente por defecto. Las reglas de simulación pueden poner informes en cola, pero no envían correos. Un mensaje aceptado significa que el proveedor de correo lo aceptó, no que llegó a la bandeja de entrada. Los límites de cola pendiente y de entrega diaria del propietario suprimen las notificaciones excedentes; no se generan cargos por exceso. Disable all en Reports & alerts cancela los mensajes en cola. Los mensajes aceptados previamente no pueden retirarse.
Solo las sesiones del propietario pueden acceder a /api/projects/:id/notifications. Los tokens de portador de solo lectura y los Viewers no pueden configurar informes ni leer la cola privada. Las acciones POST son weekly, goal, remove_goal y unsubscribe.
Enlaces públicos de agregados y widgets
Los propietarios crean explícitamente un recurso compartido en los ajustes Sharing del proyecto. Cualquier persona con su URL de portador puede leer únicamente agregados de visitantes, eventos, pagos, cobros brutos, reembolsados y netos, moneda y periodo. No se incluyen fuentes, visitantes individuales, notas ni registros subyacentes. Los enlaces y widgets insertados no se publican automáticamente. La rotación o revocación invalida inmediatamente la URL anterior, pero no puede borrar copias que alguien ya haya visto.
La página compartida y la inserción son noindex y usan cabeceras no-referrer/no-store. El widget está diseñado para permitir su inclusión en un marco solo después de que un propietario cree ese acceso. Las rutas privadas del panel siguen sin permitir marcos. Un recuento agregado cero del registro financiero no demuestra que un negocio real desconectado no haya tenido ventas.
SDK y CLI de solo lectura
reylin-client.mjs es un SDK del lado del servidor sin dependencias que expone summary/events/journey/trend/search. reylin-cli.mjs expone las mismas operaciones de lectura e imprime JSON. Configura REYLIN_API_TOKEN en el entorno, nunca en argumentos de línea de comandos ni paquetes del navegador. Los tokens no pueden modificar facturación, ajustes de proveedores ni cuentas de usuarios. Estas herramientas de código fuente son locales; no se ha publicado ningún paquete en el registro npm ni conexión MCP de terceros.
node reylin-cli.mjs summary --origin https://YOUR_APPROVED_HOST --project PROJECT_ID --days 30 --currency USDErrores y tratamiento de datos
Nunca reintentes una acción con coste usando una nueva clave de idempotencia solo porque se haya perdido su respuesta. No incluyas secretos en cadenas de consulta, eventos personalizados ni capturas de soporte. Las exportaciones y los recorridos seudónimos son datos de proyecto autenticados; restringe su acceso y respeta las políticas de conservación y borrado. No hay una API pública de lectura de analítica sin autenticación.
Referencias
Esta documentación describe el código y sus límites; no confirma una conexión activa. Los ejemplos técnicos mantienen sus identificadores originales.