> For the complete documentation index, see [llms.txt](https://docs.qentaz.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qentaz.com/documentation/cuentas-administradas/introduccion.md).

# 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

```mermaid
flowchart LR

    %% ===== ESTILOS =====
    classDef admin fill:#FFFFFF,stroke:#00D084,color:#123C46,stroke-width:2px;
    classDef regional fill:#123C46,stroke:#123C46,color:#FFFFFF,stroke-width:1px;

    %% ===== NODO CENTRAL =====
    A[ADMINISTRADOR]

    %% ===== CUENTAS =====
    B[Regional Bogotá<br/><font size="2">Cuenta administrada</font>]
    C[Regional Antioquia<br/><font size="2">Cuenta administrada</font>]
    D[Regional Costa<br/><font size="2">Cuenta administrada</font>]
    E[Regional Eje Cafetero<br/><font size="2">Cuenta administrada</font>]

    %% ===== RELACIONES =====
    A --> B
    A --> C
    A --> D
    A --> E

    %% ===== ESTILOS =====
    class A admin;
    class B,C,D,E regional;
```

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 <a href="#user-content-casos-de-uso-comunes" id="user-content-casos-de-uso-comunes"></a>

<table><thead><tr><th width="249.640625">Caso de Uso</th><th>Descripción</th></tr></thead><tbody><tr><td><strong>Operación Logística / Flotas</strong></td><td>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.</td></tr><tr><td><strong>Gestión Multi-Cliente</strong> <br><strong>(Partners / Agencias)</strong></td><td>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.</td></tr><tr><td><strong>Modelos de Franquicia</strong></td><td>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.</td></tr></tbody></table>

***

### Flujo de dinero <a href="#user-content-caracteristicas-de-la-relacion" id="user-content-caracteristicas-de-la-relacion"></a>

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.

<figure><img src="/files/tuozxQLZ9kh2gjpn0dUy" alt=""><figcaption></figcaption></figure>

* 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 <a href="#user-content-caracteristicas-de-la-relacion" id="user-content-caracteristicas-de-la-relacion"></a>

**1. Independencia Operativa**

Cada cuenta administrada conserva su identidad técnica y operativa de forma aislada:

* **Identificador único** (`business_id`) por entidad
* **Balance 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:

1. **Identidad:** Validación del `x-auth-token` de la cuenta administradora.
2. **Vinculación:** Verificación en tiempo real de la relación activa entre cuenta administradora y cuenta hija.
3. **Autorización:** Restricción de permisos basada en el rol del usuario administrador dentro de la jerarquía.

***

### Uso de Integración <a href="#user-content-paso-1-autenticacion-inicial" id="user-content-paso-1-autenticacion-inicial"></a>

**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/login`
* **Resultado:** 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**:

1. `x-auth-token`: Tu token de administrador (Paso 1).
2. `child-id`: El ID del negocio hijo (Paso 2).

**Ejemplo de llamada (cURL):**

```hurl
curl -X GET "https://api.trazo.com/api/v1/transactions" \
     -H "x-auth-token: TU_TOKEN_DE_ADMINISTRADOR" \
     -H "child-id: ID_DEL_NEGOCIO_HIJO"
```

**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.

{% hint style="warning" %}
El `child-id` no se "guarda" en la sesión. Debes enviarlo en **cada una** de las peticiones que quieras realizar sobre el hijo.
{% endhint %}

**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`.

```hurl
curl -X GET "https://api.trazo.com/api/v1/transactions" \
     -H "x-auth-token: TU_TOKEN_DE_ADMINISTRADOR"
```

{% hint style="info" %}
Nunca pidas un token usando las llaves del hijo si eres el administrador, usa siempre tu propio token para mantener la trazabilidad de quién realizó la acción.
{% endhint %}