Extremos de administración de usuarios masiva

Los extremos de la API de administración masiva te permiten crear o actualizar una gran cantidad de usuarios a través de la colección de administración masiva de usuarios.

La API admite el uso de archivos JSON. Puedes obtener datos JSON con la API de plantillas.

Solo se admite la autenticación de api_user. Debes ingresar el token de usuario de la API en la variable de contraseña. No se admite la autenticación heredada con un secreto de la empresa.

Cuando se sube un archivo JSON a través de la API de carga, se crea un trabajo que valida el esquema del archivo JSON.

Los extremos admitidos para la administración masiva de usuarios incluyen los siguientes:

Para agregar o actualizar usuarios de forma masiva con la API de usuarios masivos, haz lo siguiente:

  1. Llama al método Template para obtener el objeto de plantilla JSON que usarás para generar el archivo JSON.

  2. Llama al método Bulk add users from file o al método Bulk update users from file, según si realizas una actualización o una adición masiva. Esto verifica el esquema del archivo JSON que proporcionas.

  3. Después de verificar el esquema del archivo JSON, llama al método Proceed. Esto inicia el trabajo.

  4. Para determinar el estado del trabajo, llama al método Jobs.

Formato de archivo JSON

Puedes obtener el formato del archivo JSON llamando al método de plantilla.

Nombre de los campos Valores Obligatorio Validación
correo electrónico String(Email) Sí Debe ser un correo electrónico válido. Debe ser único dentro del archivo en la columna Correo electrónico (sin duplicados), por lo que solo se permite 1 actualización por dirección de correo electrónico por archivo.
new_email String(Email) No Debe ser un correo electrónico válido. Debe ser único dentro del archivo en la columna Correo electrónico nuevo (sin duplicados), por lo que solo se permite 1 actualización por dirección de correo electrónico por archivo.
agent_number String No Cadena sin validación
first_name String Sí Cadena no vacía
last_name String Sí Cadena no vacía
estado Activo, Inactivo, Vacío No Debe ser "Activo", "Inactivo" o estar vacío.
ubicación Es una cadena que es un nombre de ubicación, vacía o nula. No Debe coincidir exactamente con una de las ubicaciones existentes (sin distinguir mayúsculas de minúsculas), o bien ser nulo o estar vacío.
max_chat_limit De 1 a X (donde X es el valor configurado), vacío No Debe ser de 1 a X (inclusive) o estar vacío.
max_chat_limit_enabled 0, 1, vacío No Debe ser 0, 1 o estar vacío
roles name: Nombre del rol / value: 0, 1, Empty No Debe ser 0, 1 o estar vacío
equipos. name: Nombre del equipo / value: 0, 1, Empty No Debe ser 0, 1 o estar vacío

Una vez que el método de la API de carga de archivos JSON se complete correctamente, se puede llamar al método de la API de Proceed y, luego, se procesa la creación o modificación del usuario.

Contact Center AI Platform (CCAI Platform) realiza los métodos de carga y procesamiento de forma asíncrona. Para verificar el estado, llama al método jobs y especifica job_id.

Campo de estado

El campo status del trabajo puede tener cualquiera de los siguientes valores:

Estado del trabajo Descripción
created Se creó un trabajo y se espera su validación.
valid_scheme La validación del Scheme se realizó correctamente y se puede continuar.
invalid_scheme No se pudo validar el Scheme. Puedes consultar información detallada a través de la API de registro de errores de Scheme.
in_progress Se está realizando la actualización o creación masiva de usuarios.
finalizada Se completó la creación o actualización masiva de usuarios.

Plantilla

Endpoint:

Method: GET
Type: 
URL: https://{​subdomain}​.{​domain​}/apps/api/v1/bulk/users/template

Ejemplo de solicitud y respuestas

En las siguientes secciones, se proporcionan ejemplos de solicitudes al extremo.

Obtener plantilla

En este ejemplo, se muestra cómo recuperar las plantillas.

Solicitud

Cuerpo: Ninguno

Respuesta: Plantilla
[
    {
        "email": "user1@somedomain.com",
        "new_email": "user1@somedomain.com",
        "agent_number": "A-001",
        "first_name": "James",
        "last_name": "Bond",
        "status": "Active",
        "location": "Mexico",
        "max_chat_limit": "2",
        "max_chat_limit_enabled": "0",
        "roles": [
            {
                "name": "Admin",
                "value": 0
            },
            {
                "name": "Manager",
                "value": 0
            },
            {
                "name": "Agent",
                "value": 0
            },
            {
                "name": "Developer",
                "value": 0
            },
            {
                "name": "Manager Admin",
                "value": 0
            },
            {
                "name": "Manager Team",
                "value": 0
            },
            {
                "name": "Manager Data",
                "value": 0
            }
        ],
        "teams": [
            {
                "name": "test team_1",
                "value": 0
            },
            {
                "name": "test Team 2",
                "value": 0
            },
            {
                "name": "test team 3",
                "value": 0
            }
        ]
    },
    {
        "email": "user2@somedomain.com",
        "new_email": "user3@somedomain.com",
        "agent_number": "A-002",
        "first_name": "John",
        "last_name": "Doe",
        "status": "Inactive",
        "location": "",
        "max_chat_limit": "",
        "max_chat_limit_enabled": "1",
        "roles": [
            {
                "name": "Admin",
                "value": 0
            },
            {
                "name": "Manager",
                "value": 0
            },
            {
                "name": "Agent",
                "value": 0
            },
            {
                "name": "Developer",
                "value": 0
            },
            {
                "name": "Manager Admin",
                "value": 0
            },
            {
                "name": "Manager Team",
                "value": 0
            },
            {
                "name": "Manager Data",
                "value": 0
            }
        ],
        "teams": [
            {
                "name": "test team_1",
                "value": 0
            },
            {
                "name": "test Team 2",
                "value": 0
            },
            {
                "name": "test team 3",
                "value": 0
            }
        ]
    },
    {
        "email": "user3@somedomain.com",
        "new_email": "user2@somedomain.com",
        "agent_number": "A-003",
        "first_name": "Jane",
        "last_name": "Doe",
        "status": "",
        "location": "null",
        "max_chat_limit": "1",
        "max_chat_limit_enabled": "",
        "roles": [
            {
                "name": "Admin",
                "value": 0
            },
            {
                "name": "Manager",
                "value": 0
            },
            {
                "name": "Agent",
                "value": 0
            },
            {
                "name": "Developer",
                "value": 0
            },
            {
                "name": "Manager Admin",
                "value": 0
            },
            {
                "name": "Manager Team",
                "value": 0
            },
            {
                "name": "Manager Data",
                "value": 0
            }
        ],
        "teams": [
            {
                "name": "test team_1",
                "value": 0
            },
            {
                "name": "test Team 2",
                "value": 0
            },
            {
                "name": "test team 3",
                "value": 0
            }
        ]
    }
]

Código de estado: 200

Trabajos

Endpoint:

Method: GET
Type: 
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/{job_id}​

Ejemplo de solicitud y respuestas

En las siguientes secciones, se proporcionan ejemplos de solicitudes al extremo.

Detalle del trabajo

En este ejemplo, se muestra cómo recuperar los detalles de un trabajo específico. En este ejemplo, el ID del trabajo es 1.

Solicitud

Encabezados:

Clave Valor Descripción
Content-Type application/json

Consulta:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Respuesta: Detalle del trabajo
{
    "id": 1,
    "created_at": "2022-01-07T06:06:45.000Z",
    "process_requested_at": null,
    "filename": "100row.csv",
    "total_rows": 100,
    "affected_rows": 0,
    "failed_rows": 0,
    "status": "created",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": null,
    "scheme_errors": [],
    "update_errors": []
}

Código de estado: 200

Lista de trabajos

En este ejemplo, se muestra cómo obtener todos los trabajos.

Solicitud

Encabezados:

Clave Valor Descripción
Content-Type application/json

Consulta:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/
Respuesta: Lista de trabajos
[
    {
        "id": 3,
        "created_at": "2022-01-07T06:21:10.000Z",
        "process_requested_at": "2022-01-07T06:22:25.000Z",
        "filename": "100row_new.csv",
        "total_rows": 100,
        "affected_rows": 0,
        "failed_rows": 0,
        "status": "in_progress",
        "uploaded_user_name": null,
        "proceed_user_name": null,
        "uploaded_api_user_name": "zdco_admin",
        "proceed_api_user_name": "zdco_admin",
        "scheme_errors": [],
        "update_errors": []
    },
    {
        "id": 2,
        "created_at": "2022-01-07T06:17:09.000Z",
        "process_requested_at": null,
        "filename": "100row.csv",
        "total_rows": 100,
        "affected_rows": 0,
        "failed_rows": 0,
        "status": "created",
        "uploaded_user_name": null,
        "proceed_user_name": null,
        "uploaded_api_user_name": "zdco_admin",
        "proceed_api_user_name": null,
        "scheme_errors": [],
        "update_errors": []
    },
    {
        "id": 1,
        "created_at": "2022-01-07T06:06:45.000Z",
        "process_requested_at": null,
        "filename": "100row.csv",
        "total_rows": 100,
        "affected_rows": 0,
        "failed_rows": 0,
        "status": "created",
        "uploaded_user_name": null,
        "proceed_user_name": null,
        "uploaded_api_user_name": "zdco_admin",
        "proceed_api_user_name": null,
        "scheme_errors": [],
        "update_errors": []
    }
]

Código de estado: 200

Se creó el trabajo

En este ejemplo, se muestra cómo recuperar los trabajos de solicitud de usuarios masivos que se crearon.

Solicitud

Encabezados:

Clave Valor Descripción
Content-Type application/json

Consulta:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Respuesta: Se creó el trabajo
{
    "id": 1,
    "created_at": "2022-01-07T06:39:59.000Z",
    "process_requested_at": null,
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 0,
    "failed_rows": 0,
    "status": "created",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": null,
    "scheme_errors": [],
    "update_errors": []
}

Código de estado: 200

Se validó correctamente el trabajo

En este ejemplo, se muestra cómo validar que un trabajo se haya completado correctamente.

Solicitud

Encabezados:

Clave Valor Descripción
Content-Type application/json

Consulta:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Respuesta: El trabajo se validó correctamente
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": null,
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 0,
    "failed_rows": 0,
    "status": "valid_scheme",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": null,
    "scheme_errors": [],
    "update_errors": []
}

Código de estado: 200

Falla la validación del trabajo

En este ejemplo, se muestra cómo determinar que un trabajo falló.

Solicitud

Encabezados:

Clave Valor Descripción
Content-Type application/json

Consulta:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Respuesta: Falla la validación del trabajo
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": null,
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 0,
    "failed_rows": 0,
    "status": "invalid_scheme",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": null,
    "scheme_errors": [
        "scheme error detail 1",
        "scheme error detail 2",
        "scheme error detail 3"
    ],
    "update_errors": []
}

Código de estado: 200

Actualización de trabajos

En este ejemplo, se muestra cómo determinar que un trabajo se está actualizando.

Solicitud

Encabezados:

Clave Valor Descripción
Content-Type application/json

Consulta:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Respuesta: Actualización del trabajo
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": "2022-01-07T06:42:59.000Z",
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 52,
    "failed_rows": 0,
    "status": "in_progress",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": "zdco_admin",
    "scheme_errors": [],
    "update_errors": []
}

Código de estado: 200

Finalización de la actualización del trabajo sin errores

En este ejemplo, mostramos cómo identificar un trabajo que finalizó sin errores.

Solicitud

Encabezados:

Clave Valor Descripción
Content-Type application/json

Consulta:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Respuesta: La actualización del trabajo finalizó sin errores
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": "2022-01-07T06:42:59.000Z",
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 100,
    "failed_rows": 0,
    "status": "finished",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": "zdco_admin",
    "scheme_errors": [],
    "update_errors": []
}

Código de estado: 200

La actualización del trabajo finalizó con errores

En este ejemplo, mostramos cómo identificar un trabajo que finalizó con errores.

Solicitud

Encabezados:

Clave Valor Descripción
Content-Type application/json

Consulta:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Respuesta: La actualización del trabajo finalizó con errores
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": "2022-01-07T06:42:59.000Z",
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 100,
    "failed_rows": 0,
    "status": "finished",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": "zdco_admin",
    "scheme_errors": [],
    "update_errors": [
        "update error detail 1",
        "update error detail 2",
        "update error detail 3"
    ]
}

Código de estado: 200

Error: ID de trabajo no válido

En este ejemplo, se muestra una solicitud de falla en la que el ID de trabajo no es válido.

Solicitud

Encabezados:

Clave Valor Descripción
Content-Type application/json

Consulta:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Respuesta: Error: ID de trabajo no válido
{
    "message": "Not Found"
}

Código de estado: 404

Cómo agregar y editar usuarios de forma masiva desde un archivo

Encabezados:

Clave Valor Descripción
Content-Type multipart/form-data

Endpoint:

Method: POST
Type: FORM DATA
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/upload

Cuerpo:

Clave Valor Descripción
archivo

Ejemplo de solicitud y respuestas

En las siguientes secciones, se proporcionan ejemplos de solicitudes al extremo.

Se creó el trabajo

En este ejemplo, se muestra cómo enviar un trabajo.

Solicitud

Cuerpo:

Clave Valor Descripción
archivo
Respuesta: Se creó el trabajo
{
    "id": 1,
    "status": "created",
    "link": "https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/1"
}

Código de estado: 200

Continuar

Este extremo de API se usa para continuar un trabajo de ipport que se inició.

Endpoint:

Method: POST
Type: FORM DATA
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/proceed

Encabezados:

Clave Valor Descripción
Content-Type multipart/form-data

Cuerpo:

Clave Valor Descripción
id `[job_id}`

Ejemplo de solicitud y respuestas

En las siguientes secciones, se proporcionan ejemplos de solicitudes al extremo.

La operación se realizó correctamente

En este ejemplo, se muestra un proceso de trabajo exitoso.

Solicitud

Encabezados:

Clave Valor Descripción
Content-Type multipart/form-data

Consulta:

Clave Valor Descripción
id `[job_id}`
Respuesta: La operación se realizó correctamente
{
    "id": 1,
    "status": "valid_scheme",
    "link": "https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/1"
}

Código de estado: 200

Error: Proceed when before validation

En este ejemplo, se muestra un proceso anterior a la finalización de la validación.

Solicitud

Encabezados:

Clave Valor Descripción
Content-Type multipart/form-data

Consulta:

Clave Valor Descripción
id `[job_id}`
Respuesta: Error: Proceed when before validation
{
    "message": "This job cannot proceed update. status: created"
}

Código de estado: 400

Error: Continúa cuando esté en curso

En este ejemplo, se muestra un proceso cuando el trabajo ya está en curso.

Solicitud

Encabezados:

Clave Valor Descripción
Content-Type multipart/form-data

Consulta:

Clave Valor Descripción
id `[job_id}`
Respuesta: Error: Proceed when in progress
{
    "message": "Update is already in progress."
}

Código de estado: 400

Errores de Scheme

Endpoint:

Method: GET
Type: 
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/errors/scheme/​{job_id}​

Ejemplo de solicitud y respuestas

En las siguientes secciones, se proporcionan ejemplos de solicitudes al extremo.

Errores de Scheme

En este ejemplo, se muestra cómo recuperar los errores de esquema.

Solicitud

Cuerpo: Ninguno

Respuesta: Errores de Scheme
[
    {
        "message": "scheme error message 1",
        "column": null,
        "row": 1
    },
    {
        "message": "scheme error message 2",
        "column": null,
        "row": 2
    }
]

Código de estado: 200

Sin errores

En este ejemplo, se muestra cómo recuperar los errores de esquema sin errores.

Solicitud

Cuerpo: Ninguno

Respuesta: Sin errores
[]

Código de estado: 200

Errores de actualización

Endpoint:

Method: GET
Type: 
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/errors/update/{job_id}​

Ejemplo de solicitud y respuestas

En las siguientes secciones, se proporcionan ejemplos de solicitudes al extremo.

Errores de actualización

En este ejemplo, se muestra cómo recuperar los errores de esquema con errores de actualización.

Solicitud

Cuerpo: Ninguno

Respuesta: Errores de actualización
[
    {
        "message": "update error message 1",
        "column": 1,
        "row": 1,
        "error_type": "error"
    },
    {
        "message": "update error message 2",
        "column": null,
        "row": 2,
        "error_type": "error"
    },
    {
        "message": "update warning message 1",
        "column": 3,
        "row": 3,
        "error_type": "warning"
    },
    {
        "message": "update warning message 2",
        "column": null,
        "row": 4,
        "error_type": "warning"
    }
]

Código de estado: 200

Sin errores

En este ejemplo, se muestra cómo recuperar los errores de esquema sin errores.

Solicitud

Cuerpo: Ninguno

Respuesta: Sin errores
[]

Código de estado: 200