# Referidos

Cuando una persona llega a un bot a través del enlace de referido de otro contacto, se crea un vínculo entre ellos: quien invitó es el **referente**, y el invitado, el **referido**. Los vínculos forman una cadena: las personas que el contacto invitó personalmente son su primera línea, las invitadas por ellas son la segunda línea, y así sucesivamente. Para ver cómo funciona en el panel, consulta [Referidos](https://support.cleverapp.pro/es/chatbots/contacts/accounts-referrals#referidos).

Los métodos de esta página te permiten llevar un programa de referidos en tu propio sistema: otorgar bonos a lo largo de la cadena, crear informes de la red y comprobar las condiciones de una promoción.

Los tres métodos reciben un contacto por su ID, `contact_id`, y solo trabajan con contactos de tus propios bots. Los contactos de las respuestas tienen la misma estructura que en los métodos de contactos: [Campos del contacto](https://support.cleverapp.pro/es/api/contacts#campos-del-contacto).

Errores comunes a los métodos de esta página (los demás están en [Errores](https://support.cleverapp.pro/es/api#errores)):

| Código | Cuándo | Respuesta |
|---|---|---|
| `404` | Ningún contacto de tus bots tiene este `contact_id`: no existe o pertenece a otra cuenta | `{"message": "Contact not found", "errors": {"contact_id": ["Contact not found"]}}` |
| `422` | Falta `contact_id` o no es un número; `depth`, `level` o `is_flat` no son válidos | `{"message": "…", "errors": {…}}` |

Un contacto de otra cuenta y uno inexistente reciben la misma respuesta, así que la respuesta no revela si el ID existe en otra cuenta.

## getReferrers

Devuelve la cadena de referentes del contacto hacia arriba: quién lo invitó, quién invitó a esa persona, y así sucesivamente.

```endpoint
GET POST https://app.cleverapp.pro/api/v1/getReferrers
```

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `contact_id` | número | sí | ID del contacto |
| `depth` | número | no | Cuántos niveles subir: de 1 a 1000. Por defecto, 10 |
| `is_flat` | booleano | no | `true` o `1`: devolver los referentes como una lista; `false` o `0`: anidados unos dentro de otros. Lo mismo en la cadena de consulta de un `GET`: `true`, `false`, `1` o `0`. Por defecto, `false` |

```bash title="Solicitud"
curl -X POST "https://app.cleverapp.pro/api/v1/getReferrers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 4815170, "depth": 2}'
```

```json title="Respuesta 200"
{
  "data": {
    "id": 4815170,
    "bot_id": 12345,
    "phone": null,
    "email": null,
    "name": "Michael Brown",
    "address": null,
    "messenger": "telegram",
    "utm": [],
    "avatar": null,
    "telegram_id": "223456781",
    "telegram_username": null,
    "vk_user_id": null,
    "created_at": "2026-09-29T15:02:47+00:00",
    "unsubscribed_at": null,
    "referrer": {
      "id": 4815162,
      "bot_id": 12345,
      "phone": "15550100123",
      "email": null,
      "name": "Emily Johnson",
      "address": null,
      "messenger": "telegram",
      "utm": [],
      "avatar": null,
      "telegram_id": "123456789",
      "telegram_username": "emily_j",
      "vk_user_id": null,
      "created_at": "2026-09-28T07:41:12+00:00",
      "unsubscribed_at": null,
      "referrer": {
        "id": 4814901,
        "bot_id": 12345,
        "phone": null,
        "email": null,
        "name": "Sarah Miller",
        "address": null,
        "messenger": "telegram",
        "utm": [],
        "avatar": null,
        "telegram_id": "323456782",
        "telegram_username": "sarah_m",
        "vk_user_id": null,
        "created_at": "2026-09-20T11:30:05+00:00",
        "unsubscribed_at": null,
        "tags": ["partner"],
        "variables": []
      },
      "tags": [],
      "variables": []
    },
    "tags": [],
    "variables": []
  }
}
```

La respuesta contiene el propio contacto, y su campo `referrer` contiene al referente con su propio `referrer`, y así hasta `depth`. Si no hay referente, el contacto no tiene el campo `referrer`.

Con `"is_flat": true`, `data` es una lista de referentes sin el propio contacto, del más cercano al más lejano. Cada uno tiene un campo `level`: `-1` es quien invitó al contacto, `-2` es su referente, y así sucesivamente:

```json
{
  "data": [
    {
      "id": 4815162,
      "name": "Emily Johnson",
      "…": "…",
      "tags": [],
      "variables": [],
      "level": -1
    },
    {
      "id": 4814901,
      "name": "Sarah Miller",
      "…": "…",
      "tags": ["partner"],
      "variables": [],
      "level": -2
    }
  ]
}
```

Los campos del contacto en la lista son los mismos que arriba; aquí están abreviados. Sin referentes: `{"data": []}`.

## getReferrals

Devuelve la primera línea del contacto (las personas que invitó personalmente), 15 por página.

```endpoint
GET POST https://app.cleverapp.pro/api/v1/getReferrals
```

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `contact_id` | número | sí | ID del contacto |
| `filters[tag_name]` | cadena o array de cadenas | no | Solo los referidos que tienen estas etiquetas, todas a la vez. Se usan las 10 primeras etiquetas |
| `page` | número | no | Número de página, a partir de 1. Por defecto, 1 |

Solicitud de los referidos con la etiqueta «paid»:

```bash title="Solicitud"
curl -X POST "https://app.cleverapp.pro/api/v1/getReferrals" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 4815162, "filters": {"tag_name": ["paid"]}}'
```

```json title="Respuesta 200"
{
  "data": [
    {
      "id": 4815170,
      "bot_id": 12345,
      "phone": null,
      "email": null,
      "name": "Michael Brown",
      "address": null,
      "messenger": "telegram",
      "utm": [],
      "avatar": null,
      "telegram_id": "223456781",
      "telegram_username": null,
      "vk_user_id": null,
      "created_at": "2026-09-29T15:02:47+00:00",
      "unsubscribed_at": null,
      "tags": ["paid"],
      "variables": []
    }
  ],
  "links": {
    "first": "https://app.cleverapp.pro/api/v1/getReferrals?page=1",
    "last": "https://app.cleverapp.pro/api/v1/getReferrals?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": […],
    "path": "https://app.cleverapp.pro/api/v1/getReferrals",
    "per_page": 15,
    "to": 1,
    "total": 1
  }
}
```

Los referidos se ordenan por `id` ascendente. El tamaño de página no se puede cambiar. Pide las páginas siguientes con el parámetro `page` hasta que `links.next` sea `null`; envía `contact_id` y el filtro en cada solicitud: las URL de `links` no los llevan.

## getCountReferrals

Cuenta los referidos del contacto: toda la red o una sola línea.

```endpoint
GET POST https://app.cleverapp.pro/api/v1/getCountReferrals
```

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `contact_id` | número | sí | ID del contacto |
| `level` | número | no | Número de línea, a partir de 1: `1`, las personas que el contacto invitó personalmente; `2`, las invitadas por ellas, y así sucesivamente. Sin él, se cuenta toda la red |
| `filters[tag_name]` | cadena o array de cadenas | no | Solo los referidos que tienen estas etiquetas, todas a la vez. Se usan las 10 primeras etiquetas |

Cuántas personas hay en la segunda línea:

```bash title="Solicitud"
curl "https://app.cleverapp.pro/api/v1/getCountReferrals?contact_id=4815162&level=2" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

```json title="Respuesta 200"
{
  "data": {
    "count": 7
  }
}
```

Si el contacto no ha invitado a nadie, `count` es `0`.

Aquí el número está en `data.count`, mientras que [getNumberOfContacts](https://support.cleverapp.pro/es/api/contacts#getnumberofcontacts) lo devuelve en un `count` de nivel superior, sin `data`. Es así por motivos históricos y se mantiene para no romper las integraciones existentes.