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

# Introducción a la API

> Autentícate con la API REST y empieza a desarrollar

La API REST de Famulor te permite gestionar los mismos recursos de cliente disponibles en el panel, incluidos asistentes, llamadas, campañas, transcripciones, conocimiento y configuración del espacio de trabajo.

<Tip>
  Para un proceso de negocio de varios pasos — enriquecer un lead, luego llamar, luego actualizar un CRM, luego avisar en un canal — una [automatización](/es/automations/overview) suele requerir menos código de mantenimiento que conectar los pasos tú mismo. Recurre directamente a la API cuando necesites un control programático simple e inmediato, como disparar una única llamada desde tu propia app.
</Tip>

## URL base

```text theme={null}
https://app.famulor.io/api/v1
```

Si usas un dominio de marca blanca, sustituye `app.famulor.io` por ese dominio. Las rutas son las mismas.

## Acceso a la API

Las solicitudes REST requieren **API Access** mediante el plan del espacio de trabajo o un complemento recurrente. Si se retira el acceso, las claves de API y credenciales OAuth existentes siguen disponibles para que los administradores del espacio las revisen y revoquen, pero las solicitudes normales a `/api/v1` devuelven `403 api_access_required`.

Después de un pago de plan fallido, `POST /api/v1/billing/invoice-payment` y `POST /api/v1/billing/portal` siguen disponibles con una credencial válida para que un propietario pueda recuperar la facturación. Las comprobaciones de autenticación, rol y alcance siguen aplicándose.

## Autenticación

Envía un token Bearer en el encabezado `Authorization`:

```bash theme={null}
curl https://app.famulor.io/api/v1/assistants \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX"
```

Se admiten dos tipos de credencial:

* **Workspace API keys** (`fam_...`) — créalas en **Settings → API & MCP** para integraciones de servidor a servidor. La clave completa se muestra una sola vez. El panel no tiene selector de alcances, así que una clave creada ahí siempre lleva todos los alcances. Para generar una clave más restringida, llama a `POST /api/v1/api-keys` o `POST /api/v1/workspaces/{workspace_id}/api-keys` con un array `scopes` explícito — los alcances de la nueva clave deben ser un subconjunto de los de la credencial que la crea.
* **OAuth 2.0 access tokens** (`fam_at_...`) — usa Authorization Code con PKCE-S256 para aplicaciones que actúan en nombre de un usuario con sesión iniciada.

El acceso autorizado por un usuario sigue su pertenencia y su rol actuales en el espacio de trabajo. Las claves de API del espacio de trabajo siguen su propio estado y alcances hasta que un administrador autorizado del espacio las revoque.

<Warning>
  Trata las claves de API como contraseñas. Nunca las incluyas en código de navegador o de aplicaciones móviles; usa OAuth para aplicaciones orientadas al usuario final.
</Warning>

### Higiene de las claves

* Guarda las claves en variables de entorno o en un gestor de secretos, nunca en el control de versiones.
* Limita el alcance de cada clave a lo que necesite la integración — una clave que solo lee llamadas no debería tener también `assistants:write`. Las claves creadas desde el panel siempre tienen acceso completo; usa el método de la API anterior para generar una con alcance limitado.
* Rota las claves periódicamente, y de inmediato cuando alguien con acceso a una deje el equipo.
* Revocar una clave desde **Settings → API & MCP** tiene efecto inmediato; las solicitudes ya en curso pueden completarse igualmente.

### Requisitos de clientes OAuth

Un cliente construido a mano interactúa directamente con los endpoints de autorización y de token:

```text theme={null}
https://app.famulor.io/api/oauth/authorize
https://app.famulor.io/api/oauth/token
```

Usa URL de redirección HTTPS. Las aplicaciones nativas también pueden usar direcciones HTTP de loopback literales como `127.0.0.1`. Las solicitudes de autorización OAuth deben usar PKCE-S256 y pedir solo los alcances registrados para el cliente. Cuando una solicitud se limite por frecuencia, reinténtala tras el retraso indicado en la respuesta.

El cliente usa credenciales preaprobadas para tu espacio de trabajo, o se registra a sí mismo de forma dinámica con `POST /api/oauth/register` — indica entre 1 y 10 `redirect_uris` únicos. Los endpoints, los alcances admitidos y los tipos de concesión se pueden consultar en `/.well-known/oauth-authorization-server`.

Los tokens de acceso se renuevan con la concesión `refresh_token`. Los tokens de actualización rotan en cada uso: solicitar un nuevo token de acceso también emite un nuevo token de actualización e invalida de inmediato el que enviaste.

## Formato de respuesta

Las respuestas correctas envuelven el resultado en `data` y pueden incluir `meta`:

```json theme={null}
{
  "data": [{ "id": "…", "name": "Support Agent" }],
  "meta": { "pagination": { "limit": 50, "offset": 0, "total": 1 } }
}
```

Las respuestas contienen únicamente datos del espacio de trabajo orientados al cliente. Los secretos nunca se devuelven después de guardarse, y los valores sensibles se enmascaran cuando resulta útil. Las grabaciones se entregan mediante enlaces temporales. El uso y la facturación se reportan en los minutos y créditos que aparecen en tu cuenta.

## Paginación

Los endpoints de lista usan `limit` y `offset`:

| Parámetro | Predeterminado | Máximo | Descripción                    |
| --------- | -------------- | ------ | ------------------------------ |
| `limit`   | `50`           | `200`  | Número de elementos a devolver |
| `offset`  | `0`            | —      | Número de elementos a omitir   |

Usa `meta.pagination.total` para saber si hay más páginas disponibles.

## Errores

Los fallos devuelven un código estable y un mensaje legible:

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "A destination phone number is required."
  }
}
```

| Estado | Código                | Significado                                                     |
| ------ | --------------------- | --------------------------------------------------------------- |
| `400`  | `invalid_request`     | Cuerpo o parámetros de la solicitud no válidos                  |
| `401`  | `unauthorized`        | Credencial ausente, no válida, caducada o revocada              |
| `403`  | `forbidden`           | El alcance, el rol o el plan no permiten la acción              |
| `403`  | `api_access_required` | API Access no está disponible para este espacio de trabajo      |
| `404`  | `not_found`           | Recurso no encontrado o no visible para este espacio de trabajo |
| `409`  | `conflict`            | El recurso está en un estado conflictivo                        |
| `429`  | `rate_limited`        | Demasiadas solicitudes; espera y vuelve a intentarlo            |
| `500`  | `internal_error`      | Error inesperado                                                |

## Gestión de clientes de marca blanca

Los revendedores autorizados pueden usar los endpoints `platform` para gestionar a sus propios clientes finales, emitir y revocar tokens de API de clientes, transferir créditos y gestionar su dominio personalizado. Estos endpoints requieren los alcances `platform:read` o `platform:write`; las operaciones de dominio personalizado usan el alcance de configuración correspondiente.

| Endpoint                                        | Finalidad                                                              |
| ----------------------------------------------- | ---------------------------------------------------------------------- |
| `GET /api/v1/platform/users`                    | Listar tus clientes finales                                            |
| `POST /api/v1/platform/users`                   | Registrar un cliente final                                             |
| `GET /api/v1/platform/users/{user_id}`          | Leer el resumen de cuenta de un cliente final                          |
| `POST /api/v1/platform/users/{user_id}/token`   | Emitir un token de API para ese cliente                                |
| `POST /api/v1/platform/users/login`             | Autenticar a un cliente                                                |
| `POST /api/v1/platform/users/{user_id}/logout`  | Revocar los tokens de API de ese cliente                               |
| `POST /api/v1/platform/users/{user_id}/balance` | Transferir créditos entre tu saldo de revendedor y el cliente          |
| `GET /api/v1/custom-domain`                     | Consultar el estado del dominio personalizado                          |
| `POST /api/v1/custom-domain`                    | Añadir un dominio personalizado y recibir los registros DNS necesarios |
| `POST /api/v1/custom-domain/verify`             | Comprobar el DNS y activar un dominio listo                            |
| `DELETE /api/v1/custom-domain`                  | Eliminar el dominio personalizado                                      |

Consulta la [guía de la API de marca blanca](/es/admin/whitelabel-api) para ver ejemplos.

## MCP

Las mismas funciones orientadas al cliente están disponibles como herramientas de IA a través del [endpoint de MCP](/es/api/mcp):

```text theme={null}
https://app.famulor.io/mcp
```

MCP usa las mismas claves de API, consentimiento OAuth, alcances y acceso al espacio de trabajo. Su disponibilidad se controla por separado mediante **Connect AI / MCP**, no mediante API Access.