Com a nossa integração API, você tem total controle do que a sua Voxuy vai fazer e como ela vai trabalhar. E o melhor, as possibilidades são infinitas! Pra fazer essa integração você vai precisar da ajuda de um desenvolvedor.
Como configurar a Voxuy pra uma integração via API?
Durante a configuração, nós vamos colhendo e anotando alguns dados que você vai precisar pra fazer a integração. Esses dados são:
1. ID do evento (caso seja um evento personalizado)
2. Token API
3. URL para webhook
4. ID do plano que será usado
Bora lá pra configuração!
Selecione o seu produto.
Se o seu produto é de alguma plataforma que já integramos, é só você fazer a integração com a plataforma de vendas que quer, e selecionar o produto na lista.
Se o produto que você quer usar é de uma plataforma que ainda não temos integração, você pode cadastrar ele no atalho "Adicionar Produto".
2. Depois que selecionar o produto, vamos criar os eventos:
a. Clique em "Nova Categoria" e crie os eventos dentro dessas categorias;
b. Nos 3 pontinhos, você pode clicar pra "Alterar nome" do seu grupo e também do seu evento;
💡Uma categoria é simplesmente um método de agrupar logicamente seus eventos pra fins de organização.
3. Copie o ID do evento que você criou e guarde esse número.
4. Agora é só você criar as mensagens pra esse evento e produto que acabou de criar.
5. Copie a URL para webhook na Voxuy.
a. Acesse o menu de Configurações e clique em Integrações;
b. Selecione a opção API Voxuy;
c. Clique em copiar no campo URL para webhook e guarde esse link.
6. Ainda dentro de integrações, clique em copiar no campo do código Token API e guarde esse código.
💡 Se o campo Token API estiver vazio, clique no botão Gerar Novo Token.
7. Agora vamos copiar o ID do plano.
a. Acesse o menu de Configurações e clique em Produtos;
b. Clique no produto que quer integrar;
c. Escolha o plano, copie o ID do plano e guarde esse código.
Agora você tem todos os dados necessários pra fazer a integração via API!
Como fazer uma integração via API?
Depois de fazer todas as configurações dentro da Voxuy, vamos seguir pra parte da integraçã. Caso você não tenha configurado a sua Voxuy ainda, dá uma olhada aqui.
Ah, você vai precisar da ajuda de um desenvolvedor pra fazer essa integração, tá bom?
💡 Lembrando que vamos precisar dos seguintes dados:
1. ID do evento (caso seja um evento personalizado)
2. Token API
3. URL para webhook
4. ID do plano que será usado
Request
Pra enviar um Request para a Voxuy, você vai usar a URL para Webhook que pegamos como parte desse passo a passo aqui.
Esse Request deve ser um POST, e conter o Header Content-Type: application/json
Body
O corpo (dados) do Request que você vai enviar, deve ser um JSON com os campos abaixo.
💡 Obervação importante: todos os campos de valores são em Integer, sem vírgulas. Por exemplo, o valor R$ 69,90 seria enviado como 6990.
Campo | Tipo | Requerido? | Descrição |
apiToken | String | ✓ | Token da API encontrado em Configurações Gerais – API Voxuy – Token API |
id | String | X | Código de venda / ID único dessa transação. Esse é o identificador de uma venda/pedido/item para que seja adicionado ou atualizado. Caso este campo esteja vazio, um código único será atribuido. |
planId | String | ✓ | ID do plano desejado (veja Dados necessários para a API) |
agentEmail | String | X | Caso preenchido, especifica o atendente responsável pelas próximas mensagens desta transação. |
dontCancelPrevious | Boolean | X | Como padrão, a Voxuy irá cancelar e remover do funil todas as mensagens anteriores ao entrar uma nova transação para o mesmo número. Use este campo como true para não cancelar essas mensagens anteriores. Útil se você não quiser tirar ninguém de um funil e está somente enviando uma mensagem avulsa agora. |
value | Integer | X | Valor líquido da venda/pedido. |
freight | Integer | X | Valor do frete. |
freightType | String | X | Tipo do frete, por exemplo, PAC. |
totalValue | Integer | X | Valor total da venda/pedido. |
metadata | Object | X | Campos adicionais que queira usar futuramente como variáveis nas mensagens. |
paymentType | Integer | ✓ | Tipo de pagamento da venda/pedido/item. Veja a tabela Tipos de Pagamento abaixo para possíveis valores. |
status | Integer | ✓ | Status atual da venda/pedido/item. Veja a tabela Status do Pedido abaixo para possíveis valores. |
customEvent | Integer | X | ID do evento, caso esteja colocando esta pessoa em um evento personalizado do funil. |
date | DateTime | X | Data da venda/pedido/item. Este campo deverá ser enviado no formato ISO 8601, em UTC. Exemplo: “2021-05-01T21:00:00Z” (Z para sinalizar UTC) Caso o campo vier em branco (nulo), a data atual (ao receber o webhook) será usada. Obs.: Caso esta data seja anterior à data de criação da licença da Voxuy, não será agendada mensagens manualmente. |
clientName | String | X | Nome do cliente/lead. |
clientEmail | String | X | Email do cliente/lead. |
clientPhoneNumber | String | X | Telefone completo do cliente/lead, incluindo código do país. Exemplo: +5511912341234 |
clientDocument | String | X | CPF ou CNPJ do cliente/lead. |
clientAddress | String | X | Logradouro do endereço do cliente/lead. |
clientAddressNumber | String | X | Número do endereço do cliente/lead. |
clientAddressComp | String | X | Complemento do endereço do cliente/lead |
clientAddressDistrict | String | X | Bairro do cliente/lead |
clientAddressCity | String | X | Cidade do cliente/lead |
clientAddressState | String | X | Estado do cliente/lead |
clientZipCode | String | X | Código Postal do cliente/lead |
checkoutUrl | String | X | URL de checkout para o cliente/lead finalizar ou refazer a compra. |
paymentLine | String | X | Linha digitável do boleto, caso esta compra seja via Boleto. |
boletoUrl | String | X | URL de acesso ao boleto do cliente/lead, caso esta compra seja via Boleto. |
pixQrCode | String | X | QR Code completo do Pix, caso esta compra seja via Pix. |
pixUrl | String | X | URL de acesso aos dados do Pix, caso esta compra seja via Pix. |
fileUrl | String | X | URL para enviar algum arquivo personalizado dessa transação (não esqueça de habilitar a opção na parte “Avançada” do funil ) |
currentShippingEvent | Integer | X | Para logística, o evento atual desta venda. (Ver tabela “Status de Logística” abaixo) |
shipping | Object | X | Dados da última atualização de logística (Ver tabela “Logística” com campos disponíveis) |
Tipos de Pagamento
Nome | Valor | Descrição |
Gratuito | 0 | Usado quando há uma venda mas não tem valor monetário. |
Boleto | 1 | Pedido via boleto. |
Cartão de Crédito | 2 | Pedido via Cartão de Crédito. |
PayPal | 3 | Pedido via PayPal. |
Boleto Parcelado | 4 | Pedido via boleto, de forma parcelada. |
Depósito bancario | 5 | Pedido via depósito bancário. |
Depósito em conta | 6 | Pedido com pagamento usando crédito em conta da plataforma. |
Pix | 7 | Pedido via Pix. |
Nenhum | 99 | Use este valor caso seja um Carrinho Abandonado, Mensagem Externa ou algum Evento Personalizado. |
Status do Pedido
Nome | Valor | Descrição |
Pendente / Aguardando Pagamento | 0 | Pedido em aberto, aguardando pagamento. |
Pagamento Aprovado | 1 | Pagamento foi aprovado e pronto para envio. |
Cancelado | 2 | Pedido cancelado ou com pagamento não aprovado. |
Chargeback | 3 | Pedido com Chargeback |
Estornado | 4 | Cliente foi estornado. |
Em Análise | 5 | Pagamento em análise pela instituição financeira. |
Aguardando Estorno | 6 | Estorno pedido pelo cliente. |
Processando Cartão | 7 | Pagamento em cartão sendo processado. |
Parcialmente Pago | 8 | Valor completo ainda não foi pago |
Bloqueado | 9 | Pedido bloqueado. |
Rejeitado | 10 | Rejeitado, possivelmente por alguma tentativa de fraude |
Duplicado | 11 | Pagamento duplicado |
Carrinho Abandonado | 80 | Também conhecido como Abandono de Checkout. |
Nenhum / Desconhecido | 99 | Use este valor caso esteja usando um evento personalizado. |
Logística
Campo | Tipo | Requerido? | Descrição |
trackingCode | String | X | Código de rastreio |
trackingUrl | String | X | URL para rastreio |
branchName | String | X | Agência ou local em que o produto se encontra |
city | String | X | Cidade em que o produto se encontra |
state | String | X | Estado/UF em que o produto se encontra |
country | String | X | País em que o produto se encontra |
date | String | X | Data e hora da última atualização recebida pela empresa de logística. Este campo deverá ser enviado no formato ISO 8601, em UTC. Exemplo: “2021-05-01T21:00:00Z” (Z para sinalizar UTC) |
Status de Logística
Nome | Valor | Descrição |
Nenhum | 0 | Pedido não possui nenhum status de logística. |
Postado | 1 | O vendedor levou o objeto para a transportadora |
Em Trânsito | 2 | A transportadora está fazendo a logística do objeto |
Retirada | 3 | O cliente precisa retirar o pacote na transportadora |
Alerta | 4 | Ocorreu algum problema com o objeto, como por exemplo, extravio |
Saiu para entrega | 5 | A transportadora está levando o objecto para a residência do cliente |
Entregue | 6 | Objeto recebido pelo cliente |
Exemplo de Request
Este exemplo criará um novo item que vai agendar mensagens do funil personalizado que criamos de teste.
POST https://sistema.voxuy.com/api/<codigo>/webhooks/voxuy/transaction
Headers:
Content-Type: application/json
{"apiToken": "00000000-0000-0000-0000-000000000000",
"id": "<id-do-seu-sistema>",
"planId": "e9b3a0a5-7ad9-4ea9-b7dd-93cfeb",
"value": null,
"freight": null,
"freightType": null,
"totalValue": null,
"metadata": null,
"paymentType": 99,
"status": 99,
"customEvent": 63,
"paymentLine": null,
"date": "2021-05-21T23:59:00Z",
"clientName": "Cliente 1",
"clientEmail": null,
"clientPhoneNumber": "+551199999999",
"clientDocument": null,
"clientAddress": null,
"clientAddressNumber": null,
"clientAddressComp": null,
"clientAddressDistrict": null,
"clientAddressCity": null,
"clientAddressState": null,
"clientAddressCountry": null,
"clientZipCode": null,
"checkoutUrl": null,
"boletoUrl": null,
"pixQrCode": null,
"pixUrl": null
}Resposta (Código 200) – sucesso.
Resposta (Código 200) - sucesso.
{ "Success": true }
Resposta (Código 400 - Bad Request) - quando algum campo enviado for inválido.
{"errors": {
"clientPhoneNumber": [
"The clientPhoneNumber field is required."
]
},
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "0HM8U2U27H831:00000001"
}