Endpoints de gerenciamento de usuários em massa

Com os endpoints da API de gerenciamento em massa, é possível criar ou atualizar um grande número de usuários usando a coleção de gerenciamento de usuários em massa.

A API aceita o uso de arquivos JSON. É possível receber dados JSON usando a API de modelo.

Apenas a autenticação api_user é aceita. Você precisa inserir o token de usuário da API na variável de senha. A autenticação legada usando um segredo da empresa não é compatível.

Quando um arquivo JSON é enviado por upload usando a API, um job é criado e valida o esquema do arquivo JSON.

Os endpoints compatíveis com o gerenciamento de usuários em massa incluem o seguinte:

Para adicionar ou atualizar usuários em massa usando a API de usuários em massa, faça o seguinte:

  1. Chame o método Template para receber o objeto de modelo JSON que você usará para gerar o arquivo JSON.

  2. Chame o método Adicionar usuários em massa de um arquivo ou o método Atualizar usuários em massa de um arquivo, dependendo se você está fazendo uma adição ou uma atualização em massa. Isso verifica o esquema do arquivo JSON que você fornece.

  3. Depois que o esquema do arquivo JSON for verificado, chame o método Proceed. Isso inicia o job.

  4. Para determinar o status do job, chame o método Jobs.

Formato de arquivo JSON

Para conseguir o formato de arquivo JSON, chame o método de modelo.

Nome dos campos Valores Obrigatório Validação
e-mail String(Email) Sim Precisa ser um e-mail válido. Precisa ser exclusivo na coluna "E-mail" do arquivo (sem duplicatas). Portanto, apenas uma atualização por endereço de e-mail por arquivo.
new_email String(Email) Não Precisa ser um e-mail válido. Precisa ser exclusivo na coluna "Novo e-mail" do arquivo (sem duplicatas). Portanto, apenas uma atualização por endereço de e-mail por arquivo.
agent_number String Não Uma string sem validação
first_name String Sim String não vazia
last_name String Sim String não vazia
status Ativo, inativo, vazio Não Precisa ser "Ativo", "Inativo" ou vazio
local Uma string que é um nome de local, vazia ou nula Não Precisa corresponder exatamente a um dos locais existentes (sem diferenciar maiúsculas de minúsculas) ou ser nulo ou vazio.
max_chat_limit 1 a X (em que X é o valor configurado), vazio Não Precisa ser de 1 a X (inclusive) ou estar vazio
max_chat_limit_enabled 0, 1, vazio Não Precisa ser 0, 1 ou vazio
papéis name: Role name / value: 0, 1, Empty Não Precisa ser 0, 1 ou vazio
equipes name: Team name / value: 0, 1, Empty Não Precisa ser 0, 1 ou vazio

Quando o método da API de upload de arquivo JSON for concluído, o método da API Proceed poderá ser chamado, e o trabalho de criação ou modificação do usuário será processado.

Os métodos de upload e de continuação são realizados de forma assíncrona pela Contact Center AI Platform (CCAI Platform). Para verificar o status, chame o método jobs e especifique job_id.

Campo de status

O campo status do trabalho pode ter qualquer um dos seguintes valores:

Status do job Descrição
created Um job é criado e aguarda validação.
valid_scheme A validação do Scheme foi concluída e é possível continuar.
invalid_scheme Falha na validação do Scheme. Informações detalhadas podem ser verificadas na API de registro de erros do Scheme.
in_progress Realizando atualização/criação de usuários em massa.
concluídas A atualização/criação de usuários em massa foi concluída.

Modelo

Endpoint:

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

Exemplo de solicitação e respostas

As seções a seguir fornecem exemplos de solicitações ao endpoint.

Acessar modelo

Este exemplo demonstra como recuperar os modelos.

Solicitação

Corpo: nenhum

Resposta: modelo
[
    {
        "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 status:200

Jobs

Endpoint:

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

Exemplo de solicitação e respostas

As seções a seguir fornecem exemplos de solicitações ao endpoint.

Detalhes do job

Este exemplo demonstra como recuperar os detalhes de um job específico. Neste exemplo, o ID do job é 1.

Solicitação

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json

Consulta

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Resposta: detalhes do job
{
    "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 status:200

Lista de jobs

Este exemplo demonstra como receber todos os jobs.

Solicitação

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json

Consulta

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/
Resposta: lista de jobs
[
    {
        "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 status:200

Job criado

Este exemplo demonstra como recuperar os jobs de solicitação de usuário em massa que foram criados.

Solicitação

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json

Consulta

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Resposta: job criado
{
    "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 status:200

Validação de job concluída

Este exemplo demonstra como validar se um job foi concluído com êxito.

Solicitação

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json

Consulta

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Resposta: job validado
{
    "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 status:200

Falha na validação do job

Este exemplo demonstra como determinar que um job falhou.

Solicitação

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json

Consulta

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Resposta: falha na validação do job
{
    "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 status:200

Atualização de vagas

Este exemplo demonstra como determinar que um job está sendo atualizado.

Solicitação

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json

Consulta

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Resposta: atualização de vagas
{
    "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 status:200

A atualização do job foi concluída sem erros

Neste exemplo, mostramos como identificar um job concluído sem erros.

Solicitação

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json

Consulta

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Resposta: atualização de vaga concluída sem erros
{
    "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 status:200

A atualização do job foi concluída com erros

Neste exemplo, mostramos como identificar um job que terminou com erros.

Solicitação

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json

Consulta

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Resposta: Job update finish with errors
{
    "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 status:200

Erro: ID do job inválido

Este exemplo mostra uma solicitação de falha em que o ID do job é inválido.

Solicitação

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json

Consulta

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Resposta: erro: ID do job inválido
{
    "message": "Not Found"
}

Código de status:404

Adicionar e editar usuários em massa de um arquivo

Cabeçalhos:

Chave Valor Descrição
Content-Type multipart/form-data

Endpoint:

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

Corpo:

Chave Valor Descrição
arquivo

Exemplo de solicitação e respostas

As seções a seguir fornecem exemplos de solicitações ao endpoint.

Job criado

Este exemplo mostra como enviar um job.

Solicitação

Corpo:

Chave Valor Descrição
arquivo
Resposta: job criado
{
    "id": 1,
    "status": "created",
    "link": "https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/1"
}

Código de status:200

Continuar

Esse endpoint de API é usado para continuar um job ipport que foi iniciado.

Endpoint:

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

Cabeçalhos:

Chave Valor Descrição
Content-Type multipart/form-data

Corpo:

Chave Valor Descrição
ID `[job_id}`

Exemplo de solicitação e respostas

As seções a seguir fornecem exemplos de solicitações ao endpoint.

Sucesso na ação "Continuar"

Este exemplo mostra um processo de job bem-sucedido.

Solicitação

Cabeçalhos:

Chave Valor Descrição
Content-Type multipart/form-data

Consulta

Chave Valor Descrição
ID `[job_id}`
Resposta: Proceed success
{
    "id": 1,
    "status": "valid_scheme",
    "link": "https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/1"
}

Código de status:200

Erro: continuar antes da validação

Este exemplo mostra uma ação antes da conclusão da validação.

Solicitação

Cabeçalhos:

Chave Valor Descrição
Content-Type multipart/form-data

Consulta

Chave Valor Descrição
ID `[job_id}`
Resposta: Error: Proceed when before validation
{
    "message": "This job cannot proceed update. status: created"
}

Código de status:400

Erro: continuar quando em andamento

Este exemplo mostra um procedimento quando o job já está em andamento.

Solicitação

Cabeçalhos:

Chave Valor Descrição
Content-Type multipart/form-data

Consulta

Chave Valor Descrição
ID `[job_id}`
Resposta: Error: Proceed when in progress
{
    "message": "Update is already in progress."
}

Código de status:400

Erros de Scheme

Endpoint:

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

Exemplo de solicitação e respostas

As seções a seguir fornecem exemplos de solicitações ao endpoint.

Erros de Scheme

Este exemplo mostra como recuperar os erros de esquema.

Solicitação

Corpo: nenhum

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

Código de status:200

Sem erros

Este exemplo mostra como recuperar os erros de esquema sem erros.

Solicitação

Corpo: nenhum

Resposta: sem erros
[]

Código de status:200

Erros de atualização

Endpoint:

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

Exemplo de solicitação e respostas

As seções a seguir fornecem exemplos de solicitações ao endpoint.

Erros de atualização

Este exemplo mostra como recuperar os erros de esquema com erros de atualização.

Solicitação

Corpo: nenhum

Resposta: erros de atualização
[
    {
        "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 status:200

Sem erros

Este exemplo mostra como recuperar os erros de esquema sem erros.

Solicitação

Corpo: nenhum

Resposta: sem erros
[]

Código de status:200