> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yampi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Conceptos

> Cuenta, membresía, suites, Livia, Livia Desk y el mapa del dominio en la API.

El vocabulario que usa Yampi en la API de cuenta. Cuando leas un endpoint, estas piezas son el contexto.

## Cuenta

Una **cuenta** es la inmobiliaria: nombre, `slug`, estado (`active` por defecto) y configuración (locale, límites, features, calendario, Livia…). Casi todos los recursos cuelgan de `/api/v1/accounts/{account_id}/...`.

## Usuario y membresía

Un usuario puede estar en varias cuentas. La membresía es `AccountUser`:

| Campo            | Qué define                                      |
| ---------------- | ----------------------------------------------- |
| `role`           | `agent` o `administrator`                       |
| `suite_role`     | vacío (Comercial), `service` o `administrative` |
| `custom_role_id` | Rol custom de la cuenta (opcional)              |
| `availability`   | `online`, `offline` o `busy`                    |

En el perfil (`GET /api/v1/profile`) cada cuenta trae `role`, `suite_role` y `permissions`.

### Suites y permisos

| Suite          | Cómo se representa             | Qué suma                                                                                    |
| -------------- | ------------------------------ | ------------------------------------------------------------------------------------------- |
| Comercial      | `agent` con `suite_role` vacío | Alcance amplio de agente                                                                    |
| Servicio       | `suite_role: service`          | `knowledge_base_manage` (centro de ayuda). **No** implica exclusividad sobre requerimientos |
| Administrativa | `suite_role: administrative`   | `treasury_manage`, `contract_manage`, `contract_view`, `contract_sign`                      |

Un administrador recibe el permiso `administrator`.

Los **requerimientos** los puede trabajar un agente o un administrador según la policy — no son “de la suite Servicio”.

`suite_role` y `custom_role` **no se combinan**: la membresía no admite los dos a la vez.

## Token de acceso

Cada usuario (y cada bot) tiene un `AccessToken`. Lo envías en `api_access_token`. Detalle en [Empezar aquí](/guides/empezar-aqui).

## Livia y Livia Desk

Son dos superficies distintas:

* **Livia** — asistentes en bandejas; hablan con el cliente ([guía](/guides/livia)).
* **Livia Desk** — copiloto interno del agente (`copilot_threads` / `copilot_messages`); propone y el humano confirma ([guía](/guides/livia-desk)).

El detalle HTTP está en la pestaña **API**.

## Mapa del dominio

| Dominio                    | Cómo lo verás en la API                                                                        |
| -------------------------- | ---------------------------------------------------------------------------------------------- |
| Propiedades                | `properties`                                                                                   |
| Contactos y empresas       | `contacts`, `companies`                                                                        |
| Conversaciones y bandejas  | `conversations`, `inboxes`                                                                     |
| Negocios                   | `opportunities` y pipelines                                                                    |
| Requerimientos             | `requirements` (y quotes anidados)                                                             |
| Contratos y documentos     | plantillas, submissions, biblioteca                                                            |
| Tesorería / arrendamientos | `treasury/...`                                                                                 |
| Calendario                 | `calendar/...`                                                                                 |
| Centro de ayuda            | `portals` en `/api/v1/accounts/.../portals` — no es el portal de arriendo ni el de propietario |
| MCP de cuenta              | `POST .../mcp` (feature `mcp_server`)                                                          |

La identidad del firmante (IdentidApp) no es un recurso account-scoped de esta API: el flujo público está en `/s/{slug}/identity`.

<Info>
  El catálogo HTTP (método, path, body, respuestas) está en la pestaña **API**. Aquí solo fijamos el modelo.
</Info>