Documentação API
Request
Para enviar um Request para a Voxuy, você usará a URL para Webhook (Veja a página Dados necessários para a API para mais informações).
Esse Request deve ser um POST, e conter o Header Content-Type: application/json
Body
O corpo (dados) do Request que você enviará deve ser um JSON com os seguintes campos:
*Obs: 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 | Caso preenchido, especifica o atendente responsável pelas próximas mensagens desta transação. | |
| 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. Ú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. |
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 |
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 | 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) |
Exemplo de Request
Este exemplo criará um novo item que 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.
{ "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"
}Actualizado em: 14/07/2022