Introducción
Las Cuentas Administradas son entidades de negocio subordinadas a una cuenta principal (cuenta administradora), que permiten operar, configurar y supervisar múltiples cuentas desde un único punto de control. Este modelo se basa en un esquema de permisos delegados, donde la cuenta administradora puede actuar sobre las cuentas vinculadas sin requerir credenciales independientes, garantizando al mismo tiempo:
Aislamiento de datos entre entidades
Control explícito de acceso
Trazabilidad completa de las acciones
El modelo de Cuentas Administradas permite a una entidad central operar múltiples negocios de forma segura y aislada, manteniendo independencia operativa mientras habilita administración consolidada.
Casos de Uso Comunes
Operación Logística / Flotas
Una empresa gestiona múltiples unidades operativas (conductores, vehículos, bodegas o zonas) como cuentas independientes, permitiendo ejecutar operaciones, monitorear actividad y consolidar información desde una cuenta central, mientras cada unidad mantiene su propio contexto operativo.
Gestión Multi-Cliente (Partners / Agencias)
Un aliado comercial administra múltiples cuentas de clientes desde una única plataforma, pudiendo configurar pagos, monitorear transacciones y operar de forma delegada sin acceder a credenciales individuales.
Modelos de Franquicia
Una cuenta principal gestiona múltiples puntos de venta independientes, manteniendo control central sobre configuración y operación, mientras cada sucursal conserva su propia contabilidad, balance y reglas locales.
Flujo de dinero
Las Cuentas Administradas permiten distribuir ingresos y comisiones entre múltiples entidades manteniendo balances completamente independientes. Cada operación se liquida de forma automática según las reglas definidas entre la cuenta administrada, el administrador y Trazo.
La comisión del administrador puede configurarse como valor fijo, porcentaje variable o una combinación de ambos.
La comisión se descuenta automáticamente de la cuenta administrada y se acredita al balance del administrador.
Las comisiones de Trazo se calculan sobre el valor procesado por la cuenta administrada, pero se debitan del ingreso del administrador. Si el ingreso del administrador es menor al valor de la comisión, el excedente se descuenta de su saldo disponible.
Todos los balances, movimientos y configuraciones permanecen aislados entre cuentas.
Características de la Relación
1. Independencia Operativa
Cada cuenta administrada conserva su identidad técnica y operativa de forma aislada:
Identificador único (
business_id) por entidadBalance y finanzas independientes, sin mezcla de fondos entre cuentas
Configuración local, incluyendo reglas de comisión y funcionalidades activas
Credenciales propias, como API keys y webhooks exclusivos
La relación de administración no implica compartición de recursos sensibles ni colisión de configuraciones.
2. Capacidad de Gestión Centralizada
La cuenta administradora puede operar sobre cuentas vinculadas bajo un modelo de acceso explícito y controlado:
Operación delegada segura La cuenta administradora puede ejecutar acciones en nombre de la cuenta hija utilizando un contexto de operación (
child-id), el cual es validado contra la relación existente y los permisos asignados.Visibilidad configurable El acceso a información de la cuenta hija (reportes, transacciones, configuraciones) está determinado por permisos, pudiendo ser:
Lectura parcial
Lectura completa
Acceso restringido a datos sensibles
Administración remota Posibilidad de modificar parámetros operativos de la cuenta administrada desde una consola central, sujeto a permisos de configuración.
3. Seguridad y Acceso
El acceso y operación dentro del ecosistema de cuentas administradas se controla mediante múltiples niveles:
Identidad: Validación del
x-auth-tokende la cuenta administradora.Vinculación: Verificación en tiempo real de la relación activa entre cuenta administradora y cuenta hija.
Autorización: Restricción de permisos basada en el rol del usuario administrador dentro de la jerarquía.
Uso de Integración
Paso 1: Autenticación Inicial
Obtén tu token de acceso (x-auth-token) autenticándote con tus credenciales de Cuenta Administradora. Este token será el que utilices para todas tus operaciones, tanto propias como de tus hijos.
Endpoint:
POST /api/v1/auth/loginResultado: Recibes un token que identifica tu identidad como Administrador.
Paso 2: Identificar el ID del Negocio Hijo
Debes conocer el identificador único (business_id) del negocio sobre el cual deseas operar. Puedes obtener una lista de tus cuentas vinculadas consultando tu panel de administración o el endpoint de negocios.
Paso 3: Configurar los Headers de la Petición
Para realizar una petición sobre un hijo, debes incluir dos headers obligatorios:
x-auth-token: Tu token de administrador (Paso 1).child-id: El ID del negocio hijo (Paso 2).
Ejemplo de llamada (cURL):
Paso 4: Procesamiento de la API
Cuando la API recibe estos headers, realiza lo siguiente:
Valida que el token sea vigente.
Verifica que tú (dueño del token) seas realmente el administrador de ese
child-id.Aísla la consulta: El sistema responderá como si la petición hubiera sido hecha por el hijo, devolviendo solo los saldos, transacciones o configuraciones de ese negocio específico.
El child-id no se "guarda" en la sesión. Debes enviarlo en cada una de las peticiones que quieras realizar sobre el hijo.
Paso 5: Volver al Contexto de Administrador
Si deseas realizar una operación sobre tu propia cuenta principal, simplemente realiza la petición omitiendo el header child-id.
Última actualización