API de administración de usuarios masiva

La API de administración masiva de usuarios te permite usar el contenido de un archivo JSON para crear o modificar varios usuarios en una sola operación.

No hay límite para la cantidad de registros que se pueden subir, pero se recomienda que las solicitudes se realicen en lotes más pequeños.

Este proceso también se puede realizar en el portal de la plataforma de CCAI siguiendo las instrucciones de la sección Administración masiva de usuarios.

Se proporciona la aplicación de referencia de la herramienta de sincronización masiva de usuarios que realiza una sincronización de usuarios entre un directorio, como los grupos de Google Workspace o Microsoft Entra ID, con CCaaS. Esta aplicación de referencia aprovecha la API de administración masiva de usuarios.

Funciones y permisos

  • Para usar la API de Apps , crea un api_user.

  • El api_user no tiene funciones ni permisos, por lo que todos los api_users pueden realizar la bulk_user management.

  • No puedes establecer permisos detallados cuando utilizas api_user, por lo que el api_user tendrá acceso a todos los campos de usuario.

Agrega una credencial de API

  1. En el portal de la plataforma de CCAI, ve a Configuración > Configuración para desarrolladores > Administración de credenciales de API.

  2. Haz clic en + Agregar credencial de API. Se abrirá un mensaje de Agregar credencial de API.

  3. Ingresa un Nombre para la credencial.

  4. Haz clic en Crear.

Usa la API de administración masiva de usuarios

Para usar la API de administración masiva de usuarios, se requieren dos llamadas a la API. Una sube el archivo JSON y crea el trabajo, y la otra lo procesa. También puedes usar llamadas a la API opcionales para asegurarte de que tu trabajo se procese correctamente.

  1. Opcional: Recupera la plantilla JSON. Esto recupera la plantilla más reciente, que incluye cualquier función o equipo adicional que se haya creado desde que recuperaste la plantilla anterior. Google recomienda este paso.

  2. Opcional: Obtén datos de configuración del usuario. Esto recupera una lista de todos los usuarios (o un solo usuario, si especificas una dirección de correo electrónico) para duplicar.

  3. Sube el archivo JSON. Puedes agregar o actualizar uno o varios usuarios en el archivo. Asegúrate de tomar nota del ID del trabajo.

  4. Solicita el procesamiento del archivo JSON. Esto inicia el trabajo masivo.

  5. Opcional: Obtén una verificación de estado. Proporciona el ID del trabajo para ver el estado de procesamiento.

  6. Opcional: Recupera una lista de trabajos actualizada. Esto recupera la lista de todos los trabajos de administración masiva de usuarios.

  7. Opcional: Recupera los registros de errores del esquema. Especifica el ID del trabajo para obtener los registros de errores del esquema.

  8. Opcional: Recupera los errores. Obtén errores.

Sube el archivo JSON

Uso

Sube el archivo JSON

URL

apps/api/v1/bulk/users/upload

Método

POST / PUT

Solicitud

content-type: multipart/form-data

{
  "id" : {job_id} #optional. Required in case of PUT method.
  "file": {json file}
}

Respuesta

Encabezado:

Link: http://ujet.co/apps/api/v1/bulk/users_jobs/12345

Cuerpo

{
  "id": 12345, # job_id
  "status": "created"
  "link": "http://ujet.co/apps/api/v1/bulk/users_jobs/12345"
}

Recupera la plantilla JSON

Uso

Plantilla

URL

apps/api/v1/bulk/users/template

Método

GET

Solicitud

(Vacío)

Respuesta

 
[
{
"email":"user1@yourcompany.co",
"new_email":user1@yourcompany.cx",
"agent_number":"A-001",
"first_name":"John",
"last_name":"aa",
"status":"Active",
"location":"Mexico",
"max_chat_limit":2,
"max_chat_limit_enabled":0,
"roles": [
{"name":"Admin","value": 0 },
{"name":"Manager","value": 1 },
{"name":"Agent","value": 0 },
{"name":Developer","value": 1 }
]
},
 ...
]

Cómo desactivar un usuario

Para desactivar un usuario, cambia el status valor a Inactive—por ejemplo, "status":"Inactive".

Solicita el procesamiento del archivo JSON actual

Uso

Solicita el procesamiento del archivo JSON actual

URL

/v1/bulk/users/proceed

Método

POST

Solicitud

 
{
   "id": 12345  # job_id
}

Respuesta

Encabezado:

Link: http://ujet.co/apps/api/v1/bulk/users_jobs/12345

Cuerpo

1{"id": 12345 # job_id3 "status": "valid_scheme",4 "link": "http://ujet.co/apps/api/v1/bulk/users_jobs/12345"5}

Obtén una verificación de estado

Uso

Obtén una verificación de estado

URL

apps/api/v1/bulk/users/jobs/#{job_id}

Método

GET

Solicitud

Variable de ruta de acceso: job_id

Respuesta

 
{
    "id": 12345,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": "2022-01-07T06:45:34.000Z",
    "filename": "100row.json",
    "total_rows": 100,
    "affected_rows": 52,
    "failed_rows": 0,
    "status": "in_progress",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "api_user_name_1",
    "proceed_api_user_name": "api_user_name_2",
    "scheme_errors": []
    "update_errors": []
}

Recupera la lista de trabajos actualizada

Uso

Obtén la lista de trabajos actualizada

URL

apps/api/v1/bulk/users/jobs

Método

GET

Solicitud

 
{
  "page": 1,
  "per_page": 20
}

Respuesta

Encabezado

Link: <next link>
Total: 12345
Per-Page: 201

Cuerpo

[
    {
        "id": 12345,
        "created_at": "2022-01-07T06:21:10.000Z",
        "process_requested_at": "2022-01-07T06:22:25.000Z",
        "filename": "100row.json",
        "total_rows": 100,
        "affected_rows": 52,
        "failed_rows": 0,
        "status": "in_progress",
        "uploaded_user_name": null,
        "proceed_user_name": null,
        "uploaded_api_user_name": "api_user_name_1",
        "proceed_api_user_name": "api_user_name_2",
        "scheme_errors": [],
        "update_errors": []
    },
    ...
]

Nota

El resultado se ordena en orden inverso de job_id para que los datos más recientes aparezcan primero.

Recupera los registros de errores del esquema

Uso

Obtén los registros de errores del esquema

URL

/v1/bulk/users/errors/scheme/#{job_id}

Método

GET

Solicitud

Variable de ruta de acceso: job_id

Respuesta

content-type: application/json

[
  {
    "message": "Must be a valid email",
    "column": 1,
    "row": null
  },
  {
    "message": "Non-empty string",
    "column": 10,
    "row": 10
  }
]

Recupera los errores

Uso

Obtén los registros de errores de actualización

URL

/v1/bulk/users/errors/update/#{job_id}

Método

GET

Solicitud

Variable de ruta de acceso: job_id

Respuesta

content-type: application/json

1[2 {3 "message": "Must be a valid email",4 "column": 1,5 "row": null,6 "error_type": "warning"7 },8 {9 "message": "Non-empty string",10 "column": 10,11 "row": 10,12 "error_type": "error"13 } 14]