Registra Candidatos de Manera Masiva

POST /bulk-loading/upload

Este endpoint permite registrar candidatos de manera masiva, adjuntando un archivo CSV con N cantidad de candidatos.

Parámetros de Query

Nombre	Tipo	Requerido	Valor / Ejemplo
registerType	string	Sí	Método utilizado para registrar nuevos candidatos. Las opciones: byName, byNationalId

---

Archivo

Parámetro	Tipo	Requerido	Valor / Ejemplo
file	Form Data	Sí	Archivo CSV con peso máximo de 5MB

---

Plantilla del Archivo CSV

El archivo debe ser un .csv con una fila de encabezados seguida de una fila por candidato. La plantilla depende del valor de registerType.

Los encabezados deben coincidir exactamente

Usa los nombres de columna tal como aparecen abajo, respetando mayúsculas y minúsculas y guiones bajos (por ejemplo clientId, country_id, package_id, lastname). Una columna con otro nombre se considera ausente. Te recomendamos incluir todas las columnas de la plantilla, aunque vayan vacías. Las filas vacías se ignoran.

registerType=byNationalId

Registra al candidato a partir de su identificación oficial.

clientId,country_id,national_id,package_id,email,btrustProfile,btrustCategories,rfc,nss,personalReferences
cl_123456,MX,MARD020406MDFSMNA8,pkg_789012,maria.rodriguez@example.com,,,,,
cl_123456,MX,GOLJ850315HJCNPN04,pkg_789012,juan.gonzalez@example.com,,,GOLJ850315AB1,12345678901,3

Columna	Requerido	Descripción
clientId	Sí	Identificador de tu cliente en Blacktrust.
country_id	Sí	País del candidato, en ISO Alpha-2 o Alpha-3 (MX o MEX). Consulta Países Soportados.
national_id	Sí	Identificación oficial. Debe cumplir el formato del país (en México, la CURP de 18 caracteres).
package_id	Sí	Identificador del paquete de Processes a ejecutar.
email	Condicional	Requerido si el paquete exige que el candidato tenga usuario.
btrustProfile	Condicional	Requerido si el paquete incluye BTrust. Ver columnas según el paquete.
btrustCategories	Condicional	Requerido si btrustProfile es personalizado.
rfc	Condicional	Requerido si el paquete incluye Listas SAT.
nss	No	Número de Seguridad Social (11 dígitos).
personalReferences	Condicional	Requerido si el paquete incluye Referencias Personales.

registerType=byName

Registra al candidato a partir de su nombre y datos personales.

clientId,country_id,email,name,lastname,secondlastname,sex,birthDate,state,package_id,btrustProfile,btrustCategories,rfc,nss,personalReferences
cl_123456,MX,maria.rodriguez@example.com,María,Rodríguez,Díaz,M,06/04/2002,DF,pkg_789012,,,,,
cl_123456,MX,juan.gonzalez@example.com,Juan,González,,H,15/03/1985,JC,pkg_789012,,,GOLJ850315AB1,12345678901,3

Columna	Requerido	Descripción
clientId	Sí	Identificador de tu cliente en Blacktrust.
country_id	Sí	País del candidato, en ISO Alpha-2 o Alpha-3 (MX o MEX). Consulta Países Soportados.
email	Condicional	Requerido si el paquete exige que el candidato tenga usuario.
name	Sí	Nombre(s) del candidato.
lastname	Sí	Apellido paterno.
secondlastname	Sí*	Apellido materno. La columna debe existir, pero el valor puede ir vacío si el candidato no tiene segundo apellido.
sex	Sí	H (hombre) o M (mujer).
birthDate	Sí	Fecha de nacimiento en formato DD/MM/AAAA.
state	Sí	Código de estado de 2 letras. Consulta Códigos de Estado.
package_id	Sí	Identificador del paquete de Processes a ejecutar.
btrustProfile	Condicional	Requerido si el paquete incluye BTrust. Ver columnas según el paquete.
btrustCategories	Condicional	Requerido si btrustProfile es personalizado.
rfc	Condicional	Requerido si el paquete incluye Listas SAT.
nss	No	Número de Seguridad Social (11 dígitos).
personalReferences	Condicional	Requerido si el paquete incluye Referencias Personales.

* Incluye siempre el encabezado secondlastname; deja la celda vacía cuando no aplique.

Columnas según el paquete

Las columnas marcadas como Condicional dependen de los Processes incluidos en tu paquete. Déjalas vacías cuando no apliquen.

Columna	Detalle
btrustProfile	Perfil de BTrust a aplicar. Usa personalizado para elegir categorías específicas.
btrustCategories	Categorías de BTrust en una sola columna, separadas por comas (cat1,cat2).
personalReferences	Número de referencias a solicitar (mayor a 0).

Además, hay columnas que no forman parte de la plantilla base y que debes agregar solo cuando apliquen:

Columna	Cuándo se agrega	Descripción
telephone	Opcional.	Teléfono del candidato.
birthDate	Opcional en byNationalId.	Fecha de nacimiento en formato DD/MM/AAAA.
costCenter	Solo si tu cliente tiene centros de costos habilitados (entonces es obligatoria).	Identificador de un centro de costos visible para tu cliente.
calculateRfc	Paquetes con el proceso de validación de RFC.	true para calcular el RFC a partir del nombre y la fecha de nacimiento, false para enviarlo en rfc.
fiscalPostalCode	Paquetes con el proceso de validación de RFC.	Código postal fiscal de 5 dígitos, como texto (conserva el cero inicial, p. ej. 06600).

Reglas generales

• Tamaño máximo del archivo: 5MB.
• Si en alguna fila falta una columna o valor obligatorio (clientId, country_id, package_id y los propios de cada registerType), el archivo completo se rechaza con 400 y no se registra ningún candidato.
• Las validaciones de formato y de negocio (fecha, sex, state, national_id, email, rfc, etc.) se aplican por candidato después de la carga. Los que fallen se reportan en el archivo de errores disponible al consultar el estatus de la carga.
• Los archivos de personas físicas no deben incluir las columnas legalName, companyType ni incorporationDate: si están presentes, el archivo se rechaza.

---

Respuestas de la API

201 OK

A continuación se muestra un ejemplo de la respuesta estructural.

{
	"isSuccess": true,
	"statusCode": 201,
	"message": "Success",
	"data": {
		"uuid": "7203d1d6-53ea-4837-8c9a-6690f0c9d07e",
		"message": "File uploaded successfully"
	}
}

UUID En Respuesta

El UUID recibido en la respuesta podrá ser usado posteriormente para consultar el estatus del documento cargado y cada uno de los candidatos que se encontraban en el.