Integrações
Standard

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á:

  1. Desenvolver uma API que envie webhooks para a Ubitracker
  2. Seguir o padrão de corpo de requisição especificado
  3. Configurar a integração no app da Ubitracker
  4. 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:

CampoTipoObrigatórioDescrição
orderIdstringNãoIdentificador único do pedido
statusstringSimStatus atual da transação
orderBumpbooleanNãoIndica se houve um complemento de pedido
purchaseDateDateSimData e hora da compra
namestringSimNome do cliente
phonestringSimTelefone do cliente
emailstringSimEmail do cliente
productstringSimNome do produto vendido
productIdstringSimIdentificador único do produto
citystringNãoCidade do cliente
statestringNãoEstado do cliente
countrystringNãoPaís do cliente
zipCodestringNãoCEP do cliente
srcstringNãoFonte da venda
paymentMethodstringSimMétodo de pagamento utilizado
currencystringNãoMoeda utilizada na transação
installmentsnumberSimNúmero de parcelas
offernumberSimValor da oferta
feenumberSimTaxa cobrada
commissionnumberSimValor da comissão
urlstringNãoURL relacionada à venda
campaignstringNãoNome da campanha de marketing
originstringNãoOrigem da venda
sourcestringNãoFonte de tráfego
mediumstringNãoCanal de marketing
termstringNãoTermos de busca utilizados
contentstringNãoConteúdo específico da campanha
tokenstringSimToken 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:

  1. Acesse o app da Ubitracker
  2. Navegue até o seu projeto e clique em "Integrações" Integração
  3. Selecione a opção "Standart"
  4. 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
  5. 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
  6. Salve as configurações de integração Integração

Testes e Validação

Para garantir que sua integração está funcionando corretamente, é recomendável realizar os seguintes testes:

  1. Envie uma venda de teste através da sua API
  2. Verifique se a venda aparece no painel da Ubitracker
  3. Confirme se todos os dados estão sendo corretamente exibidos
  4. 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:

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.