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

3. 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 Gerar 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 nos 3 pontinhos 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ê.

💡 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 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.

💡 Obervação importante: 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	✓	Token da 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
agentEmail	String	X	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	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.
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.
status	Integer	✓	Status atual da venda/pedido/item.
customEvent	Integer	X	ID do evento
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ão 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 de vendas, caso necessário.
paymentLine	String	X	Linha digitável do boleto, caso a compra seja via boleto.
boletoUrl	String	X	URL de acesso ao boleto do cliente/lead, caso a compra seja via boleto.
pixQrCode	String	X	QR Code completo do PIX, caso a compra seja via PIX.
pixUrl	String	X	URL de acesso aos dados do PIX, caso a 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 Avançado do funil de API).
currentShippingEvent	Integer	X	Evento atual de logística da venda
shipping	Object	X	Dados da última atualização de logística

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

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.

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 nos 3 pontinhos 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.