> 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/webhooks/eventos-de-cuentas-administradas.md).

# Eventos de cuentas administradas

Estos webhooks permiten al administrador recibir los hitos de registro, activación y rechazo de sus cuentas administradas. Trazo envía una solicitud HTTP POST al endpoint configurado por el administrador. El tipo técnico del evento sigue siendo `business`.

## Eventos

| event.status | Cuándo se notifica                                                                                                              | detail.status                                                       |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `registered` | La cuenta administrada completó el envío de la información de su registro/KYB. No activa la cuenta ni implica aprobación.       | Estado guardado de la cuenta administrada; en el ejemplo, `review`. |
| `activated`  | La cuenta fue habilitada tras la revisión de compliance o la asunción de responsabilidad del administrador, cuando corresponda. | `active`                                                            |
| `rejected`   | Se registró una decisión de rechazo con su razón.                                                                               | `blocked`                                                           |

Precrear una cuenta administrada no significa que haya completado su registro. El evento `registered` corresponde a la finalización del envío de la información.

## Destinatario

El destinatario es el **administrador** de la cuenta administrada. Trazo usa su endpoint, sus eventos habilitados y sus credenciales. El `business_id` del payload identifica la cuenta administrada que originó el evento, no al administrador que lo recibe.

La configuración del cuenta administrada no controla esta entrega. El administrador debe tener el endpoint configurado, las credenciales correspondientes y cada evento que desee recibir habilitado. Si el administrador tiene el evento deshabilitado o no tiene endpoint, no se intenta enviar a la cuenta administrada como alternativa.

## Encabezados

Trazo envía los siguientes encabezados al endpoint del administrador:

| Encabezado              | Contenido                                 | Uso                                                   |
| ----------------------- | ----------------------------------------- | ----------------------------------------------------- |
| `Authorization`         | `Bearer {integration_key}`                | Identifica la integración del administrador.          |
| `X-Trazo-Signature`     | `timestamp={timestamp},signature={firma}` | Permite validar el origen y la integridad del cuerpo. |
| `X-Trazo-Event-Id`      | Identificador del evento                  | Es el mismo `event_id` que aparece en el cuerpo.      |
| `X-Trazo-Event-Attempt` | `1`, `2` o `3`                            | Indica el intento actual de entrega.                  |
| `Content-Type`          | `application/json`                        | Formato del cuerpo.                                   |

Si el administrador configuró un encabezado personalizado, Trazo lo envía junto con los anteriores.

## Validación de la firma

Para conocer más detalles sobre las firmas en los eventos, consulta [Validación de firma](https://docs.qentaz.com/documentation/webhooks/introduccion.md#validacion-de-la-firma).

## Estructura del payload

Los tres eventos conservan la misma estructura. Solo `rejected` agrega `detail.reason`.

| Campo                  | Tipo          | Descripción                                                                                            |
| ---------------------- | ------------- | ------------------------------------------------------------------------------------------------------ |
| `event_id`             | string        | Identificador de la entrega; se conserva entre sus reintentos.                                         |
| `event.type`           | string        | Siempre `business`.                                                                                    |
| `event.status`         | string        | Hito notificado: `registered`, `activated` o `rejected`.                                               |
| `created_at`           | string        | Fecha de generación del evento, en ISO 8601 UTC. No es la fecha de creación de la cuenta administrada. |
| `business_id`          | string        | Identificador de la cuenta administrada que originó el evento.                                         |
| `detail.business_name` | string o null | Nombre de la cuenta administrada.                                                                      |
| `detail.status`        | string o null | Estado guardado de la cuenta administrada al construir la notificación.                                |
| `detail.reason`        | string        | Razón del rechazo. Se incluye exclusivamente en `rejected`; en los otros eventos la clave se omite.    |

`event.status` y `detail.status` tienen propósitos distintos: el primero identifica el hito y el segundo informa el estado de la cuenta administrada.

Los ejemplos siguientes usan identificadores y nombres ficticios.

## Registro completado: registered

{% code overflow="wrap" %}

```json
{
  "event_id": "b62b05de-7897-40bd-b6b3-cc3ac74478b2",
  "event": {
    "type": "business",
    "status": "registered"
  },
  "created_at": "2026-10-26T17:50:55.203Z",
  "business_id": "cuenta-administrada-ejemplo",
  "detail": {
    "business_name": "Cuenta administrada de ejemplo",
    "status": "review"
  }
}
```

{% endcode %}

Este evento confirma que se completó el envío de la información; la activación se notifica después mediante `activated`.

## Cuenta administrada activada: activated

{% code overflow="wrap" %}

```json
{
  "event_id": "fa727bde-64ea-4433-829a-27ae792cad45",
  "event": {
    "type": "business",
    "status": "activated"
  },
  "created_at": "2026-10-26T18:00:00.000Z",
  "business_id": "cuenta-administrada-ejemplo",
  "detail": {
    "business_name": "Cuenta administrada de ejemplo",
    "status": "active"
  }
}
```

{% endcode %}

## Cuenta administrada rechazada: rejected

{% code overflow="wrap" %}

```json
{
  "event_id": "4f1445d3-ff3d-452d-b9af-a5cbe5dcb755",
  "event": {
    "type": "business",
    "status": "rejected"
  },
  "created_at": "2026-10-26T18:00:00.000Z",
  "business_id": "cuenta-administrada-ejemplo",
  "detail": {
    "business_name": "Cuenta administrada de ejemplo",
    "status": "blocked",
    "reason": "Los documentos aportados no coinciden con el registro"
  }
}
```

{% endcode %}

La razón debe estar registrada antes de emitir el evento. No se incluye `reason` en `registered` ni en `activated`, aunque exista un rechazo anterior en el expediente.

## Respuesta y reintentos

Responde con un código HTTP 2xx dentro de 15 segundos. Si el endpoint responde 5xx, Trazo hace hasta tres intentos en total; no reintenta ante respuestas 4xx ni timeout. El `event_id` es el mismo en los reintentos de una entrega: guárdalo para evitar procesar dos veces el mismo evento.

Para el detalle de encabezados y tiempos de reintento, consulta la [Introducción a webhooks](https://docs.qentaz.com/documentation/webhooks/introduccion.md).
