API de mappage d’ID externe

  • Rversion finale: Australia
  • Mis à jour 12 mars 2026
  • 7 minutes de lecture

    • Permet aux plateformes CCaaS (Contact Center as a Service) externes de stocker et de récupérer les identificateurs d’acheminement pour ServiceNow les enregistrements.

    Dans le cadre de l’application de stockage Base d’intégration du centre de contact (sn_ct_ctr_it_core), cette API permet aux fournisseurs CCaaS d’obtenir ou de définir des ID externes dans la table Mappages d’ID externes CCaaS [sn_ct_ctr_it_core_ccaas_external_id_mapping]. Cette API se trouve dans l’espace de noms sn_ct_ctr_it_core et nécessite le rôle sn_ct_ctr_it_core.admin.

    Cette API prend en charge les environnements multifournisseurs, ce qui permet aux organisations de s’intégrer simultanément à plusieurs plateformes CCaaS tout en conservant des espaces de noms d’ID d’acheminement distincts pour chaque fournisseur.

    Lorsqu’une plateforme CCaaS (telle que Genesys Cloud, Five9 ou Amazon Connect) achemine un ticket, une tâche ou une interaction vers un agent externe, elle génère un ID d’acheminement unique. Cette API fournit un mécanisme centralisé pour mapper ces ID d’acheminement externes aux enregistrements, permettant un suivi bidirectionnel et une corrélation entre la plateforme CCaaS et ServiceNow.

    Cas d'utilisation
    Corrélation d’acheminement externe
    La plateforme CCaaS génère un ID d’acheminement lorsqu’elle achemine un ticket vers un agent externe. doit stocker cet ID pour corréler les événements, rappels ou mises à jour de statut futurs à partir de la plateforme CCaaS.
    Cette API stocke l’ID d’acheminement externe dans une table de mappage, en l’associant à l’enregistrement et au fournisseur qui l’a généré.
    Suivi bidirectionnel
    Vous devrez peut-être suivre quelle session d’acheminement externe correspond à quel ticket pour le reporting, l’analyse et le dépannage.
    Vous pouvez utiliser cette API pour récupérer les ID d’acheminement externes pour n’importe quel enregistrement, ce qui permet aux tableaux de bord et aux rapports d’afficher l’historique complet des acheminements.
    Flexibilité d’intégration
    Différentes plateformes CCaaS peuvent nécessiter le stockage d’ID d’acheminement pour différentes tables, telles que des tickets, des tâches, des interactions ou des tables personnalisées.
    Cette API accepte tout nom de table valide, ce qui le rend extensible pour des cas d’utilisation futurs. Les points de terminaison peuvent être appelés indépendamment en fonction du workflow.

    Pour plus d’informations sur l’intégration aux systèmes CCaaS, reportez-vous à la section Integrating with contact centers.

    Mappage d’ID externe : GET /sn_ct_ctr_it_core/external_id_mapping/table/{tableName}/documentId/{documentId}

    Récupère le mappage d’ID d’acheminement externe pour un enregistrement spécifique.

    Ce point de terminaison interroge la table de mappage pour trouver l’ID d’acheminement externe qui a été stocké pour un enregistrement et un fournisseur donnés. Utilisez ce point de terminaison pour récupérer l’ID d’acheminement externe qui a été affecté à un enregistrement par une plateforme CCaaS.

    Format d'URL

    URL par défaut : /api/sn_ct_ctr_it_core/external_id_mapping/table/{tableName}/documentId/{documentId}

    Paramètres de demande pris en charge

    Tableau 1. Paramètres de chemin d'accès
    Nom Description
    tableName Requis. Nom ServiceNow de la table contenant l’enregistrement. Peut être n’importe quel nom de table valide. Par exemple, les tables sn_customerservice_case, sn_customerservice_task, d’interaction ou personnalisées.

    Type de données : chaîne
    documentId Requis. La sys_id de l’enregistrement ServiceNow pour lequel récupérer le mappage d’ID externe.

    Type de données : chaîne
    Tableau 2. Paramètres de requête
    Nom Description
    Néant
    Tableau 3. Paramètres du corps de la demande (JSON)
    Nom Description
    Néant

    En-têtes

    Les en-têtes de demande et de réponse suivants s’appliquent uniquement à cette action HTTP ou s’appliquent à cette action d’une manière distincte. Pour obtenir la liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.

    Tableau 4. En-têtes de demandes
    En-tête Description
    Accepter Format de données du corps de la réponse. Types pris en charge : application/json ou application/xml.

    Valeur par défaut : application/json
    Tableau 5. En-têtes de réponses
    En-tête Description
    Néant

    Codes d'état

    Les codes d’état suivants s’appliquent à cette action HTTP. Pour obtenir la liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.

    Tableau 6. Codes d'état
    Code d'état Description
    200 Réussi. La demande a été traitée avec succès.
    400 Demande incorrecte. Un type de demande incorrecte ou mal formé a été détecté.
    401 Non autorisé. Les informations d’identification de l’utilisateur sont incorrectes ou n’ont pas été transmises.
    403 Interdit. L’utilisateur ne dispose pas des droits d’accès à l’enregistrement spécifié.
    404 Introuvable. L’élément demandé est introuvable.
    500 Erreur interne du serveur. Une erreur inattendue s’est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l’erreur.

    Paramètres de corps de réponse (JSON)

    Nom Description
    résultat Objet de résultat contenant des informations sur la demande.

    Type de données : objet

    "result": { 
   "data": "String",
   "message": "String"
}
    résultat.données Données pour le mappage.

    Type de données : objet

    "data": { 
  "document_id": "String", 
  "document_table": "String",
  "external_id": "String",
  "external_provider": "String"
}
    result.data.document_id La sys_id de l’enregistrement ServiceNow AI Platform pour lequel récupérer le mappage d’ID externe.

    Type de données : chaîne
    result.data.document_table Nom ServiceNow AI Platform de la table contenant l’enregistrement.

    Type de données : chaîne
    result.data.external_id L’ID d’acheminement externe de la plateforme CCaaS.

    Nombre maximum de caractères : 200

    Type de données : chaîne
    result.data.external_provider Le sys_id du fournisseur dans la table Fournisseur externe [awa_external_provider].

    Type de données : chaîne
    Résultat.Erreur.Message Si la demande échoue, message expliquant pourquoi la demande a échoué.

    Type de données : chaîne
    résultat.erreur Si la demande échoue, message expliquant pourquoi la demande a échoué.

    Type de données : chaîne
    Résultat.Erreur.Message Si la demande échoue, message expliquant pourquoi la demande a échoué.

    Type de données : chaîne
    résultat.message Message décrivant le résultat de la demande d’API.

    Type de données : chaîne
    résultat.état État de réussite ou d’échec de la demande.
    Valeurs valides :
    • réussite
    • échec

    Type de données : chaîne

    Cet exemple interroge le mappage pour le ticket avec sys_id f584a7b23b3d3e10c524c59a04e45a6f pour trouver quel ID d’acheminement externe a été affecté par la plateforme CCaaS.

    curl "https://instance.service-now.com/api/sn_ct_ctr_it_core/external_id_mapping/table/sn_customerservice_case/documentId/f584a7b23b3d3e10c524c59a04e45a6f" \
--request GET \
--header "Accept:application/json" \
--user 'admin':'admin'

    Corps de la réponse :

    {
  "result": {
    "data": {
      "document_table": "sn_customerservice_case",
      "document_id": "f584a7b23b3d3e10c524c59a04e45a6f",
      "external_id": "200",
      "external_provider": "8b592fb64f140210c0338ef0b1ce0b18"
    }
  }
}

    Mappage d’ID externe : PUT /sn_ct_ctr_it_core/external_id_mapping/table/{tableName}/documentId/{documentId}

    Crée ou met à jour un mappage d’ID d’acheminement externe pour un ServiceNow enregistrement.

    Ce point de terminaison est idempotent, donc l’appeler plusieurs fois avec le même paramètre met à jour le mappage existant plutôt que de créer des mappages en double. Le point de terminaison détermine automatiquement s’il faut insérer un nouveau mappage ou mettre à jour un mappage existant en fonction de la combinaison du nom de table, de l’ID de document et du fournisseur externe.

    Format d'URL

    URL par défaut : /api/sn_ct_ctr_it_core/external_id_mapping/table/{tableName}/documentId/{documentId}

    Paramètres de demande pris en charge

    Tableau 7. Paramètres de chemin d'accès
    Nom Description
    tableName Requis. Nom ServiceNow de la table contenant l’enregistrement. Peut être n’importe quel nom de table valide. Par exemple, les tables sn_customerservice_case, sn_customerservice_task, d’interaction ou personnalisées.

    Type de données : chaîne
    documentId Requis. La sys_id de l’enregistrement ServiceNow pour lequel récupérer le mappage d’ID externe.

    Type de données : chaîne
    Tableau 8. Paramètres de requête
    Nom Description
    Néant
    Tableau 9. Paramètres du corps de la demande (JSON)
    Nom Description
    external_id Requis. ID de l’agent externe du système CCaaS.

    Type de données : chaîne

    Longueur maximale : 200 caractères
    external_provider La sys_id de l’enregistrement du fournisseur à partir de la table Fournisseur externe [awa_external_provider]. Cette action identifie quelle plateforme CCaaS a généré l’ID externe.

    Type de données : chaîne

    En-têtes

    Les en-têtes de demande et de réponse suivants s’appliquent uniquement à cette action HTTP ou s’appliquent à cette action d’une manière distincte. Pour obtenir la liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.

    Tableau 10. En-têtes de demandes
    En-tête Description
    Accepter Format de données du corps de la réponse. Prend uniquement en charge application/json.
    Type de contenu Format des données du corps de la demande. Prend uniquement en charge application/json.
    Tableau 11. En-têtes de réponses
    En-tête Description
    Néant

    Codes d'état

    Les codes d’état suivants s’appliquent à cette action HTTP. Pour obtenir la liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.

    Tableau 12. Codes d'état
    Code d'état Description
    200 Réussi. La demande a été traitée avec succès.
    201 Créé. Le mappage d’ID externe a été créé avec succès, c’est-à-dire qu’un nouveau mappage a été inséré.
    400 Demande incorrecte. Un type de demande incorrecte ou mal formé a été détecté.
    401 Non autorisé. Les informations d’identification de l’utilisateur sont incorrectes ou n’ont pas été transmises.
    403 Interdit.
    Raisons possibles :
    • L’utilisateur ne dispose pas du rôle awa_integration_user.
    • La valeur de la propriété glide.awa.enabled n’est pas vraie. Cette propriété est répertoriée dans la table Propriétés système [sys_property] si le module d’extension Affectation de travail avancée (com.glide.awa) est installé. Pour plus d’informations, voir Composants installés avec Affectation de travail avancée.
    404 Introuvable. L’élément demandé est introuvable.
    500 Erreur interne du serveur. Une erreur inattendue s’est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l’erreur.

    Paramètres de corps de réponse (JSON)

    Nom Description
    résultat Objet de résultat contenant des informations sur la demande.

    Type de données : objet

    "result": { 
   "data": "String",
   "message": "String"
}
    Résultat.Erreur.Message Si la demande échoue, message expliquant pourquoi la demande a échoué.

    Type de données : chaîne
    résultat.erreur Si la demande échoue, message expliquant pourquoi la demande a échoué.

    Type de données : chaîne
    Résultat.Erreur.Message Si la demande échoue, message expliquant pourquoi la demande a échoué.

    Type de données : chaîne
    résultat.message Message décrivant le résultat de la demande d’API.

    Type de données : chaîne
    résultat.état État de réussite ou d’échec de la demande.
    Valeurs valides :
    • réussite
    • échec

    Type de données : chaîne

    Demande cURL

    Cet exemple montre comment stocker un ID externe à partir d’une plateforme CCaaS (identifié par le fournisseur sys_id 8b592fb64f140210c0338ef0b1ce0b18).

    curl "https://instance.service-now.com/api/sn_ct_ctr_it_core/external_id_mapping/table/sn_customerservice_case/documentId/f584a7b23b3d3e10c524c59a04e45a6f" \
--request PUT \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
    \"external_id\": \"200\",
    \"external_provider\": \"8b592fb64f140210c0338ef0b1ce0b18\"
}" \
--user 'admin':'admin'

    Corps de la réponse :

    {
  "result": {
    "message": "External ID mapping record updated for sn_customerservice_case [f584a7b23b3d3e10c524c59a04e45a6f]",
    "status": "success"
  }
}