Documentação OminiConnect

Quick Start (5 minutos)

Em 5 minutos seu WhatsApp está respondendo automaticamente.

1. 1.
   Crie sua conta grátis em app.luizrjesus.app.br. Trial de 30 dias, sem cartão.
2. 2.
   Clique em "Nova instância" no dashboard. Dê um nome ao seu negócio.
3. 3.
   Descreva o que o bot deve fazer (use o botão "✨ Sugerir com IA" se quiser). Escolha modelo gpt-4o-mini.
4. 4.
   Configure anti-banimento: 20 msgs/min e 800/dia (padrões seguros).
5. 5.
   Escaneie o QR Code no WhatsApp do celular: ⚙ Configurações → Aparelhos conectados → Conectar aparelho.

✅ Pronto. Seu bot está vendendo 24/7.

Conceitos básicos

Instância

1 número de WhatsApp conectado. Você pode ter várias (depende do plano).

Bot

A IA configurada para cada instância. Tem prompt próprio, modelo, regras anti-banimento.

Crédito

1 crédito = 1 mensagem enviada pelo bot. R$ 1,00 = 10 créditos.

Webhook

URL onde você recebe eventos (mensagens, conexão etc) em tempo real.

Data Source

URL do SEU sistema que o bot consulta quando o cliente pergunta sobre dados (estoque, vendas).

Trial

30 dias grátis para novos cadastros. Depois, compre créditos ou assine um plano.

Tutorial 1 — Criar conta

1. 1. Acesse /app/
2. 2. Clique em "Criar conta"
3. 3. Informe nome, e-mail e senha (mínimo 8 caracteres)
4. 4. Pronto — você ganhou 30 dias de trial grátis. Sem cartão.

Tutorial 2 — Conectar WhatsApp

Cada instância = 1 número de WhatsApp.

1. 1. No painel, clique em + Nova instância
2. 2. Preencha nome do negócio (ex: "Padaria do João") e slug (identificador único, ex: padaria-joao)
3. 3. (Opcional) Webhook URL pra receber eventos no seu sistema
4. 4. Avance → escolha o template do bot ou descreva personalizado
5. 5. Avance → configure anti-banimento (padrões funcionam pra maioria)
6. 6. Clique em Criar e gerar QR Code
7. 7. No celular, abra o WhatsApp Business → ⚙ Configurações → Aparelhos conectados → Conectar um aparelho → Aponte para o QR Code da tela

Tutorial 3 — Configurar o bot

A "personalidade" do bot é definida pelo system prompt. Use o assistente de IA pra criar o seu.

3.1 Usar o assistente "Sugerir com IA"

1. 1. Na tab "🤖 Bot" da instância, clique em ✨ Sugerir com IA
2. 2. Descreva seu negócio (ex: "Pizzaria delivery em SP, vendo pizzas tradicionais")
3. 3. Diga o objetivo do bot (ex: "Atender pedidos com upsell de bebidas")
4. 4. Escolha o tom (profissional, amigável, casual, formal)
5. 5. Clique em Gerar prompt
6. 6. Revise o prompt gerado → clique em Aplicar este prompt

3.2 Configurações importantes

• • Encerrar após (min): tempo de inatividade pra encerrar sessão. Padrão: 10 min.
• • Debounce (s): tempo antes do bot responder, agrupa msgs em rajada. Padrão: 15s.
• • Modelo: gpt-4o-mini (rápido + DeepSeek fallback) ou gpt-4o (premium).

Tutorial 4 — Anti-banimento

Proteja seu número configurando limites adequados.

Tutorial 5 — Ver conversas

Na tab "💬 Conversas" da instância:

• • Sidebar à esquerda: lista de contatos ordenados por mais recente
• • Cada contato mostra: nome (push name), último texto, tempo relativo (5min/2h/3d), total de mensagens (🤖 bot / 👤 lead)
• • Clique em um contato → thread completa do lado direito

Tutorial 6 — BI / Analytics integrado

Faça o bot consultar dados reais do seu sistema quando o cliente perguntar.

1. 1. Na tab "📊 BI / Dados", marque BI ativo
2. 2. Coloque a URL do endpoint do seu sistema que responde a perguntas (ex: https://meusistema.com/api/bi)
3. 3. (Opcional) Token de autenticação que enviamos como Authorization: Bearer ...
4. 4. Adicione contexto do negócio (descrição curta dos dados disponíveis)
5. 5. Salvar.

Agora quando o cliente perguntar "Quais produtos vendem mais?", o bot:

1. 1. Responde "Vou consultar agora!" no WhatsApp
2. 2. Internamente faz POST pra sua URL com { query, instance, context }
3. 3. Seu sistema responde com { answer, chart_url? }
4. 4. O bot envia a resposta + link do gráfico (se houver) pelo WhatsApp

Veja como implementar o endpoint no seu sistema abaixo.

Tutorial 7 — Pagamentos via PIX

Aceite PIX/cartão/boleto direto do chat com clientes.

1. 1. Crie conta em Asaas ou Mercado Pago
2. 2. Pegue o Access Token (use sandbox pra testar primeiro)
3. 3. (Admin) No painel OminiConnect → 🏦 Gateways → escolha provedor → cole token → marque ativo → Salvar
4. 4. Configure o webhook do gateway pra https://luizrjesus.app.br/api/webhooks/{gateway}
5. 5. Quando o bot disser ao cliente "vou gerar o PIX" — o sistema gera automaticamente

API REST

Base URL: https://luizrjesus.app.br/api

Autenticação

Use Bearer token JWT no header de todas as chamadas:

Authorization: Bearer SEU_TOKEN_JWT

POST /auth/signup

{
  "email": "voce@empresa.com",
  "password": "senha-forte-aqui",
  "name": "Seu Nome"
}

// Resposta:
{
  "access_token": "eyJhbGc...",
  "token_type": "bearer"
}

POST /auth/login

{ "email": "voce@empresa.com", "password": "..." }

GET /auth/me

Retorna dados do usuário logado + status de billing (admin / subscription / trial / credits / expired).

Instâncias

POST /me/instances

Cria nova instância + bot + webhook.

{
  "name": "minha-padaria",                     // slug único
  "business_name": "Padaria do João",
  "webhook_url": "https://seusistema.com/wpp", // opcional
  "bot": {
    "enabled": true,
    "system_prompt": "Você é atendente da Padaria do João...",
    "model": "gpt-4o-mini",
    "expire_minutes": 10,
    "debounce_seconds": 15
  },
  "rate_limit": {
    "per_minute": 20,
    "per_day": 800,
    "warmup": true
  }
}

// Retorna o QR Code base64 para escanear:
{
  "name": "minha-padaria",
  "status": "created",
  "bot_id": "cmpb...",
  "qr_code_base64": "data:image/png;base64,iVBORw0KGgo..."
}

GET /me/instances

Lista todas as instâncias do usuário com status atual.

GET /me/instances/{name}

Detalhe da instância: status, perfil conectado, QR code (se desconectado), bot config completo, rate limits.

GET /me/instances/{name}/qr

Gera QR Code fresco (anterior expira em ~20s).

DELETE /me/instances/{name}

Desconecta e remove permanentemente.

Configurar bot

PUT /me/instances/{name}/bot

Atualiza prompt, modelo, expire, debounce.

{
  "enabled": true,
  "system_prompt": "Você é...",
  "model": "gpt-4o-mini",
  "expire_minutes": 10,
  "debounce_seconds": 15
}

PUT /me/instances/{name}/rate-limit

{
  "per_minute": 20,
  "per_day": 800,
  "warmup": true
}

POST /me/assistant/suggest-prompt

Gera prompt customizado via IA (DeepSeek com fallback OpenAI).

{
  "business_description": "Pizzaria delivery em SP...",
  "goal": "Receber pedidos com upsell",
  "tone": "friendly"
}

// Retorna:
{ "prompt": "Você é o atendente...", "tokens_used": 1226 }

Mensagens & conversas

POST /me/instances/{name}/send

{
  "number": "5511987654321",
  "text": "Olá! Pode falar?"
}

⚠️ Cada chamada decrementa 1 crédito (admin/subscription ativa = sem decremento).

GET /me/instances/{name}/contacts

Lista contatos agrupados (1 por número), ordenados por mais recente.

GET /me/instances/{name}/contacts/{jid}/messages

Thread completa de mensagens com um contato específico (ordenadas cronologicamente).

BI / Dados

PUT /me/instances/{name}/data-source

{
  "bi_enabled": true,
  "data_source_url": "https://meusistema.com/api/bi",
  "data_source_token": "seu-bearer-token",
  "bi_context": "Padaria delivery. Dados: produtos, estoque, vendas."
}

GET /me/instances/{name}/bi-history

Últimas consultas BI feitas pelo bot (auditoria + debug).

Pagamentos

POST /me/topup

Compra créditos. R$ 1,00 = 10 créditos.

{
  "amount": 50.00,
  "gateway": "asaas",        // ou "mercadopago"
  "method": "pix",           // pix | card | boleto
  "payer_name": "Seu Nome",  // obrigatório se boleto
  "cpf_cnpj": "00000000000"  // obrigatório se boleto
}

// Retorna QR Code PIX ou link de checkout:
{
  "payment_id": "pay_xxx",
  "status": "pending",
  "qr_code_text": "00020126...",        // PIX copia-cola
  "qr_code_base64": "data:image/png...",
  "payment_url": "https://..."
}

GET /me/payments

Histórico de compras.

GET /me/payments/{id}/check

Força verificação de status no gateway (fallback caso webhook falhe).

Webhooks

Quando você configura webhook_url na instância, recebe POST com eventos:

// Mensagem recebida (event=messages.upsert):
{
  "event": "messages.upsert",
  "instance": "minha-padaria",
  "data": {
    "key": { "remoteJid": "5511...@s.whatsapp.net", "fromMe": false },
    "message": { "conversation": "Quero pão de queijo" },
    "pushName": "João Cliente",
    "messageTimestamp": 1730000000
  }
}

// Bot enviou (event=send.message):
{
  "event": "send.message",
  "instance": "minha-padaria",
  "data": { "key": {...}, "message": {...} }
}

// Status conexão:
{
  "event": "connection.update",
  "instance": "minha-padaria",
  "data": { "state": "open" | "connecting" | "close" }
}

SDK PHP

<?php
// 1. Login (uma vez)
$ch = curl_init('https://luizrjesus.app.br/api/auth/login');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode(['email' => 'voce@empresa.com', 'password' => '...']),
]);
$resp = json_decode(curl_exec($ch), true);
$token = $resp['access_token'];

// 2. Enviar mensagem
$ch = curl_init('https://luizrjesus.app.br/api/me/instances/minha-padaria/send');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'number' => '5511987654321',
        'text' => 'Seu pedido está pronto!',
    ]),
]);
echo curl_exec($ch);

JavaScript / Node

const API = 'https://luizrjesus.app.br/api';

// Login
const r = await fetch(API + '/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'voce@empresa.com', password: '...' }),
});
const { access_token } = await r.json();

// Enviar mensagem
await fetch(API + '/me/instances/minha-padaria/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + access_token,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    number: '5511987654321',
    text: 'Seu pedido está pronto!',
  }),
});

Python

import requests

API = 'https://luizrjesus.app.br/api'

# Login
r = requests.post(f'{API}/auth/login', json={
    'email': 'voce@empresa.com', 'password': '...'
})
token = r.json()['access_token']

# Enviar mensagem
requests.post(
    f'{API}/me/instances/minha-padaria/send',
    headers={'Authorization': f'Bearer {token}'},
    json={'number': '5511987654321', 'text': 'Seu pedido está pronto!'},
)

cURL

# Login
TOKEN=$(curl -s -X POST https://luizrjesus.app.br/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"voce@empresa.com","password":"..."}' \
  | jq -r .access_token)

# Enviar mensagem
curl -X POST https://luizrjesus.app.br/api/me/instances/minha-padaria/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"number":"5511987654321","text":"Olá!"}'

Conectar seu sistema (BI)

Pra que o bot consulte dados reais, implemente um endpoint no seu sistema.

Contrato do endpoint

O OminiConnect fará POST pra sua URL com:

POST https://seu-sistema.com/api/bi
Authorization: Bearer seu-token-de-auth (se configurou)
Content-Type: application/json

{
  "query": "produtos mais vendidos",
  "instance": "minha-padaria",
  "context": "Padaria delivery. Dados disponíveis: produtos, estoque, vendas."
}

Sua resposta deve ser:

{
  "answer": "Top 5 produtos:\n1. Coxinha — 342\n2. Pão de queijo — 287\n...",
  "chart_url": "https://quickchart.io/chart?c={...}"   // opcional, gráfico
}

Exemplo PHP

<?php
// seu_sistema/api/bi.php
$body = json_decode(file_get_contents('php://input'), true);
$query = strtolower($body['query'] ?? '');

if (str_contains($query, 'mais vendido')) {
    $pdo = new PDO('mysql:...');
    $stmt = $pdo->query("SELECT nome, SUM(qtd) as total FROM vendas GROUP BY produto ORDER BY total DESC LIMIT 5");
    $rows = $stmt->fetchAll(PDO::FETCH_ASSOC);
    $list = array_map(fn($r, $i) => ($i+1).". {$r['nome']} — {$r['total']} unidades", $rows, array_keys($rows));
    echo json_encode([
        'answer' => "📊 *Mais vendidos do mês:*\n\n" . implode("\n", $list),
    ]);
    exit;
}
echo json_encode(['answer' => 'Não entendi a pergunta.']);

Dica: use QuickChart.io pra gerar URLs de gráfico sem servidor próprio.

Gateways de pagamento

Asaas

1. 1. Acesse asaas.com e crie conta
2. 2. Em API, gere um Access Token (sandbox primeiro)
3. 3. No painel admin OminiConnect → 🏦 Gateways → Asaas → cole token → Ativo → Salvar
4. 4. No Asaas, configure webhook pra https://luizrjesus.app.br/api/webhooks/asaas

Mercado Pago

1. 1. Acesse developers.mercadopago.com.br
2. 2. Criar aplicação → pegue o Access Token (produção)
3. 3. Configure no painel OminiConnect
4. 4. Configure webhook no MP pra https://luizrjesus.app.br/api/webhooks/mercadopago

PagBank / PicPay

Implementação completa na Fase 4. Por enquanto use Asaas ou MP.

Guia anti-banimento WhatsApp

Boas práticas pra manter seu número saudável:

• ✅ Use WhatsApp Business, não o pessoal
• ✅ Aqueça números novos: deixe o modo warmup ligado por 1ª semana
• ✅ Não envie sem contato prévio: bot responde, não inicia massa
• ✅ Mantenha taxa de bloqueio baixa: clientes que bloqueiam = sinal pra WhatsApp
• ✅ Configure perfil completo: nome, foto, descrição comercial
• ❌ Nunca envie spam ou conteúdo não solicitado
• ❌ Nunca compre listas de números
• ❌ Nunca mande mais que 1000/dia em número novo

Troubleshooting

Changelog