API de marca blanca

Si operas un espacio de trabajo de revendedor de marca blanca, la API de marca blanca te permite gestionar a tus propios clientes finales mediante programación en lugar de a través del panel — crea tu propia consola de administración, automatiza la incorporación, ejecuta flujos de autenticación personalizados en tu propio dominio o conecta las recargas de crédito a tu sistema de facturación.

Todos los endpoints de esta página requieren API Access, una clave de API creada en tu espacio de trabajo de marca blanca con el alcance platform:read o platform:write y un rol de propietario o administrador. Los resultados siempre se limitan a tus propios espacios de trabajo de clientes. Una clave emitida para un cliente solo puede usar la API REST mientras su espacio de trabajo también tenga API Access; emitir o revocar una clave no concede esta función.

Obtener usuarios de la plataforma

GET /api/v1/platform/users enumera tus clientes, del más reciente al más antiguo. Pagina con limit / offset (consulta paginación) y busca por nombre o correo con q.

curl "https://your-domain.example/api/v1/platform/users?limit=20&q=jane" \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX"

Registrar un usuario de la plataforma

POST /api/v1/platform/users crea una cuenta de cliente y un espacio de trabajo nuevos en tu nombre. Dos modos:

invite (predeterminado) — no requiere contraseña. La cuenta se crea sin credenciales; combínalo con una llamada de inicio de sesión o de token (más abajo) para que el cliente (o tu propio frontend) pueda acceder realmente.
password — eliges de antemano una contraseña inicial (8 o más caracteres) para el cliente.

curl https://your-domain.example/api/v1/platform/users \
  -X POST \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe", "email": "jane@customer.example", "mode": "invite"}'

Un correo que ya está registrado en cualquier parte de la plataforma falla con 409 — el mensaje nunca revela si esa cuenta está dentro o fuera de tu propio alcance. La respuesta del registro incluye welcome_credit con status, requested_credits y granted_credits. Esto permite que tu interfaz de incorporación muestre si los créditos de bienvenida (únicos) se concedieron o si necesitan una transferencia manual posterior. Esta es una acción autorizada del operador. Sigue disponible cuando el registro de autoservicio de la página de inicio de sesión alojada está desactivado.

Configurar el registro y los valores prepago predeterminados

GET /api/v1/platform/default-limits devuelve los controles independientes del registro de autoservicio y del acceso prepago, el precio prepago por minuto en EUR y los límites predeterminados de las cuentas de cliente prepago. PATCH actualiza cualquier subconjunto de estos ajustes.

curl https://your-domain.example/api/v1/platform/default-limits \
  -X PATCH \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"self_service_registration_enabled":false,"prepaid_accounts_enabled":true,"prepaid_extra_minute_price_eur":0.49}'

El registro de autoservicio solo afecta a la creación de cuentas desde la página de inicio de sesión alojada en tu dominio personalizado verificado. Los clientes existentes pueden seguir iniciando sesión y los operadores pueden seguir creando clientes. El acceso prepago determina por separado si los clientes sin un plan de pago pueden usar créditos prepago; cuando está desactivado, los clientes registrados deben elegir un plan de pago antes de usar la plataforma. Las herramientas MCP equivalentes son get_platform_default_limits y update_platform_default_limits en el conjunto platform.

Configurar los créditos de bienvenida

GET /api/v1/platform/welcome-credits devuelve el importe único configurado, si las cuentas prepago y las concesiones automáticas están activas, el saldo actual de tu monedero y el número estimado de clientes nuevos que puedes financiar ahora mismo. PATCH actualiza el importe para los futuros clientes; 800 créditos es el punto de partida recomendado, y 0 desactiva las concesiones automáticas.

curl https://your-domain.example/api/v1/platform/welcome-credits \
  -X PATCH \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"welcome_credits": 800}'

Puedes guardar el importe aunque sea superior al saldo actual de tu monedero. Si el monedero no alcanza para cubrir la concesión completa de un cliente nuevo, el registro se completa igualmente con 0 créditos de bienvenida. Esto no se compensa automáticamente después; usa la acción de transferencia de saldo cuando tu monedero tenga fondos. Los clientes existentes nunca reciben créditos con carácter retroactivo, y los cambios posteriores de configuración solo se aplican a los clientes futuros.

Iniciar sesión de un usuario de la plataforma

POST /api/v1/platform/users/login autentica a un cliente con su propio correo y contraseña y, si tiene éxito, devuelve un token de acceso. Úsalo para crear un formulario de inicio de sesión en tu plataforma de marca blanca en lugar de enviar a los clientes a la página de inicio de sesión alojada. Los inicios de sesión fallidos devuelven la misma respuesta genérica 401 y no revelan si la cuenta existe.

curl https://your-domain.example/api/v1/platform/users/login \
  -X POST \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@customer.example", "password": "correct horse battery staple"}'

Esta es la única operación de la API de marca blanca sin equivalente en MCP — las credenciales nunca deben viajar a través de una llamada a una herramienta MCP.

Crear un token de usuario

POST /api/v1/platform/users/{user_id}/token crea una clave de API para un cliente sin necesitar su contraseña — útil para un panel, un flujo de incorporación o una automatización aprobada que actúe en nombre del cliente.

curl https://your-domain.example/api/v1/platform/users/USER_ID/token \
  -X POST \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"name": "Onboarding token", "expires_in_days": 90}'

La clave en texto plano se devuelve una única vez — guárdala de inmediato, no se puede recuperar después. Pertenece al cliente, no a ti: si omites scopes, se concede acceso completo para ese cliente, no solo los alcances que tenga tu propia credencial de operador.

Cerrar sesión de un usuario de la plataforma

POST /api/v1/platform/users/{user_id}/logout revoca las claves de API activas y los tokens OAuth del cliente dentro de tu alcance de cliente. Úsalo para forzar el cierre de sesión después de que una cuenta se vea comprometida o cuando termine tu relación con ese cliente. Repetir la solicitud es seguro.

curl https://your-domain.example/api/v1/platform/users/USER_ID/logout \
  -X POST \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX"

Transferir saldo

POST /api/v1/platform/users/{user_id}/balance mueve créditos entre el saldo de tu espacio de trabajo y el de un cliente:

credits positivo — concede créditos de tu monedero al cliente (la forma estándar de aprovisionar la cuenta de un cliente).
credits negativo — recupera créditos del cliente de vuelta a tu monedero.

Cualquiera de las dos direcciones requiere que el monedero de origen cubra el importe — un saldo nunca baja de cero, y un intento de recuperación que supere el saldo del cliente falla por completo en lugar de aplicarse parcialmente.

curl https://your-domain.example/api/v1/platform/users/USER_ID/balance \
  -X POST \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"credits": 50, "note": "Onboarding credit"}'

Pagos personalizados

Los pagos personalizados te permiten cobrar a un cliente al margen de su plan habitual: una cuota de configuración única, una factura de soporte o un complemento recurrente a medida que no quieres modelar como un plan. Dos tipos:

Único — un cargo único por un importe fijo.
Suscripción — un cargo recurrente en el intervalo que elijas (día/semana/mes/año), con periodo de prueba opcional.

Cada pago se entrega por uno de tres canales:

charge_saved_method — cobra de inmediato la tarjeta guardada del cliente. Falla si no tiene ninguna tarjeta guardada, o si la tarjeta requiere un paso de autenticación que el cliente debe completar (en ese caso, usa invoice o payment_link).
invoice — crea una factura alojada, vencida en days_until_due días (14 por defecto), y envía al cliente un correo con el enlace de pago.
payment_link — crea un enlace de pago y devuelve su URL. El enlace es de un solo uso (deja de aceptar pagos tras completarse) pero no caduca por sí solo — compártelo cuando quieras.

curl https://your-domain.example/api/v1/platform/users/USER_ID/custom-payments \
  -X POST \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"kind": "one_time", "channel": "invoice", "description": "Custom integration setup", "amount_minor": 25000, "currency": "EUR"}'

amount_minor es el precio unitario en la unidad más pequeña de la moneda (p. ej. céntimos); el importe total cobrado es amount_minor * quantity. El cálculo automático de impuestos se aplica siempre que esté disponible para tu cuenta de pagos — esto requiere que el cliente ya tenga una dirección de facturación registrada; en caso contrario la solicitud falla con una indicación para añadir una primero (o puedes pasar automatic_tax: false para omitir el cálculo de impuestos en ese pago). La moneda debe coincidir con la moneda de visualización propia del workspace del cliente una vez establecida — no puedes cobrar a un cliente existente en una segunda moneda. GET /api/v1/platform/users/{user_id}/custom-payments lista los pagos de un cliente más el contexto para la creación (su workspace resuelto, monedas disponibles, métodos de pago guardados y disponibilidad del cálculo automático de impuestos). GET /api/v1/platform/custom-payments lista los pagos de todos los clientes en tu ámbito, filtrable por status, kind, channel y una búsqueda (q) que coincide tanto con la descripción del pago como con el correo electrónico del cliente.

curl "https://your-domain.example/api/v1/platform/custom-payments?status=open&limit=20" \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX"

Por defecto el cliente recibe un correo de notificación en los canales invoice y payment_link (desactivado por defecto en charge_saved_method, ya que un cargo con tarjeta ya genera un recibo) — puedes cambiarlo con notify_customer. El correo usa tu propio remitente y tu marca, igual que cualquier otro correo dirigido a clientes en tu plataforma. Un pago recorre estados como pending, open, paid, active / trialing (suscripciones), past_due, canceled, void, uncollectible y expired. GET /api/v1/platform/custom-payments/{payment_id} devuelve el estado actual, los importes y el enlace alojado. Usa POST sobre el mismo endpoint para ejecutar una acción:

curl https://your-domain.example/api/v1/platform/custom-payments/PAYMENT_ID \
  -X POST \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"action": "cancel"}'

Acción	Efecto
`refresh`	Vuelve a sincronizar el estado y los importes desde el proveedor de pagos.
`resend_notification`	Reenvía el correo de notificación al cliente.
`cancel`	Anula una factura abierta o desactiva un enlace de pago de inmediato. En una suscripción: programa la cancelación al final del periodo actual, salvo que se pase `immediately: true`, en cuyo caso cancela de inmediato.
`cancel_at_period_end`	Solo suscripciones: programa la cancelación al final del periodo actual (mismo efecto que `cancel` sin `immediately`).
`mark_uncollectible`	Marca una factura abierta como incobrable.
`deactivate_link`	Desactiva un enlace de pago sin afectar a lo ya pagado a través de él.

immediately (booleano, opcional) solo se aplica a la acción cancel en una suscripción: true cancela de inmediato, false/omitido cancela al final del periodo actual. No tiene efecto en facturas/enlaces de pago únicos ni en ninguna otra acción. Cancelar o marcar como incobrable no se puede deshacer mediante esta API. Limitaciones: no existe una acción de reembolso — realiza los reembolsos directamente desde el panel de tu cuenta de pagos. Cada pago es una única línea (sin descuentos, cupones ni varias líneas), y el precio de una suscripción existente no se puede modificar; cancélala y crea una nueva. Las herramientas MCP equivalentes son list_custom_payments, get_custom_payment, create_custom_payment y run_custom_payment_action en el conjunto platform — consulta MCP más abajo.

Gestionar claves de API

En el espacio de revendedor, abre Settings → API & MCP. Desplázate debajo de las conexiones MCP hasta Create a new API key, introduce un nombre y pulsa Create key. Necesitas API Access y el rol de propietario o administrador.

API & MCP — acceso a los ajustes; las claves API se encuentran más abajo

Cualquier espacio de trabajo — incluidos los espacios de cliente creados mediante esta API — puede gestionar sus propias claves de API a través de /api/v1/api-keys o de Settings → API & MCP en el panel. Una credencial propiedad de un usuario también puede generar una clave directamente para otro espacio de la misma marca en el que ese usuario sea actualmente propietario o administrador, llamando a /api/v1/workspaces/{workspace_id}/api-keys. Ese endpoint anidado es una capacidad general multiespacio y no requiere acceso de marca blanca.

curl https://your-domain.example/api/v1/api-keys \
  -X POST \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"name": "CRM integration", "scopes": ["calls:read", "leads:write"]}'

Una clave nunca puede crear otra clave con más acceso que ella misma: scopes en una clave nueva debe ser un subconjunto de los alcances de la credencial que hace la llamada. GET /api/v1/api-keys enumera las claves de un espacio de trabajo sin exponer sus secretos; DELETE /api/v1/api-keys/{id} revoca una.

MCP

Todo lo anterior también está disponible como herramientas MCP, agrupadas en el grupo platform (además de list_api_keys / create_api_key / revoke_api_key en el grupo settings). Conéctate con el selector de grupos de herramientas:

https://your-domain.example/mcp?toolsets=platform

Herramienta	Equivale a
`list_platform_users`	`GET /api/v1/platform/users`
`get_platform_user`	`GET /api/v1/platform/users/{user_id}`
`register_platform_user`	`POST /api/v1/platform/users`
`get_platform_default_limits`	`GET /api/v1/platform/default-limits`
`update_platform_default_limits`	`PATCH /api/v1/platform/default-limits`
`get_platform_welcome_credit_settings`	`GET /api/v1/platform/welcome-credits`
`update_platform_welcome_credit_settings`	`PATCH /api/v1/platform/welcome-credits`
`create_platform_user_token`	`POST /api/v1/platform/users/{user_id}/token`
`logout_platform_user`	`POST /api/v1/platform/users/{user_id}/logout`
`transfer_platform_credits`	`POST /api/v1/platform/users/{user_id}/balance`
`list_custom_payments`	`GET /api/v1/platform/custom-payments` (o `GET /api/v1/platform/users/{user_id}/custom-payments` con `user_id`)
`get_custom_payment`	`GET /api/v1/platform/custom-payments/{payment_id}`
`create_custom_payment`	`POST /api/v1/platform/users/{user_id}/custom-payments`
`run_custom_payment_action`	`POST /api/v1/platform/custom-payments/{payment_id}`

No existe una herramienta login_platform_user — el inicio de sesión se mantiene exclusivamente en REST, por el motivo indicado arriba. Las herramientas MCP aceptan un user_id o un email para identificar al cliente de destino; REST siempre toma user_id de la ruta de la URL.

Incluir servicios en un plan de cliente

En Plans, selecciona las funciones y la capacidad adicional incluidas en el precio recurrente. Los clientes las ven como Incluido en el plan. Las compras de capacidad adicional se suman a esa asignación; una función incluida no se cobra otra vez. Los servicios de pago único siguen siendo compras separadas. El editor muestra la tarifa de plataforma, su impuesto, una reserva estimada para procesar pagos y tu contribución restante por cliente, antes de tus propios gastos e impuestos. Las ofertas anuales usan los precios anuales disponibles; de lo contrario, el editor indica explícitamente doce periodos de costes mensuales. Los créditos incluidos siguen siendo una asignación mensual en ambos intervalos. La confirmación del pago activa los servicios comprados. Una cancelación programada mantiene el acceso hasta el final del periodo pagado. Un fallo de renovación bloquea los servicios de pago; un pago correcto restaura el contrato comprado. El saldo de créditos comprados permanece separado. Tras la cancelación se aplica tu política existente de cuentas gratuitas. Duplica los planes con suscripciones antes de cambiar el precio o los servicios incluidos. La copia comienza inactiva para que puedas revisarla.

Gestionar las inclusiones mediante la API

GET /api/v1/reseller/plans con settings:read devuelve tus planes y los códigos disponibles. PUT /api/v1/reseller/plans/{id}/inclusions con settings:write reemplaza las inclusiones de un plan elegible. Ambas operaciones requieren permisos de propietario o administrador del espacio de marca blanca. Las herramientas MCP son list_reseller_plans y update_reseller_plan_inclusions. Configuran la oferta sin cobrar a los clientes ni crear suscripciones de pago.

Contraseñas de clientes y correos de la cuenta

Abre Usuarios → seleccionar cliente → Acceso a la cuenta para enviar un correo de restablecimiento o establecer una nueva contraseña. El cambio directo solo está disponible si la cuenta se utiliza exclusivamente dentro de tu marca. Para las cuentas con acceso a otras marcas o espacios de la plataforma, envía un correo de restablecimiento para que el cliente controle su acceso global. Los correos de la cuenta usan tu dominio verificado, tu marca y el remitente SMTP configurado: invitaciones, recuperación de contraseña, confirmaciones de cambio de correo, códigos y notificaciones de seguridad activadas. El cambio de correo puede requerir confirmación desde la dirección actual y la nueva. Un fallo de envío no cambia el remitente a otra marca. Revisa tus ajustes SMTP si falla la entrega. Usa GET /api/v1/platform/users/{user_id}/password?workspace_id=... para comprobar permisos. POST al mismo endpoint acepta el espacio, la acción reset o set y una contraseña para set. Las herramientas MCP get_platform_user_password_access y manage_platform_user_password aplican los mismos límites de clientes. El restablecimiento usa tu remitente SMTP. Nunca registres contraseñas en logs.

Cuenta de pagos y actividad financiera

Antes de activar la cuenta de pagos, Conectar pagos te guía durante la verificación. Después, Pagos y transferencias ofrece un resumen, pagos de clientes, transferencias bancarias, una pestaña Informe de saldo y ajustes del checkout. El panel muestra el saldo de tu cuenta de pagos. Los importes conservan su moneda de liquidación real. La acción del panel externo abre el panel compatible con tu cuenta conectada. El informe de saldo permite filtrar por período, moneda y zona horaria y exportar archivos CSV. Cuando están disponibles, el resumen también muestra una oferta de transferencias instantáneas y un gráfico del volumen de pagos. Las transferencias instantáneas solo aparecen cuando hay fondos elegibles. Financiación, después de Checkout, aparece cuando tu cuenta dispone de financiación empresarial. Las transferencias y las solicitudes de financiación requieren tu propio acceso autenticado y cualquier verificación adicional de la cuenta de pagos. Usa GET /api/v1/reseller/billing o la herramienta MCP get_reseller_billing del conjunto billing con billing:read. Se requieren permisos owner o admin en tu espacio de marca blanca y API Access. El resumen predeterminado devuelve el estado y los saldos disponibles y pendientes. Usa view=payments o view=payouts para la actividad y limit de 1 a 100 (25 por defecto). Pasa next_cursor como cursor en las siguientes 24 horas para obtener otra página; null indica el final. Los cursores están vinculados a la cuenta y la vista. Antes de la activación, los saldos están vacíos y las consultas de actividad devuelven 409. Estas operaciones solo leen datos: no generan reembolsos, transferencias, cambios de cuentas bancarias ni sesiones de acceso al panel. Usa view=transactions para consultar el registro del saldo: importes con signo, cambios netos, categorías públicas y fechas de disponibilidad. Usa next_cursor para obtener más historial. Los informes exportables y las solicitudes de financiación son procesos interactivos de la cuenta; la API pública y MCP ofrecen acceso de lectura y no envían solicitudes ni inician transferencias. Una notificación de la cuenta muestra las verificaciones pendientes tras el registro, incluidas las que limitan temporalmente los pagos. Se oculta cuando no hay notificaciones. La sección fiscal de Checkout incluye ajustes y registros fiscales. Los detalles también están disponibles en modo de solo lectura mediante view=tax; la interfaz autenticada de la cuenta de pagos también permite cambios interactivos. La gestión fiscal también está disponible por API y MCP con billing:write y acceso de propietario/administrador: PUT /api/v1/reseller/tax/settings actualiza valores y dirección; POST /api/v1/reseller/tax/registrations crea o programa la recaudación; PATCH /api/v1/reseller/tax/registrations cambia inicio o vencimiento. Consulta ajustes con GET /api/v1/reseller/tax/settings. Las herramientas son get_reseller_tax_settings, update_reseller_tax_settings, create_reseller_tax_registration y update_reseller_tax_registration. Usa la referencia opaca de la vista fiscal (válida 24 horas) y una clave única para cada creación, reutilizada en reintentos idénticos. Los registros no se pueden eliminar y no inscriben a tu empresa ante autoridades fiscales. Los cambios deben seguir instrucciones explícitas del propietario.

Acceso a fuentes de conocimiento

Los operadores de marca blanca pueden activar por separado Rastreo del sitio web, Sincronización de almacenamiento en la nube y Sincronización automática en los planes de clientes y los valores predeterminados de prepago. La sincronización automática controla la actualización programada de ambos tipos de fuente; la función de fuente correspondiente también debe estar activada. El espacio propio del operador sigue su propio plan, de forma independiente a sus clientes. Las fuentes en la nube requieren además Configuración → Espacio de trabajo → Funciones beta en cada espacio de cliente. El contenido nuevo o modificado sigue consumiendo créditos; habilitar el acceso no incluye procesamiento gratuito. Consulta los permisos con GET /api/v1/reseller/plans y actualízalos con PATCH /api/v1/reseller/plans/{id}/knowledge-sources (settings:write). La herramienta MCP correspondiente es update_reseller_plan_knowledge_sources. Los cambios se aplican a los clientes que usan ese plan. Los valores de prepago usan la API y las herramientas MCP de límites predeterminados descritas arriba.

Programa de marca blanca

Configuración de marca blanca

Plantillas de prompts

Facturación y pagos

Tarifas y planes

Gestión de límites de clientes

Migración de datos