API de mapeamento de ID externa

  • Versão de lançamento: Australia
  • Atualizado 12 de mar. de 2026
  • 7 min. de leitura

    • Permite que plataformas externas de Contact Center como serviço (CCaaS) armazenem e recuperem identificadores de roteamento ServiceNow registros.

    Como parte da aplicação de armazenamento Núcleo de integração do contact center (sn_ct_ctr_it_core), esta API permite que os provedores de CCaaS obtenham ou definam IDs externas na tabela Mapeamentos de ID externo de CCaaS [sn_ct_ctr_it_core_ccaas_external_id_mapping]. Esta API está no namespace sn_ct_ctr_it_core e requer a função sn_ct_ctr_it_core.admin.

    Esta API é compatível com ambientes de vários provedores, permitindo que as organizações se integrem a várias plataformas CCaaS simultaneamente, mantendo namespaces de ID de roteamento separados para cada provedor.

    Quando uma plataforma de CCaaS (como Genesys Cloud, Five9 ou Amazon Connect) roteia um caso, tarefa ou interação para um agente externo, ela gera um ID de roteamento exclusivo. Esta API fornece um mecanismo centralizado para mapear esses IDs de roteamento externos para registros, permitindo o acompanhamento bidirecional e a correlação entre a plataforma CCaaS e. ServiceNow.

    Casos de uso
    Correlação de roteamento externo
    A plataforma CCaaS gera um ID de roteamento quando roteia um caso para um agente externo. Deve armazenar este ID para correlacionar eventos futuros, retornos de chamada ou atualizações de status da plataforma CCaaS.
    Esta API armazena o ID de roteamento externo em uma tabela de mapeamento, associando-o ao registro e ao provedor que o gerou.
    Rastreamento bidirecional
    Pode ser necessário rastrear qual sessão de roteamento externo corresponde a qual caso para geração de relatórios, análise e solução de problemas.
    Você pode usar esta API para recuperar IDs de roteamento externos para qualquer registro, permitindo que painéis e relatórios mostrem o histórico de roteamento completo.
    Flexibilidade de integração
    Diferentes plataformas de CCaaS podem exigir o armazenamento de IDs de roteamento para tabelas diferentes, como casos, tarefas, interações ou tabelas personalizadas.
    Esta API aceita qualquer nome de tabela válido, tornando-a extensível para casos de uso futuros. Os endpoints podem ser chamados independentemente, dependendo do fluxo de trabalho.

    Para obter mais informações sobre integração com sistemas CCaaS, consulte Integrating with contact centers.

    Mapeamento de ID externo - OBTER /sn_ct_ctr_it_core/external_id_mapping/table//documentId/

    Recupera o mapeamento de ID de roteamento externo para um registro específico.

    Este endpoint consulta a tabela de mapeamento para encontrar o ID de roteamento externo que foi armazenado para um determinado registro e provedor. Use este endpoint para recuperar o ID de roteamento externo que foi atribuído a um registro por uma plataforma de CCaaS.

    Formato de URL

    URL padrão: /api/sn_ct_ctr_it_core/external_id_mapping/table/

    Parâmetros de solicitação compatíveis

    Tabela 1. Parâmetros de caminho
    Nome Descrição
    tableName Necessário. . ServiceNow nome da tabela que contém o registro. Pode ser qualquer nome de tabela válido. Por exemplo, sn_customerservice_case, sn_customerservice_task, interaction ou tabelas personalizadas.

    Tipo de dados: Cadeia de caracteres
    documentId Necessário. O sys_id do ServiceNow Registro para o qual recuperar o mapeamento de ID externo.

    Tipo de dados: Cadeia de caracteres
    Tabela 2. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 3. Solicitar parâmetros do corpo (JSON)
    Nome Descrição
    Nenhum(a)

    Cabeçalhos

    Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos da REST API compatíveis .

    Tabela 4. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: application/jsonou application/xml.

    Padrão: application/json
    Tabela 5. Cabeçalhos de resposta
    Cabeçalho Descrição
    Nenhum(a)

    Códigos de status

    Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de possíveis códigos de status usados na REST API, consulte REST API códigos de resposta HTTP .

    Tabela 6. Códigos de status
    Código de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    400 Solicitação Incorreta. Um tipo de solicitação incorreto ou uma solicitação malformada foi detectada.
    401 Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas.
    403 Proibido. O usuário não tem direitos de acesso ao registro especificado.
    404 Não encontrado. O item solicitado não foi encontrado.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro.

    Parâmetros do corpo da resposta (JSON)

    Nome Descrição
    resultado Objeto de resultado que contém informações sobre a solicitação.

    Tipo de dados: Objeto

    "result": { 
   "data": "String",
   "message": "String"
}
    resultado.dados Dados para o mapeamento.

    Tipo de dados: Objeto

    "data": { 
  "document_id": "String", 
  "document_table": "String",
  "external_id": "String",
  "external_provider": "String"
}
    result.data.document_id O sys_id do ServiceNow AI Platform Registro para o qual recuperar o mapeamento de ID externo.

    Tipo de dados: Cadeia de caracteres
    result.data.document_table . ServiceNow AI Platform nome da tabela que contém o registro.

    Tipo de dados: Cadeia de caracteres
    result.data.external_id O ID de roteamento externo da plataforma CCaaS.

    Máximo de caracteres: 200

    Tipo de dados: Cadeia de caracteres
    resultado.data.external_provider O sys_id do provedor da tabela Provedor externo [awa_external_provider].

    Tipo de dados: Cadeia de caracteres
    mensagem.resultado.erro.mensagem Se a solicitação falhar, mensagem explicando o motivo da falha na solicitação.

    Tipo de dados: Cadeia de caracteres
    erro.resultado Se a solicitação falhar, mensagem explicando o motivo da falha na solicitação.

    Tipo de dados: Cadeia de caracteres
    mensagem.resultado.erro.mensagem Se a solicitação falhar, mensagem explicando o motivo da falha na solicitação.

    Tipo de dados: Cadeia de caracteres
    mensagem.resultado Mensagem que descreve o resultado da solicitação de API.

    Tipo de dados: Cadeia de caracteres
    status.resultado Status de sucesso ou falha da solicitação.
    Valores válidos:
    • êxito
    • falha

    Tipo de dados: Cadeia de caracteres

    Este exemplo consulta o mapeamento do caso com sys_id f584a7b23b3d3e10c524c59a04e45a6f Para descobrir qual ID de roteamento externo foi atribuído pela plataforma 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'

    Corpo da resposta:

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

    Mapeamento de ID externo - COLOQUE /sn_ct_ctr_it_core/external_id_mapping/table//documentId/

    Cria ou atualiza um mapeamento de ID de roteamento externo para um ServiceNow registro.

    Este endpoint é idempotente, portanto chamá-lo várias vezes com o mesmo parâmetro atualiza o mapeamento existente em vez de criar mapeamentos duplicados. O endpoint determina automaticamente se um novo mapeamento deve ser inserido ou atualizado um existente com base na combinação de nome da tabela, ID do documento e provedor externo.

    Formato de URL

    URL padrão: /api/sn_ct_ctr_it_core/external_id_mapping/table/

    Parâmetros de solicitação compatíveis

    Tabela 7. Parâmetros de caminho
    Nome Descrição
    tableName Necessário. . ServiceNow nome da tabela que contém o registro. Pode ser qualquer nome de tabela válido. Por exemplo, sn_customerservice_case, sn_customerservice_task, interaction ou tabelas personalizadas.

    Tipo de dados: Cadeia de caracteres
    documentId Necessário. O sys_id do ServiceNow Registro para o qual recuperar o mapeamento de ID externo.

    Tipo de dados: Cadeia de caracteres
    Tabela 8. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 9. Solicitar parâmetros do corpo (JSON)
    Nome Descrição
    external_id Necessário. ID do agente externo do sistema CCaaS.

    Tipo de dados: Cadeia de caracteres

    Tamanho máximo: 200 caracteres
    external_provider O sys_id do registro do provedor da tabela Provedor externo [awa_external_provider]. Isso identifica qual plataforma de CCaaS gerou o ID externo.

    Tipo de dados: Cadeia de caracteres

    Cabeçalhos

    Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos da REST API compatíveis .

    Tabela 10. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Oferece suporte somente a application/json.
    Tipo de conteúdo Formato de dados do corpo da solicitação. Oferece suporte somente a application/json.
    Tabela 11. Cabeçalhos de resposta
    Cabeçalho Descrição
    Nenhum(a)

    Códigos de status

    Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de possíveis códigos de status usados na REST API, consulte REST API códigos de resposta HTTP .

    Tabela 12. Códigos de status
    Código de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    201 Criado. O mapeamento de ID externo foi criado com sucesso, ou seja, um novo mapeamento foi inserido.
    400 Solicitação Incorreta. Um tipo de solicitação incorreto ou uma solicitação malformada foi detectada.
    401 Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas.
    403 Proibido.
    Possíveis motivos:
    • O usuário não tem a função awa_integration_user.
    • O valor da propriedade glide.awa.enabled não é verdadeiro . Esta propriedade será listada na tabela Propriedade do sistema [sys_property] se o plug-in Atribuição de trabalho avançada (com.glide.awa) estiver instalado. Para obter mais informações, consulte Componentes instalados com atribuição de trabalho avançada .
    404 Não encontrado. O item solicitado não foi encontrado.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro.

    Parâmetros do corpo da resposta (JSON)

    Nome Descrição
    resultado Objeto de resultado que contém informações sobre a solicitação.

    Tipo de dados: Objeto

    "result": { 
   "data": "String",
   "message": "String"
}
    mensagem.resultado.erro.mensagem Se a solicitação falhar, mensagem explicando o motivo da falha na solicitação.

    Tipo de dados: Cadeia de caracteres
    erro.resultado Se a solicitação falhar, mensagem explicando o motivo da falha na solicitação.

    Tipo de dados: Cadeia de caracteres
    mensagem.resultado.erro.mensagem Se a solicitação falhar, mensagem explicando o motivo da falha na solicitação.

    Tipo de dados: Cadeia de caracteres
    mensagem.resultado Mensagem que descreve o resultado da solicitação de API.

    Tipo de dados: Cadeia de caracteres
    status.resultado Status de sucesso ou falha da solicitação.
    Valores válidos:
    • êxito
    • falha

    Tipo de dados: Cadeia de caracteres

    Solicitação de curl

    Este exemplo mostra como armazenar um ID externo de uma plataforma CCaaS (identificada pelo sys_id do provedor 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'

    Corpo da resposta:

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