Ir al contenido principal

Clonación de subdominios para socios: guía paso a paso

¿Cómo hago una copia de mi subdominio?

Este endpoint permite que un socio aprobado cree un nuevo subdominio de WorkBright copiando un subdominio de plantilla existente. La cuenta nueva hereda la configuración de la plantilla (procesos, paquetes de documentos y ajustes), así que puede tener cuentas listas para usar sin configurar cada una manualmente.

Nota de acceso: Este endpoint solo está disponible para socios aprobados.

Cuándo usarlo

Úselo cuando quiera crear una cuenta de cliente nueva mediante programación en lugar de configurarla manualmente. Un uso común: su representante de WorkBright configura una plantilla con la configuración exacta que necesita, y usted la clona cada vez que incorpora a un cliente nuevo.

Antes de empezar

Necesita dos cosas, y ambas corresponden a su subdominio principal de socio (no a un subdominio de plantilla):

  1. Su subdominio principal de socio: es el host al que envía la solicitud.

  2. La clave de API de ese subdominio principal: autentica la solicitud.

También debe saber el nombre del subdominio de plantilla que quiere clonar. Su representante de WorkBright crea las plantillas, así que pregúntele qué nombre usar si no está seguro.

El error de configuración más común es enviar la solicitud a un subdominio de plantilla. Siempre envíela a su subdominio principal de socio. La plantilla se indica en el cuerpo de la solicitud, no en la URL.

Cómo funciona, de principio a fin

  1. Su representante de WorkBright configura las plantillas. Cada subdominio de plantilla viene preconfigurado con los ajustes que quiere que hereden las cuentas nuevas.

  2. Usted llama al endpoint desde su subdominio principal. Se autentica con la clave de API de su subdominio principal e indica la plantilla que quiere copiar.

  3. Recibe una respuesta inmediata con status: pending. La creación de la cuenta se hace en segundo plano. Esta misma respuesta incluye la clave de API de la cuenta nueva, así que guárdela de forma segura de inmediato.

  4. Un webhook confirma el resultado. Cuando termina la creación, se envía el evento de webhook account.provisioned con el estado succeeded o failed.

Como la creación es asíncrona, una respuesta 202 significa “aceptada y en curso”, no “terminada”. El webhook le indica el resultado final.

La solicitud

Elemento

Valor

Método

POST

Endpoint

/api/partner/accounts/clone

URL base

Autenticación

Clave de API en el encabezado API-Key

Content-Type

application/json

Parámetros del cuerpo

Campo

Tipo

Obligatorio

Descripción

template

String

Sí

El subdominio de la cuenta de plantilla que se va a clonar. Use el nombre de plantilla que creó su representante de WorkBright.

subdomain

String

Sí

El subdominio que quiere para la cuenta nueva. Debe ser único a nivel global y apto para URL: solo letras minúsculas, números y guiones.

name

String

Sí

Un nombre visible y legible para la cuenta nueva.

account_type

String

No

Use test para crear una cuenta de prueba (sandbox). Las cuentas de prueba no cuentan para el uso y activan una versión de prueba de Document Verification. No lo use para cuentas de producción.

Ejemplo de solicitud

curl --location 'https://yoursubdomain.workbright.com/api/partner/accounts/clone' \
--header 'API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"template": "templatesubdomain",
"subdomain": "desiredsubdomain",
"name": "Subdomain Name"
}'

Qué recibe como respuesta

Éxito: 202 Accepted

La cuenta se aceptó y se está creando en segundo plano.

{
"subdomain": "accountprovisioningtest9",
"api_key": "your_api_key",
"status": "pending"
}

Dos puntos importantes:

  • status es pending. La cuenta todavía no está lista. Espere el webhook account.provisioned para confirmarlo.

  • api_key es la clave de la cuenta nueva. Guárdela de forma segura ahora, porque la necesitará para hacer llamadas de API a esa cuenta.

Cómo confirmar el resultado: el webhook account.provisioned

La respuesta 202 le indica que la creación empezó, no que terminó. Para saber el resultado final, escuche el webhook account.provisioned. Se envía cuando termina la solicitud de clonación.

Algunos requisitos de configuración:

  • Este webhook solo está disponible para socios aprobados con acceso a la creación de subdominios por API.

  • Debe configurar el webhook en su subdominio principal de socio (partner bundle).

Cómo se ve el contenido (payload)

{
"event_key": "account.provisioned",
"occurred_at": "2026-06-22T10:30:35.764-06:00",
"data": {
"subdomain": "subdomainABC",
"status": "succeeded"
}
}

Cómo leer el contenido

  • event_key identifica el evento como account.provisioned.

  • occurred_at es el momento en que terminó la creación.

  • data.subdomain indica a qué cuenta corresponde el resultado. Compárelo con el subdominio que pidió.

  • data.status es succeeded o failed. Si falló, el atributo status incluye notas que explican por qué.

En resumen: envíe la solicitud, guarde la clave de API que recibe y espere este webhook para saber si la cuenta está lista o requiere atención.

Cómo manejar los errores

401 Unauthorized: clave de API no válida

Falta el encabezado API-Key o es incorrecto. Confirme que usa la clave de API de su subdominio principal de socio.

{}

422 Unprocessable Entity: el subdominio ya está en uso

El subdominio que pidió ya está en uso. Elija otro.

{
"errors": {
"subdomain": [
"This subdomain is already taken."
]
}
}

422 Unprocessable Entity: subdominio no válido

El valor de subdomain no tiene el formato correcto. Use solo letras minúsculas, números y guiones.

{
"errors": {
"subdomain": [
"This does not look like a valid subdomain"
]
}
}

Lista de verificación rápida

  • Envió la solicitud a su subdominio principal de socio, no a una plantilla.

  • Usó la clave de API de ese subdominio principal.

  • template coincide con un nombre de plantilla que configuró su representante de WorkBright.

  • subdomain es único a nivel global y solo usa letras minúsculas, números y guiones.

  • name tiene un valor.

  • Guardó la api_key que recibió para la cuenta nueva.

  • Está escuchando el webhook account.provisioned para confirmar si funcionó o falló.

Qué se copia de una plantilla

Al clonar un subdominio nuevo a partir de una plantilla, se copia esta configuración:

  • Formularios y documentos, con sus ajustes, campos, orden y asignaciones a grupos

  • Campos: campos personalizados y estándar

  • Grupos: grupos de empleados

  • Informes: informes guardados

  • Configuración de funciones: qué funciones están activadas

  • Ajustes de permisos de administrador

  • Configuración de webhooks

  • Ajustes de URL de redirección integrada, cuando la función integrada (embedded) está activada

  • Lógica condicional, cuando está activada

Fuera del alcance

  • Clonar la dirección de la empresa

  • Clonar las credenciales de E-Verify

  • Clonar los ajustes de fechas límite de envío

  • Fechas relativas (fecha límite habitual o extendida) o fechas exactas

  • Clonar la configuración de SSO

  • Clonar la configuración de CSS

  • Compartir formularios personalizados entre subdominios (por ejemplo, que los cambios en un formulario se apliquen a otros, o que el ID del formulario sea el mismo en todos los subdominios)

  • Clonar usuarios administradores

  • Un panel único para ver novedades de todos los subdominios secundarios

  • Un endpoint para ver de forma masiva el progreso de incorporación de los empleados en todos los subdominios

  • Dar de baja subdominios

¿Ha quedado contestada tu pregunta?