Quer integrar a sua Voxuy com alguma plataforma que não integramos? Com a nossa API, você consegue fazer isso, e tem total controle do que a sua Voxuy vai fazer e como ela vai trabalhar. E o melhor, as possibilidades são infinitas!
Esse tipo de integração não é feita pela Voxuy, por isso, indicamos que você tenha a ajuda de algum desenvolvedor.
Configurando a Voxuy pra uma integração por API
Adicionando produto
1. Clique em Automações → API;
2. Clique na listagem de produtos, e em + Adicionar produto;
3. Dê um nome ao seu produto, e clique em Salvar;
Adicionando categorias e eventos
1. Selecione o produto que criou, e clique em + Nova categoria;
2. Preencha um nome para seu novo evento, que vai ficar dentro da categoria que criou;
As categorias servem apenas pra agrupar os seus eventos.
ID do evento
Cada evento tem um ID, que é um código que identica e diferencia cada um deles. Esse código é extremamente necessário pra integração por API, por isso, copie ele pra seguir para os próximos passos.
Cadastrando um funil de mensagens
1. Com o produto e evento criados, agora você já pode se adiantar e cadastrar as mensagens do seu funil.
URL para webhook e Token para API
1. Clique em , e em Integrações;
2. Pesquise por API VOXUY, e selecione essa opção;
3. Copie os códigos da URL para webhook, e também o
Token API, e guarde para usarmos nas próximas etapas;
Se o campo
Token API estiver vazio, clique no botão Novo Token.
Plan ID
1. Clique em , e em Produtos;
2. Pesquise pelo produto que criou nessa etapa, e clique nele;
3. Clique em + Adicionar plano;
4. Preencha um nome para o novo plano, e clique em Salvar;
5. Clique em ao lado do plano que criou, e clique em
Copiar código do plano.
Agora você tem todos os dados que vai precisar pra fazer a integração via API.
Criando a integração por API
Agora que todas as configurações na sua Voxuy já estão prontinhas, vamos pra segunda etapa da integração que é desenvolver o código dela.
Nessa fase, é muito importante que você tenha um desenvolvedor junto com você.
Vamos precisar dos seguintes dados:
1. ID do evento (caso seja um evento personalizado)
2. Token API
4. ID do plano que será usado
Request
Pra enviar um Request para a Voxuy, você vai usar a URL para Webhook que copiou da sua Voxuy.
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.
Todos os campos de valores são em Integer, sem vírgulas. Por exemplo, o valor R$ 69,90 deve ser enviado como 6990.
Campo | Tipo | Requerido? | Descrição |
apiToken | String | ||
id | String | 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 | |
agentEmail | String | Caso preenchido, especifica o atendente responsável pelas próximas mensagens desta transação. Se não preencher, quando chegar na Voxuy, a transação vai ser direcionada para o atendente que estiver configurado pra esse evento e produto. | |
dontCancelPrevious | Boolean | 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. | |
value | Integer | Valor líquido da venda/pedido. | |
freight | Integer | Valor do frete. | |
freightType | String | Tipo do frete, por exemplo: PAC. | |
totalValue | Integer | Valor total da venda/pedido. | |
metadata | Object | Campos adicionais que queira usar futuramente como variáveis nas mensagens. | |
paymentType | Integer | Tipo de pagamento da venda/pedido/item. | |
status | Integer | Status atual da venda/pedido/item. | |
customEvent | Integer | ||
date | DateTime | 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ão agendada mensagens manualmente. | |
clientName | String | Nome do cliente/lead. | |
clientEmail | String | Email do cliente/lead. | |
clientPhoneNumber | String | Telefone completo do cliente/lead, incluindo código do país. Exemplo: +5511912341234 | |
clientDocument | String | CPF ou CNPJ do cliente/lead. | |
clientAddress | String | Logradouro do endereço do cliente/lead. | |
clientAddressNumber | String | Número do endereço do cliente/lead. | |
clientAddressComp | String | Complemento do endereço do cliente/lead | |
clientAddressDistrict | String | Bairro do cliente/lead | |
clientAddressCity | String | Cidade do cliente/lead | |
clientAddressState | String | Estado do cliente/lead | |
clientZipCode | String | Código Postal do cliente/lead | |
checkoutUrl | String | URL de checkout de vendas, caso necessário. | |
paymentLine | String | Linha digitável do boleto, caso a compra seja via boleto. | |
boletoUrl | String | URL de acesso ao boleto do cliente/lead, caso a compra seja via boleto. | |
pixQrCode | String | QR Code completo do PIX, caso a compra seja via PIX. | |
pixUrl | String | URL de acesso aos dados do PIX, caso a compra seja via PIX. | |
fileUrl | String | URL para enviar algum arquivo personalizado dessa transação (não esqueça de habilitar a opção Avançado do funil de API). | |
currentShippingEvent | Integer | ||
shipping | Object |
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 | Código de rastreio | |
trackingUrl | String | URL para rastreio | |
branchName | String | Agência ou local em que o produto se encontra | |
city | String | Cidade em que o produto se encontra | |
state | String | Estado/UF em que o produto se encontra | |
country | String | País em que o produto se encontra | |
date | String | 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. |
Etiqueta emitida | 8 | Etiqueta do pedido foi emitida pela transportadora. |
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
Esse request de 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"
} Dúvidas frequentes
Como criar variáveis personalizadas com os dados que envio no webhook da minha integração por API?
Pra criar no seu funil, variáveis personalizadas com os dados que você envia no webhook da sua integração por API, é só na mensagem que deseja, clicar em Inserir variável →
Venda →
Campo metadata (API).
Pra que a variável seja preenchida, você precisa enviar no body do seu request as informações que deseja.
metadata | Object | | Campos adicionais que queira usar futuramente como variáveis nas mensagens. |
Essa informação também vai aparecer nas Informações adicionais do evento do cliente no relatório da sua Voxuy.
Como duplicar um funil de API para outro evento do mesmo produto?
1. Clique em ao lado do evento que que copiar, e clique em
Duplicar evento;
2. Selecione o evento que quer enviar a cópia;
3. Clique em Duplicar funil;
4. Prontinho! Seu funil já vai estar duplicado pra outro evento.
Como configurar meu chat pra enviar o funil de API?
Pra Voxuy enviar as mensagens do funil de API, você precisa marcar o produto que criou, e também o evento de API/Customizado no chat do seu atendente. Aqui nesse link explicamos como fazer essa configuração.
