Points de terminaison pour la gestion globale des utilisateurs

Les points de terminaison de l'API de gestion groupée vous permettent de créer ou de mettre à jour un grand nombre d'utilisateurs grâce à la collection de gestion groupée des utilisateurs.

L'API est compatible avec les fichiers JSON. Vous pouvez obtenir des données JSON à l'aide de l'API Templates.

Seule l'authentification api_user est acceptée. Vous devez saisir le jeton utilisateur de l'API dans la variable de mot de passe. L'ancienne authentification à l'aide d'un code secret d'entreprise n'est pas acceptée.

Lorsqu'un fichier JSON est importé via l'API d'importation, un job est créé et valide le schéma du fichier JSON.

Les points de terminaison compatibles avec la gestion groupée des utilisateurs sont les suivants :

Pour ajouter ou modifier des utilisateurs de manière groupée à l'aide de l'API Bulk User, procédez comme suit :

  1. Appelez la méthode Template pour obtenir l'objet de modèle JSON que vous utiliserez pour générer le fichier JSON.

  2. Appelez la méthode Bulk add users from file (Ajouter des utilisateurs de manière groupée à partir d'un fichier) ou Bulk update users from file (Mettre à jour des utilisateurs de manière groupée à partir d'un fichier), selon que vous souhaitez ajouter ou mettre à jour des utilisateurs de manière groupée. Cela permet de vérifier le schéma du fichier JSON que vous fournissez.

  3. Une fois le schéma du fichier JSON vérifié, appelez la méthode Proceed. La tâche démarre.

  4. Pour déterminer l'état du job, appelez la méthode Jobs.

Format des fichiers JSON

Vous pouvez obtenir le format de fichier JSON en appelant la méthode de modèle.

Nom du ou des champs Valeurs Obligatoire Validation
e-mail String(Email) Oui Veuillez saisir une adresse e-mail valide. Doit être unique dans le fichier au niveau de la colonne "Adresse e-mail" (pas de doublons). Par conséquent, une seule mise à jour par adresse e-mail et par fichier
new_email String(Email) Non Veuillez saisir une adresse e-mail valide. Doit être unique dans la colonne "Nouvelle adresse e-mail" du fichier (pas de doublons). Vous ne pouvez donc effectuer qu'une seule mise à jour par adresse e-mail et par fichier.
agent_number Chaîne Non Chaîne sans validation
first_name Chaîne Oui Chaîne non vide
last_name Chaîne Oui Chaîne non vide
état Actif, Inactif, Vide Non Doit être "Active", "Inactive" ou vide
emplacement Chaîne correspondant à un nom de lieu, vide ou nulle Non Doit correspondre exactement à l'un des emplacements existants (sans tenir compte de la casse), ou être défini sur "Null" ou être vide
max_chat_limit 1 à X (où X est la valeur configurée), vide Non Doit être compris entre 1 et X (inclus) ou être vide
max_chat_limit_enabled 0, 1, Vide Non Doit être égal à 0, 1 ou être vide
rôles name: Role name / value: 0, 1, Empty Non Doit être égal à 0, 1 ou être vide
équipes name: Team name / value: 0, 1, Empty Non Doit être égal à 0, 1 ou être vide

Une fois la méthode d'API d'importation de fichier JSON exécutée, la méthode d'API "Proceed" peut être appelée, et la création ou la modification de l'utilisateur est alors traitée.

Les méthodes d'importation et de traitement sont exécutées de manière asynchrone par Contact Center AI Platform (CCAI Platform). Vous pouvez vérifier l'état en appelant la méthode jobs et en spécifiant job_id.

Champ "État"

Le champ status du job peut présenter l'une des valeurs suivantes :

État du job Description
créé Une tâche est créée et en attente de validation.
valid_scheme La validation du Scheme a réussi et la procédure peut se poursuivre.
invalid_scheme Échec de la validation du Scheme. Vous pouvez consulter des informations détaillées à l'aide de l'API de journal d'erreurs du Scheme.
in_progress Effectuer une mise à jour ou une création groupée d'utilisateurs
terminés Mise à jour/création groupée d'utilisateurs terminée.

Modèle

Point de terminaison :

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

Exemple de requête et de réponses

Les sections suivantes fournissent des exemples de requêtes au point de terminaison.

Obtenir un modèle

Cet exemple montre comment récupérer les modèles.

Requête

Corps : aucun

Réponse : modèle
[
    {
        "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
            }
        ]
    }
]

Code d'état : 200

Jobs

Point de terminaison :

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

Exemple de requête et de réponses

Les sections suivantes fournissent des exemples de requêtes au point de terminaison.

Détails de la tâche

Cet exemple montre comment récupérer les détails d'une tâche spécifique. Dans cet exemple, l'ID du job est 1.

Requête

En-têtes

Clé Valeur Description
Content-Type application/json

Requête

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Réponse : Détails de la tâche
{
    "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": []
}

Code d'état : 200

Liste des jobs

Cet exemple montre comment obtenir tous les jobs.

Requête

En-têtes

Clé Valeur Description
Content-Type application/json

Requête

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/
Réponse : liste des tâches
[
    {
        "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": []
    }
]

Code d'état : 200

Tâche créée

Cet exemple montre comment récupérer les tâches de requête utilisateur groupées qui ont été créées.

Requête

En-têtes

Clé Valeur Description
Content-Type application/json

Requête

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Réponse : Tâche créée
{
    "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": []
}

Code d'état : 200

Validation réussie du job

Cet exemple montre comment valider la réussite d'un job.

Requête

En-têtes

Clé Valeur Description
Content-Type application/json

Requête

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Réponse : validation de la tâche réussie
{
    "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": []
}

Code d'état : 200

Échec de la validation du job

Cet exemple montre comment déterminer qu'une tâche a échoué.

Requête

En-têtes

Clé Valeur Description
Content-Type application/json

Requête

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Réponse : Échec de la validation du 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": []
}

Code d'état : 200

Mise à jour des tâches

Cet exemple montre comment déterminer qu'un job est en cours de mise à jour.

Requête

En-têtes

Clé Valeur Description
Content-Type application/json

Requête

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Réponse : mise à jour de la tâche
{
    "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": []
}

Code d'état : 200

Mise à jour de l'offre d'emploi terminée sans erreur

Dans cet exemple, nous montrons comment identifier une tâche terminée sans erreur.

Requête

En-têtes

Clé Valeur Description
Content-Type application/json

Requête

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Réponse : Mise à jour de l'emploi terminée sans erreurs
{
    "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": []
}

Code d'état : 200

Mise à jour du job terminée avec des erreurs

Cet exemple montre comment identifier une tâche qui s'est terminée avec des erreurs.

Requête

En-têtes

Clé Valeur Description
Content-Type application/json

Requête

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Réponse : Mise à jour du job terminée avec des erreurs
{
    "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"
    ]
}

Code d'état : 200

Erreur : ID de tâche non valide

Cet exemple montre une demande d'échec lorsque l'ID du job n'est pas valide.

Requête

En-têtes

Clé Valeur Description
Content-Type application/json

Requête

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Réponse : Erreur : ID de tâche non valide
{
    "message": "Not Found"
}

Code d'état : 404

Ajouter et modifier des utilisateurs de manière groupée à partir d'un fichier

En-têtes

Clé Valeur Description
Content-Type multipart/form-data

Point de terminaison :

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

Corps :

Clé Valeur Description
fichier

Exemple de requête et de réponses

Les sections suivantes fournissent des exemples de requêtes au point de terminaison.

Tâche créée

Cet exemple montre comment envoyer un job.

Requête

Corps :

Clé Valeur Description
fichier
Réponse : Tâche créée
{
    "id": 1,
    "status": "created",
    "link": "https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/1"
}

Code d'état : 200

Continuer

Ce point de terminaison de l'API permet de poursuivre un job ipport qui a été démarré.

Point de terminaison :

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

En-têtes

Clé Valeur Description
Content-Type multipart/form-data

Corps :

Clé Valeur Description
id `[job_id}`

Exemple de requête et de réponses

Les sections suivantes fournissent des exemples de requêtes au point de terminaison.

Poursuite réussie

Cet exemple montre une procédure de job réussie.

Requête

En-têtes

Clé Valeur Description
Content-Type multipart/form-data

Requête

Clé Valeur Description
id `[job_id}`
Réponse : Procéder à la réussite
{
    "id": 1,
    "status": "valid_scheme",
    "link": "https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/1"
}

Code d'état : 200

Erreur : Poursuivre avant la validation

Cet exemple montre une procédure avant la validation.

Requête

En-têtes

Clé Valeur Description
Content-Type multipart/form-data

Requête

Clé Valeur Description
id `[job_id}`
Réponse : Erreur : Procéder avant la validation
{
    "message": "This job cannot proceed update. status: created"
}

Code d'état : 400

Erreur : Poursuivre quand l'opération est en cours

Cet exemple montre une poursuite lorsque le job est déjà en cours.

Requête

En-têtes

Clé Valeur Description
Content-Type multipart/form-data

Requête

Clé Valeur Description
id `[job_id}`
Réponse : Erreur : Continuer quand l'opération est en cours
{
    "message": "Update is already in progress."
}

Code d'état : 400

Erreurs de Scheme

Point de terminaison :

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

Exemple de requête et de réponses

Les sections suivantes fournissent des exemples de requêtes au point de terminaison.

Erreurs de Scheme

Cet exemple montre comment récupérer les erreurs de schéma.

Requête

Corps : aucun

Réponse : erreurs de Scheme
[
    {
        "message": "scheme error message 1",
        "column": null,
        "row": 1
    },
    {
        "message": "scheme error message 2",
        "column": null,
        "row": 2
    }
]

Code d'état : 200

Aucune erreur

Cet exemple montre comment récupérer les erreurs de schéma sans aucune erreur.

Requête

Corps : aucun

Réponse : Aucune erreur
[]

Code d'état : 200

Erreurs de mise à jour

Point de terminaison :

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

Exemple de requête et de réponses

Les sections suivantes fournissent des exemples de requêtes au point de terminaison.

Erreurs de mise à jour

Cet exemple montre comment récupérer les erreurs de schéma avec les erreurs de mise à jour.

Requête

Corps : aucun

Réponse : Erreurs de mise à jour
[
    {
        "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"
    }
]

Code d'état : 200

Aucune erreur

Cet exemple montre comment récupérer les erreurs de schéma sans aucune erreur.

Requête

Corps : aucun

Réponse : Aucune erreur
[]

Code d'état : 200