> 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 permite crear y gestionar cobros de manera flexible, adaptándose a diferentes escenarios de pago: creados, programados y normales. Los cobros pueden personalizarse con reglas de vencimiento, recargos, descuentos anticipados y notificaciones automatizadas, garantizando una integración sencilla y escalable para el comercio. **Es esencial que te asegures de generar un único cobro por cada venta, pedido o interacción con el cliente, según sea apropiado.**

## 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 | CE | NIT | PASAPORTE | DNI | EIN</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="sFwIPm2Dqll0">string</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>

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

<table><thead><tr><th width="249">Name</th><th width="113">Type<select><option value="CRQXJNwgXiB2" label="string" color="blue"></option><option value="DSyQfsQTOGwM" label="number" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><mark style="color:blue;"><code>fee_variable_saas</code></mark></td><td><span data-option="DSyQfsQTOGwM">number</span></td><td>Tarifa (fee) variable aplicada bajo el modelo SaaS para este sub-negocio específico. Se espera un número entre <code>0</code> y <code>1</code>(por defecto es <code>0</code><br><br><em><mark style="color:blue;"><code>Ejemplo: 0.1</code></mark></em></td></tr><tr><td><mark style="color:blue;"><code>fee_fixed_saas</code></mark></td><td><span data-option="DSyQfsQTOGwM">number</span></td><td>Tarifa (fee) fija aplicada bajo el modelo SaaS para este sub-negocio específico.<br><br><em><mark style="color:blue;"><code>Ejemplo: 2000</code></mark></em></td></tr></tbody></table>

### **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": [
        "\"fee_variable_saas\" must be a number"
    ]
}
```

{% 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,
  "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 %}