> 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/crear-cuenta-administrada.md).

# Crear cuenta administrada

Esta API crea una cuenta administrada asociada al negocio autenticado y permite configurar sus medios de pago y tarifas SaaS.

## Ruta

<mark style="color:green;">`POST`</mark> `/v1/business/child`

## **Encabezado**

| Name                                                   | Value            |
| ------------------------------------------------------ | ---------------- |
| `Content-Type`*<mark style="color:red;">**\***</mark>* | application/json |
| `x-auth-token`*<mark style="color:red;">**\***</mark>* | {token}          |

## **Cuerpo**

### **Datos del Negocio**

<table><thead><tr><th width="249">Name</th><th width="126">Type<select><option value="GnWreahNlF6F" label="numeric" color="blue"></option><option value="sFwIPm2Dqll0" label="string" color="blue"></option><option value="l8UgNW8hbMuc" label="date" color="blue"></option><option value="VIiuN2CCxiaY" label="boolean" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><code>business_id</code><em><mark style="color:red;"><strong>*</strong></mark></em></td><td><span data-option="sFwIPm2Dqll0">string</span></td><td>Es el identificador único que se le asignará al negocio hijo en el sistema</td></tr><tr><td><code>business_name</code><em><mark style="color:red;"><strong>*</strong></mark></em></td><td><span data-option="sFwIPm2Dqll0">string</span></td><td>Nombre comercial de la sede o del sub-negocio.</td></tr><tr><td><code>type</code><em><mark style="color:red;"><strong>*</strong></mark></em></td><td><span data-option="sFwIPm2Dqll0">string</span></td><td><p>Categoría del negocio.</p><p><mark style="color:green;"><code>general | logistic</code></mark></p></td></tr><tr><td><code>business_id_type</code><em><mark style="color:red;"><strong>*</strong></mark></em></td><td><span data-option="sFwIPm2Dqll0">string</span></td><td>Tipo de documento de identificación del negocio.<br><br><mark style="color:green;"><code>CC | NIT</code></mark></td></tr><tr><td><code>business_id_number</code><em><mark style="color:red;"><strong>*</strong></mark></em></td><td><span data-option="GnWreahNlF6F">numeric</span></td><td>Número de identificación de la empresa (NIT sin DV).</td></tr><tr><td><code>business_id_number_dv</code></td><td><span data-option="GnWreahNlF6F">numeric</span></td><td>Dígito de verificación de la empresa<br><br><em><mark style="color:blue;"><code>Ejemplo: 1</code></mark></em></td></tr><tr><td><code>business_phone</code></td><td><span data-option="sFwIPm2Dqll0">string</span></td><td>Número de celular del negocio.<br><br><em><mark style="color:blue;"><code>Ejemplo: 573112229999</code></mark></em></td></tr><tr><td><code>business_email</code></td><td><span data-option="sFwIPm2Dqll0">string</span></td><td>Correo electrónico de contacto comercial del sub-negocio.<br><br><em><mark style="color:blue;"><code>Ejemplo: alguien@ejemplo.com</code></mark></em></td></tr><tr><td><code>business_webhook</code></td><td><span data-option="sFwIPm2Dqll0">string</span></td><td>URL del webhook donde el sub-negocio recibirá los eventos de notificación.<br><br><em><mark style="color:blue;"><code>Ejemplo:https://minegocio.com/mi-aplicacion</code></mark></em></td></tr></tbody></table>

**Código de actividad económica:** `business_activity_code` es opcional. Envíalo como una cadena de exactamente cuatro dígitos, por ejemplo `"0111"`, para conservar los ceros iniciales. Se valida el formato, sin verificar el código contra un catálogo. Si se omite, se guarda como `null`. Durante la activación de compliance, la información validada puede actualizar el código.

### **Datos de Contacto (Usuario Principal)**

Están relacionados directamente con la persona que será el contacto principal de este sub-negocio:

<table><thead><tr><th width="249">Name</th><th width="113">Type<select><option value="tW4OOsURXuNZ" label="string" color="blue"></option><option value="zBWjm30t6gu5" label="number" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><mark style="color:yellow;"><code>first_name</code></mark></td><td><span data-option="tW4OOsURXuNZ">string</span></td><td>Nombre del contacto principal.</td></tr><tr><td><mark style="color:yellow;"><code>last_name</code></mark></td><td><span data-option="tW4OOsURXuNZ">string</span></td><td>Apellido del contacto principal.</td></tr><tr><td><mark style="color:yellow;"><code>nickname</code></mark></td><td><span data-option="tW4OOsURXuNZ">string</span></td><td>Apodo o nombre corto para el contacto.</td></tr><tr><td><mark style="color:yellow;"><code>phone</code></mark></td><td><span data-option="tW4OOsURXuNZ">string</span></td><td>Número de teléfono móvil del contacto principal (debe tener entre 10 y 15 dígitos numéricos).</td></tr><tr><td><mark style="color:yellow;"><code>user_email</code></mark></td><td><span data-option="tW4OOsURXuNZ">string</span></td><td>Correo electrónico válido del contacto.</td></tr><tr><td><mark style="color:yellow;"><code>user_id_type</code></mark></td><td><span data-option="tW4OOsURXuNZ">string</span></td><td>Tipo de documento de identificación del contacto principal.<br><br><mark style="color:green;"><code>CC | CE | NIT | PASAPORTE | DNI | EIN</code></mark></td></tr><tr><td><mark style="color:yellow;"><code>user_id_number</code></mark></td><td><span data-option="tW4OOsURXuNZ">string</span></td><td>Número de identificación del usuario.</td></tr><tr><td><mark style="color:yellow;"><code>user_id_number_dv</code></mark></td><td><span data-option="zBWjm30t6gu5">number</span></td><td>Dígito de verificación del documento del usuario (opcional, por defecto es <code>null</code>).</td></tr></tbody></table>

### Apariencia y Ubicación

Campos adicionales que permiten que el hijo tenga su propio estilo y ubicación geográfica separada del padre:

<table><thead><tr><th width="249">Name</th><th width="113">Type<select><option value="rRB3kMFO5APd" label="string" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><mark style="color:orange;"><code>logo</code></mark></td><td><span data-option="rRB3kMFO5APd">string</span></td><td>URL (URI válida) con la imagen del logo del sub-negocio.</td></tr><tr><td><mark style="color:orange;"><code>main_color_brand</code></mark></td><td><span data-option="rRB3kMFO5APd">string</span></td><td>Código HEX del color principal de la marca <em><mark style="color:blue;"><code>Ejemplo #FF0000</code></mark></em></td></tr><tr><td><mark style="color:orange;"><code>secondary_color_brand</code></mark></td><td><span data-option="rRB3kMFO5APd">string</span></td><td>Código HEX del color secundario de la marca.<br><em><mark style="color:blue;"><code>Ejemplo #FF0000</code></mark></em></td></tr><tr><td><mark style="color:orange;"><code>city</code></mark></td><td><span data-option="rRB3kMFO5APd">string</span></td><td>Ciudad principal de operación.</td></tr><tr><td><mark style="color:orange;"><code>state</code></mark></td><td><span data-option="rRB3kMFO5APd">string</span></td><td>Departamento o estado provincial de operación.</td></tr><tr><td><mark style="color:orange;"><code>country</code></mark></td><td><span data-option="rRB3kMFO5APd">string</span></td><td>País de operación.</td></tr></tbody></table>

### **Configuración Financiera**

La **tarifa SaaS** es la comisión que la cuenta administradora cobra a la cuenta administrada por procesar un pago. De esa comisión se descuenta la comisión de Trazo, que se calcula sobre el valor total del pago procesado.

Puedes configurar las tarifas SaaS de dos formas:

* **Global:** define un mismo valor para todos los medios de pago. Para hacerlo, envía un número:

  ```json
  {
    "fee_fixed_saas": 500,
    "fee_variable_saas": 0.02
  }
  ```
* **Individual por medio de pago:** define valores diferentes para cada medio. Para hacerlo, envía un objeto con el nombre y la tarifa de cada medio:

  ```json
  {
    "fee_fixed_saas": {
      "breb": 500,
      "card": 700
    },
    "fee_variable_saas": {
      "breb": 0.01,
      "card": 0.025
    }
  }
  ```

Puedes elegir la forma de cada campo por separado: por ejemplo, una tarifa fija individual y una tarifa variable global.

| Campo               | Descripción                                                                        |
| ------------------- | ---------------------------------------------------------------------------------- |
| `fee_fixed_saas`    | Tarifa fija. Cada valor debe ser igual o mayor a cero.                             |
| `fee_variable_saas` | Tarifa variable como decimal entre `0` y `1`. Por ejemplo, `0.02` equivale al 2 %. |

Para la configuración individual, puedes usar `breb`, `wallet`, `bank`, `card`, `card_intl`, `card_by_tz` y `cash`. El objeto debe contener al menos un medio y cada medio indicado debe estar habilitado.

Al **crear** la cuenta, un número se asigna a todos los medios habilitados. Si envías un objeto, los medios habilitados que no incluyas reciben `0` para ese campo. Si omites uno de los campos SaaS, su valor predeterminado es `0`.

#### Ejemplos de creación

Ambos ejemplos son cuerpos completos para `POST /v1/business/child`. En ellos están habilitados Bre-B, transferencia bancaria y tarjeta; billetera está deshabilitada.

{% tabs %}
{% tab title="Misma tarifa para todos" %}

```json
{
  "business_id": "PAY-CHILD-001",
  "business_name": "Tienda Centro",
  "type": "general",
  "business_id_type": "NIT",
  "business_id_number": 901234567,
  "payment_methods": {
    "breb": true,
    "bank": true,
    "card": true,
    "wallet": false
  },
  "fee_fixed_saas": 500,
  "fee_variable_saas": 0.02
}
```

Resultado: Bre-B, transferencia y tarjeta reciben cada uno una tarifa fija de `500` y una variable de `0.02` (2 %).
{% endtab %}

{% tab title="Tarifa fija por medio" %}

```json
{
  "business_id": "PAY-CHILD-002",
  "business_name": "Tienda Norte",
  "type": "general",
  "business_id_type": "NIT",
  "business_id_number": 901234568,
  "payment_methods": {
    "breb": true,
    "bank": true,
    "card": true,
    "wallet": false
  },
  "fee_fixed_saas": {
    "breb": 500,
    "card": 700
  },
  "fee_variable_saas": 0.02
}
```

| Medio                  | Tarifa fija | Tarifa variable |
| ---------------------- | ----------- | --------------- |
| Bre-B                  | 500         | 0.02 (2 %)      |
| Transferencia bancaria | 0           | 0.02 (2 %)      |
| Tarjeta                | 700         | 0.02 (2 %)      |

La tarifa fija de transferencia es `0` porque `bank` no aparece en el objeto. La tarifa variable es la misma para los tres medios porque se envió como número.
{% endtab %}
{% endtabs %}

Estas tarifas corresponden a pagos y no modifican las tarifas de dispersiones.

### **Configuración Medios de Pago**

<table><thead><tr><th width="249">Name</th><th width="113">Type<select><option value="VIiuN2CCxiaY" label="boolean" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><code>payment_methods.breb</code></td><td><span data-option="VIiuN2CCxiaY">boolean</span></td><td>Habilita los pagos mediante Bre-B.</td></tr><tr><td><code>payment_methods.wallet</code></td><td><span data-option="VIiuN2CCxiaY">boolean</span></td><td>Habilita los pagos mediante billetera digital.</td></tr><tr><td><code>payment_methods.bank</code></td><td><span data-option="VIiuN2CCxiaY">boolean</span></td><td>Habilita los pagos mediante transferencia bancaria.</td></tr><tr><td><code>payment_methods.card</code></td><td><span data-option="VIiuN2CCxiaY">boolean</span></td><td>Habilita los pagos con tarjeta nacional.</td></tr><tr><td><code>payment_methods.card_intl</code></td><td><span data-option="VIiuN2CCxiaY">boolean</span></td><td>Habilita los pagos con tarjeta internacional.</td></tr><tr><td><code>payment_methods.card_by_tz</code></td><td><span data-option="VIiuN2CCxiaY">boolean</span></td><td>Habilita los pagos con tarjeta mediante zona tarifaria.</td></tr><tr><td><code>payment_methods.cash</code></td><td><span data-option="VIiuN2CCxiaY">boolean</span></td><td>Habilita los pagos en efectivo.</td></tr></tbody></table>

### **Verificación del Negocio (KYB)**

#### **Flujo SELF: Sin objeto `compliance`**

La cuenta administrada realiza su propia vinculación.

```mermaid
flowchart TD
    A([INICIO]) --> B

    B["1. Se crea la cuenta<br/>con estado <code>PENDING_COMPLIANCE</code>."]
    B --> C["2. Se genera un <code>kyb_url</code><br/>para el onboarding."]
    C --> D["3. El administrador comparte<br/>el enlace con el comercio."]
    D --> E["4. El comercio completa la vinculación<br/>desde el enlace."]
    E --> F["5. La cuenta se activa automáticamente<br/>al completar el KYB."]
    F --> G([FIN])

    style A fill:#1b1b1b,stroke:#48CD8A,stroke-width:2px,color:#fff
    style G fill:#1b1b1b,stroke:#48CD8A,stroke-width:2px,color:#fff

    style B fill:#1b1b1b,stroke:#48CD8A,stroke-width:2px,color:#fff
    style C fill:#1b1b1b,stroke:#42A5F5,stroke-width:2px,color:#fff
    style D fill:#1b1b1b,stroke:#9C6ADE,stroke-width:2px,color:#fff
    style E fill:#1b1b1b,stroke:#FFC107,stroke-width:2px,color:#fff
    style F fill:#1b1b1b,stroke:#48CD8A,stroke-width:2px,color:#fff

    linkStyle default stroke:#ffffff,stroke-width:2px
```

El `kyb_url` contiene un token con datos del partner. Incluye logo, colores y URL de retorno. El enlace se acorta automáticamente para facilitar su distribución.

#### **Flujo PARENT: Con `compliance.type: "PARENT"`**

La cuenta padre asume la vinculación del comercio. Un aprobador registrado acepta los documentos legales desde un portal controlado por Trazo.

```mermaid
flowchart TD
    A([INICIO]) --> B

    B["1. Se crea la cuenta<br/>con estado <code>PENDING_APPROVAL</code>."]
    B --> C["2. Se busca al aprobador por<br/><code>approver_id</code> en el equipo del padre."]
    C --> D["3. Se envía un email de aprobación<br/>con el enlace."]
    D --> E["4. El aprobador acepta los documentos<br/>legales en el portal de Trazo."]
    E --> F["5. Se verifica la identidad mediante<br/>OTP."]
    F --> G["6. La cuenta se activa<br/>automáticamente tras la aprobación."]
    G --> H([FIN])

    style A fill:#1b1b1b,stroke:#48CD8A,stroke-width:2px,color:#fff
    style H fill:#1b1b1b,stroke:#48CD8A,stroke-width:2px,color:#fff

    style B fill:#1b1b1b,stroke:#48CD8A,stroke-width:2px,color:#fff
    style C fill:#1b1b1b,stroke:#42A5F5,stroke-width:2px,color:#fff
    style D fill:#1b1b1b,stroke:#9C6ADE,stroke-width:2px,color:#fff
    style E fill:#1b1b1b,stroke:#FFC107,stroke-width:2px,color:#fff
    style F fill:#1b1b1b,stroke:#42A5F5,stroke-width:2px,color:#fff
    style G fill:#1b1b1b,stroke:#48CD8A,stroke-width:2px,color:#fff

    linkStyle default stroke:#ffffff,stroke-width:2px
```

### **Configuración Aprobación de la Cuenta Administrada**

La aceptación de documentos legales no está disponible vía API. Debe realizarse desde Webviews de Trazo.

<table><thead><tr><th width="249">Name</th><th width="113">Type<select><option value="sFwIPm2Dqll0" label="string" color="blue"></option></select></th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><code>compliance.type</code></td><td><span data-option="sFwIPm2Dqll0">string</span></td><td>Sí</td><td>Tipo de compliance. Actualmente solo admite <code>PARENT</code>.</td></tr><tr><td><code>compliance.approver_id</code></td><td><span data-option="sFwIPm2Dqll0">string</span></td><td>Sí</td><td>Número de identificación del aprobador registrado en el equipo del negocio padre.</td></tr><tr><td><code>compliance.channel</code></td><td><span data-option="sFwIPm2Dqll0">string</span></td><td>Sí</td><td>Canal de envío de la solicitud. Actualmente solo admite <code>EMAIL</code>.</td></tr></tbody></table>

El objeto `compliance` es opcional. Si no se envía, se usa el flujo SELF.

#### **Email automático**

Con `compliance.type` en `PARENT`, se envía un email al aprobador.

## **Respuesta**

{% tabs %}
{% tab title="200 — SELF" %}

```json
{
  "message": "cuenta administrada creada exitosamente",
  "business_id": "PAY-CHILD-001",
  "status": "PENDING_COMPLIANCE",
  "kyb_url": "https://tz.co/abc123",
  "managing_business_id": "PAY-001",
  "created_at": "2026-07-23T13:00:00-05:00"
}
```

{% endtab %}

{% tab title="200 — PARENT" %}

```json
{
  "message": "cuenta administrada creada exitosamente",
  "id": "ma_PAY-CHILD-002",
  "business_id": "PAY-CHILD-002",
  "status": "PENDING_APPROVAL",
  "compliance_type": "PARENT",
  "approver": {
    "id": 42,
    "email": "aprobador@empresa.com",
    "name": "Carlos Gómez"
  },
  "managing_business_id": "PAY-001",
  "created_at": "2026-07-23T13:00:00-05:00"
}
```

{% endtab %}

{% tab title="200 — PARENT sin aprobador" %}

```json
{
  "message": "cuenta administrada creada exitosamente",
  "id": "ma_PAY-CHILD-002",
  "business_id": "PAY-CHILD-002",
  "status": "PENDING_APPROVAL",
  "compliance_type": "PARENT",
  "approver": null,
  "managing_business_id": "PAY-001",
  "created_at": "2026-07-23T13:00:00-05:00"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "El medio de pago card debe estar habilitado para configurar su tarifa SaaS."
}
```

{% endtab %}

{% tab title="401" %}

```bash
{
    "status": "unauthorized",
    "code": "Q103",
    "error": "El x-auth-token se encuentra vencido. Por favor genera un nuevo token y reintenta de nuevo el cobro."
}
```

{% endtab %}
{% endtabs %}

***

## Ejemplo

{% tabs %}
{% tab title="cURL" %}

#### El partner asume el compliance del comercio

```bash
curl --location '{{base_url}}/v1/business/child' \
--request POST \
--header 'Content-Type: application/json' \
--header 'x-auth-token: YOUR_SECRET_TOKEN' \
--data '{
  "business_id": "PAY-CHILD-002",
  "business_name": "Zona Sur",
  "type": "general",
  "business_id_type": "NIT",
  "business_id_number": 901234567,
  "business_activity_code": "6201",
  "phone": "573009876543",
  "first_name": "María",
  "last_name": "López",
  "nickname": "María",
  "user_id_type": "CC",
  "user_id_number": "87654321",
  "user_email": "maria@ejemplo.com",
  "business_email": "contacto@zonasur.com",
  "compliance": {
    "type": "PARENT",
    "approver_id": "12345678",
    "channel": "EMAIL"
  }
}'
```

#### Con medios de pago y branding personalizado

```bash
curl --location '{{base_url}}/v1/business/child' \
--request POST \
--header 'Content-Type: application/json' \
--header 'x-auth-token: YOUR_SECRET_TOKEN' \
--data '{
  "business_id": "PAY-CHILD-003",
  "business_name": "Café del Centro",
  "business_official_name": "Café del Centro SAS",
  "type": "general",
  "business_id_type": "NIT",
  "business_id_number": 901987654,
  "phone": "573115551234",
  "first_name": "Ana",
  "last_name": "Rodríguez",
  "nickname": "Ana",
  "user_id_type": "CC",
  "user_id_number": "55667788",
  "user_email": "ana@cafecentro.com",
  "business_email": "admin@cafecentro.com",
  "logo": "https://cdn.ejemplo.com/cafe-centro-logo.png",
  "main_color_brand": "#2D5016",
  "secondary_color_brand": "#F5E6D3",
  "city": "Bogotá",
  "state": "Bogotá D.C.",
  "country": "Colombia",
  "fee_variable_saas": 0.02,
  "fee_fixed_saas": 500,
  "payment_methods": {
    "breb": true,
    "wallet": true,
    "bank": true,
    "card": true,
    "card_intl": false,
    "card_by_tz": false,
    "cash": true
  },
  "compliance": {
    "type": "PARENT",
    "approver_id": "12345678",
    "channel": "EMAIL"
  }
}'
```

#### La cuenta administrada hace su propio KYB

```bash
curl --location '{{base_url}}/v1/business/child' \
--request POST \
--header 'Content-Type: application/json' \
--header 'x-auth-token: YOUR_SECRET_TOKEN' \
--data '{
  "business_id": "PAY-CHILD-001",
  "business_name": "Zona Norte",
  "business_official_name": "Gran Logística SAS",
  "type": "general",
  "business_id_type": "NIT",
  "business_id_number": 901234567,
  "phone": "573001234567",
  "first_name": "Juan",
  "last_name": "Pérez",
  "nickname": "Juan",
  "user_id_type": "CC",
  "user_id_number": "12345678",
  "user_email": "juan@ejemplo.com",
  "business_email": "contacto@zonanorte.com"
}'
```

{% endtab %}

{% tab title="NodeJS (Axios)" %}

```javascript
const axios = require('axios');
let data = JSON.stringify({
  "phone": "",
  "first_name": "",
  "last_name": "",
  "nickname": "",
  "user_id_type": "",
  "user_id_number": "",
  "user_email": "",
  "user_id_number_dv": null,
  "type": "general",
  "business_id": "",
  "business_name": "",
  "business_id_type": "",
  "business_id_number": 1,
  "business_id_number_dv": 1,
  "business_url": "",
  "business_phone": "",
  "business_webhook": "",
  "business_email": "",
  "logo": null,
  "main_color_brand": null,
  "secondary_color_brand": null,
  "city": null,
  "state": null,
  "country": null,
  "fee_variable_saas": 0
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: `${base_url}/v1/business/child`,
  headers: { 
    'Content-Type': 'application/json', 
    'x-auth-token': token
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import json

url = f"{base_url}/v1/business/child"

payload = json.dumps({
  "phone": "",
  "first_name": "",
  "last_name": "",
  "nickname": "",
  "user_id_type": "",
  "user_id_number": "",
  "user_email": "",
  "user_id_number_dv": None,
  "type": "general",
  "business_id": "",
  "business_name": "",
  "business_id_type": "",
  "business_id_number": 1,
  "business_id_number_dv": 1,
  "business_url": "",
  "business_phone": "",
  "business_webhook": "",
  "business_email": "",
  "logo": None,
  "main_color_brand": None,
  "secondary_color_brand": None,
  "city": None,
  "state": None,
  "country": None,
  "fee_variable_saas": 0
})
headers = {
  'Content-Type': 'application/json',
  'x-auth-token': token
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

```

{% endtab %}
{% endtabs %}
