API de administración de usuarios masiva

La API de Bulk User Management 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 que se indican en 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 Bulk user management.

Roles y permisos

  • Crea un api_user para usar la API de Apps.

  • El usuario de la API no tiene roles ni permisos, por lo que todos los usuarios de la API pueden realizar bulk_user management.

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

Agrega una credencial de API

  1. En el portal de la CCAI Platform, ve a Settings > Developer Settings > API Credential management.

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

  3. Ingresa un Nombre para la credencial.

  4. Haz clic en Crear.

Usa la API de administración de usuarios masiva

Para usar la API de administración de usuarios masiva, se requieren dos llamadas a la API. Uno sube el archivo JSON y crea el trabajo, y el otro 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 los roles o equipos adicionales que se crearon desde que recuperaste la plantilla anterior. Google recomienda este paso.

  2. Opcional: Obtén datos de configuración del usuario. 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 anotar el ID del trabajo.

  4. Procesamiento de la solicitud del archivo JSON. Esto inicia el trabajo masivo.

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

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

  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 errores. Obtiene 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 valor de status 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}

Cómo obtener una verificación de estado

Uso

Cómo obtener 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 de actualización

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 registros de errores de esquemas

Uso

Obtén registros de errores de esquemas

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 errores

Uso

Obtén 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]