Documentação da API de Integração com a Ubitracker
Visão Geral
Esta documentação descreve como integrar sua aplicação com a Ubitracker para envio de dados de vendas através de webhooks. A integração permite que sua aplicação envie informações detalhadas sobre transações de vendas para a plataforma Ubitracker, que irá processar e exibir esses dados em seus painéis e relatórios.
Requisitos da Integração
Para integrar sua aplicação com a Ubitracker, você precisará:
- Desenvolver uma API que envie webhooks para a Ubitracker
- Seguir o padrão de corpo de requisição especificado
- Configurar a integração no app da Ubitracker
- Utilizar um token de autenticação para validação de segurança
Estrutura do Webhook
Ao enviar dados para a Ubitracker, sua aplicação deve seguir a seguinte estrutura de corpo de requisição:
Campo | Tipo | Obrigatório | Descrição |
---|---|---|---|
orderId | string | Não | Identificador único do pedido |
status | string | Sim | Status atual da transação |
orderBump | boolean | Não | Indica se houve um complemento de pedido |
purchaseDate | Date | Sim | Data e hora da compra |
name | string | Sim | Nome do cliente |
phone | string | Sim | Telefone do cliente |
string | Sim | Email do cliente | |
product | string | Sim | Nome do produto vendido |
productId | string | Sim | Identificador único do produto |
city | string | Não | Cidade do cliente |
state | string | Não | Estado do cliente |
country | string | Não | País do cliente |
zipCode | string | Não | CEP do cliente |
src | string | Não | Fonte da venda |
paymentMethod | string | Sim | Método de pagamento utilizado |
currency | string | Não | Moeda utilizada na transação |
installments | number | Sim | Número de parcelas |
offer | number | Sim | Valor da oferta |
fee | number | Sim | Taxa cobrada |
commission | number | Sim | Valor da comissão |
url | string | Não | URL relacionada à venda |
campaign | string | Não | Nome da campanha de marketing |
origin | string | Não | Origem da venda |
source | string | Não | Fonte de tráfego |
medium | string | Não | Canal de marketing |
term | string | Não | Termos de busca utilizados |
content | string | Não | Conteúdo específico da campanha |
token | string | Sim | Token de autenticação para validação de segurança |
Implementação da API
Abaixo você encontrará um exemplo de como implementar uma API usando Node.js que envia webhooks para a Ubitracker.
// Exemplo de API para integração com Ubitracker usando Node.js com Express
const express = require('express');
const axios = require('axios');
const bodyParser = require('body-parser');
const { v4: uuidv4 } = require('uuid');
const app = express();
app.use(bodyParser.json());
// Configurações da integração
const UBITRACKER_WEBHOOK_URL = 'https://api-ubitracker-com-br-production.up.railway.app/v1/webhooks/payments/standart/[projectId]';
const UBITRACKER_INTEGRATION_TOKEN = 'seu-token-de-integracao-aqui'; // Token configurado no painel da Ubitracker
/**
* Função para enviar dados de venda para a Ubitracker
* @param {Object} saleData - Dados da venda a serem enviados
* @returns {Promise} - Resultado da requisição
*/
async function sendSaleToUbitracker(saleData) {
try {
// Adiciona o token de autenticação
const webhookData = {
...saleData,
token: UBITRACKER_INTEGRATION_TOKEN
};
// Envia os dados para a Ubitracker
const response = await axios.post(UBITRACKER_WEBHOOK_URL, webhookData, {
headers: {
'Content-Type': 'application/json'
}
});
console.log('Dados enviados com sucesso para Ubitracker:', response.data);
return response.data;
} catch (error) {
console.error('Erro ao enviar dados para Ubitracker:', error.message);
throw error;
}
}
// Rota para processar uma nova venda e enviar para Ubitracker
app.post('/api/sales', async (req, res) => {
try {
// Captura os dados da requisição
const {
orderId = uuidv4(), // Gera um ID se não for fornecido
status,
orderBump,
name,
phone,
email,
product,
productId,
city,
state,
country,
zipCode,
src,
paymentMethod,
currency,
installments,
offer,
fee,
commission,
url,
campaign,
origin,
source,
medium,
term,
content
} = req.body;
// Valida os campos obrigatórios
if (!status || !name || !phone || !email || !product || !productId ||
!paymentMethod || !installments || offer === undefined ||
fee === undefined || commission === undefined) {
return res.status(400).json({ error: 'Campos obrigatórios ausentes.' });
}
// Prepara os dados para envio ao webhook
const webhookBody = {
orderId,
status,
orderBump,
purchaseDate: new Date(),
name,
phone,
email,
product,
productId,
city,
state,
country,
zipCode,
src,
paymentMethod,
currency,
installments,
offer,
fee,
commission,
url,
campaign,
origin,
source,
medium,
term,
content
};
// Envia os dados para a Ubitracker
const ubitrackerResponse = await sendSaleToUbitracker(webhookBody);
// Retorna o sucesso com os dados enviados
res.status(200).json({
success: true,
message: 'Venda registrada e enviada para Ubitracker com sucesso',
data: {
orderId: webhookBody.orderId,
ubitrackerResponse
}
});
} catch (error) {
console.error('Erro ao processar venda:', error);
res.status(500).json({
success: false,
message: 'Erro ao processar venda',
error: error.message
});
}
});
// Rota para teste da API
app.get('/api/health', (req, res) => {
res.status(200).json({ status: 'UP', message: 'API de integração com Ubitracker está funcionando' });
});
// Inicia o servidor
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
console.log(`Servidor rodando na porta ${PORT}`);
});
// Exporta o app para testes ou uso como módulo
module.exports = app;
Exemplo de uso da API
Para enviar uma venda para a Ubitracker utilizando a API de exemplo, você pode fazer uma requisição POST para o endpoint /api/sales
com os dados necessários:
const saleData = {
"status": "approved",
"orderBump": false,
"name": "João Silva",
"phone": "+5511999999999",
"email": "joao.silva@email.com",
"product": "Curso Avançado de Marketing Digital",
"productId": "prod-123456",
"city": "São Paulo",
"state": "SP",
"country": "Brasil",
"zipCode": "01310-200",
"src": "facebook_ad",
"paymentMethod": "credit_card",
"currency": "BRL",
"installments": 3,
"offer": 997.00,
"fee": 29.90,
"commission": 199.40,
"url": "https://seusite.com.br/checkout/confirmation",
"campaign": "lancamento_q2",
"origin": "social",
"source": "facebook",
"medium": "cpc",
"term": "marketing digital",
"content": "banner-desconto"
};
fetch('http://seu-servico.com/api/sales', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(saleData),
})
.then(response => response.json())
.then(data => {
console.log('Sucesso:', data);
})
.catch((error) => {
console.error('Erro:', error);
});
Configuração no Painel da Ubitracker
Após desenvolver a API que envia webhooks para a Ubitracker, você precisará configurar a integração no app da Ubitracker. Siga os passos abaixo:
- Acesse o app da Ubitracker
- Navegue até o seu projeto e clique em "Integrações"
- Selecione a opção "Standart"
- Copie a URL do webhook fornecida pela Ubitracker
- Exemplo:
https://api-ubitracker-com-br-production.up.railway.app/v1/webhooks/payments/standart/[projectId]
- Substitua
[projectId]
pelo ID do seu projeto na Ubitracker
- Exemplo:
- Insira o token que será usado em sua API para segurança da requisição
- O token deve ser o mesmo que você configurou na sua API
- Exemplo:
seu-token-de-integracao-aqui
- Salve as configurações de integração
Testes e Validação
Para garantir que sua integração está funcionando corretamente, é recomendável realizar os seguintes testes:
- Envie uma venda de teste através da sua API
- Verifique se a venda aparece no painel da Ubitracker
- Confirme se todos os dados estão sendo corretamente exibidos
- Verifique se o token está sendo validado adequadamente
Tratamento de Erros e Boas Práticas
- Implemente um sistema de tentativas (retry) caso a comunicação com a Ubitracker falhe
- Armazene logs detalhados das requisições e respostas para facilitar a depuração
- Monitore o tempo de resposta e a disponibilidade da API da Ubitracker
- Implemente validação dos dados antes de enviá-los para a Ubitracker
- Considere usar uma fila de mensagens para garantir que todos os webhooks sejam processados mesmo em caso de falhas temporárias
Códigos de Status da Ubitracker
A API da Ubitracker pode retornar os seguintes códigos de status:
- 201 (OK): Webhook recebido e processado com sucesso
- 400 (Bad Request): Formato inválido ou campos obrigatórios ausentes
- 401 (Unauthorized): Token de autenticação inválido
- 404 (Not Found): Integração não encontrada
- 429 (Too Many Requests): Limite de taxa excedido
- 500 (Internal Server Error): Erro interno do servidor da Ubitracker
Suporte e Contato
Em caso de dúvidas ou problemas com a integração, entre em contato com o suporte da Ubitracker através dos seguintes canais:
- Email: support@ubitracker.com.br
- Telefone: (44) 9 2001-8506
Conclusão
Seguindo esta documentação, você será capaz de criar uma integração eficiente entre sua aplicação e a Ubitracker, permitindo o envio automático de dados de vendas para análise e acompanhamento em tempo real.