Introducción a la API

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.

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 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.

URL base

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:

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.

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.

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:

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:

{
  "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:

{
  "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 para ver ejemplos.

MCP

Las mismas funciones orientadas al cliente están disponibles como herramientas de IA a través del endpoint de MCP:

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.

​URL base

​Acceso a la API

​Autenticación

​Higiene de las claves

​Requisitos de clientes OAuth

​Formato de respuesta

​Paginación

​Errores

​Gestión de clientes de marca blanca

​MCP

URL base

Acceso a la API

Autenticación

Higiene de las claves

Requisitos de clientes OAuth

Formato de respuesta

Paginación

Errores

Gestión de clientes de marca blanca

MCP