Casos de uso comuns de API

Sobre casos de uso de API

Esta página destaca as maneiras como outros clientes da Qualtrics estão aproveitando a API da Qualtrics. Abaixo, você encontrará uma lista de solicitações de API comuns que nossos clientes estão usando e os casos de uso associados a cada solicitação.

Métodos comuns

Serviço Web

A automação da construção de solicitações de API é normalmente feita por um especialista de TI em sua organização, pois esse processo requer a implementação do código personalizado. No entanto, em alguns casos, você pode usar uma pesquisa da Qualtrics para automatizar em vez de código personalizado. As etapas abaixo demonstram como realizar esse processo.

Siga as etapas abaixo assim que sua pesquisa tiver sido criada:

1. Vá até a guia Pesquisa e abra o Fluxo da pesquisa.
   
2. Clique em Adicionar abaixo ou Adicionar um novo elemento aqui.
3. Selecione Serviço Web.
4. Insira o URL para a solicitação de API da seção Definição da documentação.
   
5. Selecione o método que deseja usar (ou seja, GET, PUT, POST ou DELETE).
   Atenção: embora PATCH esteja disponível no elemento Web Service, ele não pode ser usado com o API Qualtrics.
6. Clique em Adicionar um cabeçalho personalizado para enviar ao serviço da Web.
7. Insira X-API-TOKEN no campo Cabeçalho para Web Service e seu token no campo Valor.
   
8. Adicione todos os parâmetros de cabeçalho necessários para sua solicitação de API, clicando no sinal de mais (+).
9. Se você tiver definido o Método como POST ou PUT, clique em Adicionar um parâmetro de corpo para enviar ao serviço da Web e insira todos os parâmetros e valores necessários.
10. Defina o valor para cada parâmetro à direita.
    Qdica: você desejará usar o texto transportado para valores com dados dinâmicos, como Nome, Sobrenome e E-mail.

    

11. Se você estiver usando API v2.x no elemento Web Service, precisará clicar em Adicionar um parâmetro de consulta para enviar ao serviço da Web para adicionar os parâmetros de URL e valores para as solicitações.

JSON

Você pode transferir seus parâmetros como JSON pelo corpo da solicitação. Considere que, ao utilizar este método, você deve indicar um tipo de conteúdo (ou seja, aplicação/json ou texto/json). Este método é normalmente efetuado por um especialista de TI em sua organização, uma vez que este processo requer a implementação do código personalizado.

Cadeia de consulta

URL raiz:

https://levanty.qualtrics.com/WRAPI/ControlPanel/api.phpPara

o primeiro parâmetro adicionado ao URL raiz, inclua um “?” seguido pelo nome do parâmetro, um sinal de igual e o valor do parâmetro (por exemplo, ?Versão=2.4). Adicione todos os parâmetros subsequentes com um E comercial principal “&” (por exemplo, &Request=importPanel).

URL raiz + Parâmetros obrigatórios:

https://survey.qualtrics.com/WRAPI/ControlPanel/api.php?Versão=2.4&Request=importPanel
 &User=kathleenb_gen&Token=12345678901234567890&Format=XML

Continue adicionando ou anexando quaisquer outros parâmetros adicionais ao seu URL seguindo o mesmo processo descrito acima. Depois de incluir todos os parâmetros desejados, você terá uma solicitação concluída.

URL raiz + Parâmetros necessários + Parâmetros adicionais:

https://survey.qualtrics.com/WRAPI/ControlPanel/api.php?Versão=2.4&Request=importPanel
 &User=kathleenb_gen&Token=12345678901234567890&Format=XML
&LibraryID=UR_12345678901234567890&ColumnHeaders=1&Email=3&&1234581234567890&ColumnHeaders=1&Email=3&&1;URL=htt3%367890&ColumnHeaders=1&E-mail=3&&URL=3%3%Ftrics%Fquals3%
Fquals3%32FqualsFquals3%32Fquals

Você pode encontrar mais informações sobre cadeias de consulta em nossa página de suporte Passando informações por meio de cadeias de consulta.

Plataforma de pesquisa

Automatizando a importação de uma lista de contatos

Você pode usar a solicitação Criar importação de contatos para importar lotes de contatos para sua conta da Qualtrics. Por meio dessa solicitação, você pode importar listas JSON de indivíduos do seu CRM para o Qualtrics. Esses contatos podem ser importados carregando um arquivo JSON e definindo o parâmetro de cabeçalho Tipo de conteúdo como dados de várias partes/formulários, ou incluindo os contatos no corpo da solicitação e definindo o Tipo de conteúdo como aplicativo/json.

Automatização da criação de um contato

Em vez de atualizar manualmente as listas de contatos com novos membros de contato, você pode automatizar o processo usando a solicitação Criar contato. Essa solicitação adiciona um novo contato a uma lista de contatos existente. Para esta solicitação, você precisará da ID da lista de destinatários e de quaisquer outros campos que gostaria de adicionar ao contato. Eles precisarão ser passados pelo corpo da solicitação, definindo Content-Type para application/json.

Gerando seus próprios links individuais

Você pode precisar distribuir sua pesquisa por meio de um correio interno em vez do correio da Qualtrics. Com a API da Qualtrics, você pode criar Links individuais que rastreiam as informações pessoais de um entrevistado sem precisar usar o correio da Qualtrics.

Para realizar essa tarefa, você precisará usar duas solicitações de API: Criar links de distribuição e distribuição. Antes de começar, você precisará importar uma lista de contatos para a Qualtrics manualmente ou usando a solicitação de API Criar importação de contatos.

Os parâmetros de interesse para a solicitação Criar ligações de distribuição e distribuição são:

• ID da lista de destinatários (cada distribuição está vinculada a uma lista de destinatários)
• ID da pesquisa
• Descrição (o nome da distribuição)
• Ação (o valor aqui precisa ser CreateDistribution)

Automatização do download de dados em preparação para importação no CRM

Se você precisar de dados de muitas pesquisas diariamente, pode usar nossa API para obter respostas. A API v3 usa uma série de três solicitações para obter dados:

• Criar exportação de resposta: esta solicitação inicia o processo de exportação e é usada para especificar o formato do arquivo e outras preferências. Isso retornará um ID de exportação de resposta.
• Obter progresso da exportação de resposta: esta solicitação é usada para verificar o andamento da exportação usando o ID de exportação de resposta fornecido na primeira solicitação. Assim que a porcentagem de conclusão chegar a 100, você pode usar a última solicitação para obter o arquivo.
• Obter arquivo de exportação de resposta: assim que o arquivo estiver pronto, você pode usar esta solicitação para baixá-lo. Ele exportará como um arquivo compactado. Observe que, embora a maioria das solicitações de API funcione quando a ID do datacenter não estiver correta no URL, esta solicitação não funcionará. Certifique-se de usar o ID do datacenter correto nesta solicitação.

Esta sequência de solicitações baixa seus dados brutos, facilitando a obtenção de seus dados e, em seguida, importando essas respostas para seu CRM, data warehouse, etc.

Diretório XM

Atualizando um contato (Listar contatos do diretório e Atualizar contato do diretório)

Por vezes, você pode querer atualizar um contato por meio da API. Para isso, você precisará do ID de contato do contato. A solicitação da API Listar contatos do diretório permite que você procure o ID de contato de um contato, que você pode usar para solicitações de API posteriores. Primeiro explicaremos a solicitação da API Listar contatos do diretório e, em seguida, Atualizar contato do diretório.

Tudo o que você precisará para a solicitação de contatos do diretório de lista é o ID do diretório. O resultado para a solicitação de Contatos do Diretório de Listas será receber o ID de Contato do contato para que você possa utilizá-lo para solicitações como Atualizar Contato do Diretório.

Existem dois parâmetros principais de interesse para a solicitação de contato do diretório de atualização: ID do diretório e ID do contato. Como resultado da solicitação de contato do diretório de atualização, o contato especificado será atualizado com as informações que você alterou com base nos parâmetros da sua solicitação.

Guias de solução API

Você pode encontrar vários guias de solução para Gerenciamento de pesquisas, Gerenciamento de usuários, Gerenciamento de grupos de usuários e Obtendo respostas à pesquisa em nosso site de documentação da API v3.