Como fazer solicitações à Voxy Partner API

1. O que é uma solicitação HTTP?

 

A Voxy Partner API é uma API REST que aceita solicitações HTTP e retorna respostas JSON.

Para usar a Voxy Partner API, você precisará ser capaz de fazer solicitações HTTP. HTTP é um protocolo de solicitação/resposta em que o sistema envia uma solicitação à Voxy Partner API, e a API envia uma resposta (por exemplo, “User successfully created” ou “Here is the data you requested”).

Todas as linguagens de programação padrão têm bibliotecas nativas ou de terceiros para permitir as solicitações HTTP.

Se for fazer uma integração de API, você precisará configurar o site, LMS, CMS ou outro sistema para fazer solicitações HTTP à Voxy Partner API para realizar tarefas ou visualizar dados específicos. Entre em contato com o Customer Success Manager para definir as tarefas necessárias para a implementação da sua organização.

Exemplo: A Voxy Partner API tem este ponto periférico: https://app.voxy.com/partner_api/partners/segments/. Se você fizer uma solicitação HTTP GET, o ponto periférico retornará um objeto de dados contendo uma lista de segmentos personalizados criados na sua organização.

 

2. Tipos de solicitações HTTP da API

 

Existem diferentes tipos de solicitações HTTP que devem ser usadas com uma API de acordo com o que você quer fazer. A Voxy Partner API aceita quatro tipos de solicitações: GET, POST, PUT e DELETE.

  • GET é usada para visualizar dados
  • POST é usada para criar ou inserir dados
  • PUT é usada para atualizar ou editar dados
  • DELETE é usada para excluir dados

Todas as linguagens de programação padrão têm bibliotecas nativas ou de terceiros para permitir as solicitações HTTP. Elas também permitem que você especifique o tipo de solicitação que está fazendo.

Exemplo: A Voxy Partner API tem este ponto periférico: https://partners/users/{external_user_id}. Se você fizer uma solicitação HTTP GET a esse ponto periférico, poderá visualizar as informações do perfil do usuário. Se você fizer uma solicitação HTTP POST a esse ponto periférico com os parâmetros mínimos, poderá registrar um novo usuário.

 

3. Exemplo com GET

 

GET é a solicitação HTTP mais usada no desenvolvimento web. Quando você carrega uma URL no navegador, na verdade está fazendo uma solicitação HTTP GET para um servidor, que responde com uma página HTML que é exibida na janela do navegador.

No entanto, em uma API REST como a Voxy Partner API, em vez de uma página HTML, a resposta será um objeto de dados no formato JSON.

Exemplo: A Voxy Partner API tem este ponto periférico: https://partners/users/{external_user_id}. Se você fizer uma solicitação HTTP GET a esse ponto periférico, a API responderá com um objeto de dados JSON que contém as informações do perfil do usuário.

 

4. Exemplo com POST

 

A POST é uma solicitação usada para inserir dados, por exemplo para criar um novo usuário ou um novo segmento personalizado.

Quando você faz uma solicitação POST, normalmente precisa enviar um objeto de dados que contenha as informações necessárias para executar a solicitação, conhecidas como parâmetros. Alguns parâmetros POST são obrigatórios, outros são opcionais.

Por exemplo, para criar um novo usuário com a Voxy Partner API, você precisa incluir os parâmetros first_name, email e native_language no corpo da solicitação. Outros parâmetros, como expiration_date, também podem ser incluídos.

 

5. Como gerar o cabeçalho de autorização necessário

 

Para garantir a segurança e a privacidade, todas as solicitações para a Voxy Partner API exigem um cabeçalho de autorização HTTP válido, caso contrário são negadas.

Para gerar o cabeçalho de autorização necessário, você precisará de uma API Key e de um API Secret que podem ser fornecidos pelo Customer Success Manager da Voxy.

O formato do cabeçalho de autorização é "Voxy {{API_KEY}}:{{REQUEST_SIGNATURE}}", em que:

  1. {{API_KEY}} é a API_KEY,
  2. {{REQUEST_SIGNATURE}} é um hash SHA-256 do API_SECRET, concatenado com os parâmetros com codificação URL, em ordem alfabética.

Um erro comum é uma REQUEST_SIGNATURE gerada incorretamente. Para gerar a assinatura corretamente, o código deve executar as seguintes etapas:

  1. Obter os parâmetros que foram incluídos na solicitação e organizá-los em ordem alfabética por nome.
  2. Utilizar codificação URL nos parâmetros ordenados alfabeticamente.
  3. Criar uma string de texto que seja uma concatenação da assinatura de API e dos parâmetros codificados da URL da etapa 2 (por exemplo, {{API_SECRET}}+{{URL_ENCODED_PARAMETERS}}.
  4. Criptografar a string usando o algoritmo de hash SHA-256.

Como você pode ver, se a solicitação de API incluir parâmetros, eles devem ser usados para gerar a {{REQUEST_SIGNATURE}}.

Se você não gerar o cabeçalho de autorização exatamente da forma descrita acima, sua solicitação será negada pela Voxy Partner API, e você receberá a resposta 401 - Unauthorized, indicando que não foi possível verificar se a solicitação veio de uma fonte confiável.

Estes são alguns exemplos de códigos para gerar os cabeçalhos de autorização.

Para ver exemplos de códigos para gerar o cabeçalho de autorização, acesse nosso repositório de exemplos da Partner API no Github (solicite acesso ao Customer Success Manager da Voxy).  O repositório contém exemplos de códigos para fazer solicitações nas seguintes linguagens:

  • PHP
  • Ruby
  • Python
  • Java
Esse artigo foi útil?
Usuários que acharam isso útil: 0 de 0
Tem mais dúvidas? Submeter um pedido

Comentários

0 comentário

Por favor, entrar para comentar.