Tutoriais da API OminiHub 360

v1 · stable

Tudo o que você precisa para integrar qualquer aplicação ao núcleo financeiro e operacional do OminiHub — em ordem, com exemplos copiáveis.

Visão geral

A API REST do OminiHub 360 cobre cada frente do ecossistema (clientes, cobrança, agenda, CRM, atendimento, makers, notificações, webhooks). Toda chamada usa JSON, autentica por chave e respeita o princípio do menor privilégio: cada chave só vê o que seu escopo permite.

• Base URL: https://ominihub.app.br/api/v1
• Auth: header X-API-Key ou Authorization: Bearer
• Rate limit: 120 req/min por chave
• Referência interativa: /docs/api

Autenticação

Gere a chave em Admin → Chaves de API. O segredo aparece uma única vez — copie e guarde em um cofre.

# Header X-API-Key (recomendado)
curl https://ominihub.app.br/api/v1/me \
  -H "X-API-Key: ohk_live_abc12345.SuaChaveSecretaAqui"

# Authorization Bearer (alternativa)
curl https://ominihub.app.br/api/v1/me \
  -H "Authorization: Bearer ohk_live_abc12345.SuaChaveSecretaAqui"

Escopos disponíveis: clientes, cobrancas, comercial, agenda, crm, atendimento, makers, notificacoes, webhooks, athos.

Convenções

Hello World

1. Gere a chave com escopo clientes.
2. Chame GET /v1/me e veja a chave reconhecida.
3. Crie um cliente:

curl -X POST https://ominihub.app.br/api/v1/clientes \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"nome":"Maria Silva","email":"maria@acme.com","documento":"12345678900"}'

Clientes

CRUD completo com de-duplicação inteligente — se você já cadastrou alguém com o mesmo documento ou e-mail, a API atualiza o cliente existente em vez de criar duplicata.

# Listar com busca
curl "https://ominihub.app.br/api/v1/clientes?q=Maria&per_page=10" -H "X-API-Key: $KEY"

# Atualizar
curl -X PATCH https://ominihub.app.br/api/v1/clientes/123 \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"telefone":"11999998888"}'

Cobranças (PIX, boleto, cartão)

Fluxo completo: crie a fatura → emita no PSP → compartilhe o link de checkout com o cliente. A taxa já vem com gross-up (líquido preservado).

# 1) Cria a fatura
curl -X POST https://ominihub.app.br/api/v1/faturas \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "cliente_id": 123,
    "descricao": "Mensalidade junho/2026",
    "valor_cents": 9900,
    "vencimento": "2026-06-25",
    "billing_type": "PIX"
  }'

# 2) Emite no PSP (gera PIX, boleto ou link de cartão)
curl -X POST https://ominihub.app.br/api/v1/faturas/{id}/emitir -H "X-API-Key: $KEY"

# 3) Receba o webhook fatura.paga quando confirmar

Assinaturas recorrentes

curl -X POST https://ominihub.app.br/api/v1/assinaturas -H "X-API-Key: $KEY" -H "Content-Type: application/json" -d '{
  "cliente_id": 123,
  "descricao": "Plano Pro",
  "valor_cents": 19900,
  "ciclo": "mensal",
  "dia_vencimento": 10,
  "proximo_vencimento": "2026-07-10"
}'

Agenda (OminiAgenda)

# Consulta disponibilidade (público, com chave)
curl "https://ominihub.app.br/api/v1/agenda/disponibilidade?unidade=1&profissional=2&data=2026-06-20" \
  -H "X-API-Key: $KEY"

# Agenda
curl -X POST https://ominihub.app.br/api/v1/agenda/agendar -H "X-API-Key: $KEY" -H "Content-Type: application/json" -d '{
  "cliente_id": 123,
  "servico_id": 5,
  "profissional_id": 2,
  "inicio": "2026-06-20T14:00:00-03:00"
}'

CRM (OminiSales — Leads)

Pipeline RACE: Relacionar → Atrair → Converter → Encantar.

# Cria lead
curl -X POST https://ominihub.app.br/api/v1/leads -H "X-API-Key: $KEY" -H "Content-Type: application/json" -d '{
  "nome": "João Pereira", "empresa": "Acme", "email": "joao@acme.com", "fase": "relacionar"
}'

# Registra atividade
curl -X POST https://ominihub.app.br/api/v1/leads/45/atividades -H "X-API-Key: $KEY" -H "Content-Type: application/json" -d '{
  "tipo": "ligacao", "descricao": "Falei sobre proposta", "concluida_em": "2026-06-13T15:00:00-03:00"
}'

# Move para "ganho"
curl -X PATCH https://ominihub.app.br/api/v1/leads/45 -H "X-API-Key: $KEY" -H "Content-Type: application/json" -d '{"status":"ganho"}'

Atendimento e Chamados (OminiHelp)

# Abre chamado
curl -X POST https://ominihub.app.br/api/v1/chamados -H "X-API-Key: $KEY" -H "Content-Type: application/json" -d '{
  "cliente_id": 123, "titulo": "Erro ao gerar boleto", "descricao": "...", "prioridade": "alta", "tipo": "bug"
}'

# Resposta no chamado
curl -X POST https://ominihub.app.br/api/v1/chamados/8/mensagens -H "X-API-Key: $KEY" -H "Content-Type: application/json" -d '{
  "autor": "operador", "corpo": "Em análise — retorno em 2h"
}'

Makers e Projetos (OminiMakers)

curl -X POST https://ominihub.app.br/api/v1/projects -H "X-API-Key: $KEY" -H "Content-Type: application/json" -d '{
  "nome": "App OminiCheckout", "orcamento_cents": 5000000, "inicio": "2026-07-01", "fim": "2026-09-30"
}'

curl -X POST https://ominihub.app.br/api/v1/allocations -H "X-API-Key: $KEY" -H "Content-Type: application/json" -d '{
  "maker_id": 7, "project_id": 12, "horas_semana": 20, "valor_hora_cents": 18000, "inicio": "2026-07-01"
}'

Notificações (OminiConnect)

E-mail, WhatsApp, SMS ou push. Idempotência por idempotency_key — pode reenviar sem medo.

curl -X POST https://ominihub.app.br/api/v1/notificacoes -H "X-API-Key: $KEY" -H "Content-Type: application/json" -d '{
  "cliente_id": 123,
  "canal": "whatsapp",
  "evento": "lembrete.vencimento",
  "conteudo": "Olá Maria, sua fatura vence amanhã: https://ominihub.app.br/p/abc",
  "idempotency_key": "lembrete-2026-06-25-cli123"
}'

Webhooks (eventos em tempo real)

Cadastre um endpoint, escolha eventos, recebemos pra você sempre que algo acontecer.

curl -X POST https://ominihub.app.br/api/v1/webhooks -H "X-API-Key: $KEY" -H "Content-Type: application/json" -d '{
  "nome": "Zapier — pagamentos",
  "url": "https://hooks.zapier.com/...",
  "eventos": ["fatura.paga","pagamento.confirmado","lead.ganho"]
}'
# Resposta inclui "secret" — guarde, é o que assina os requests.

Verificando a assinatura

// PHP — exemplo de verificação no seu endpoint
$body = file_get_contents('php://input');
$ts   = $_SERVER['HTTP_X_OMINIHUB_TIMESTAMP'];
$sig  = explode('=', $_SERVER['HTTP_X_OMINIHUB_SIGNATURE'], 2)[1];
$calc = hash_hmac('sha256', $ts . '.' . $body, $SECRET);
if (! hash_equals($calc, $sig)) { http_response_code(401); exit; }
// proteção anti-replay: rejeitar se |now - ts| > 5min

Eventos disponíveis

OminiFlow (automações)

Cole o gatilho, defina as condições, escolha as ações — e o ecossistema reage sozinho. Gatilhos vêm do catálogo de eventos.

# Quando uma fatura PIX paga acima de R$ 100, agradecer no WhatsApp + recalcular score do lead
curl -X POST https://ominihub.app.br/api/v1/automacoes -H "X-API-Key: $KEY" -H "Content-Type: application/json" -d '{
  "nome": "Agradecer fatura paga",
  "gatilho": "fatura.paga",
  "condicoes": [
    {"campo": "valor_cents", "op": "gte", "valor": 10000},
    {"campo": "billing_type", "op": "eq", "valor": "PIX"}
  ],
  "acoes": [
    { "tipo": "notificar_cliente", "params": {
      "titulo": "Pagamento confirmado",
      "corpo": "Recebemos! Obrigado, {{nome_cliente}}.",
      "canais": ["whatsapp", "email"]
    }}
  ]
}'

Tipos de ação: log, notificar_cliente, chamar_webhook, criar_chamado, atualizar_lead, registrar_atividade_lead, recalcular_score_lead, criar_fatura_rascunho, ia_analisar. Strings em params aceitam {{campo}} para interpolar o payload do evento.

Princípio "prejuízo jamais": nenhuma ação emite dinheiro real no PSP. criar_fatura_rascunho deixa a fatura pendente — emissão exige passar pelo BillingService manual.

OminiMedia AI

Departamento de marketing por IA. Descreva o objetivo, receba briefing completo (ICP, persona, oferta, copy, posts, calendário, e-mails, WhatsApp).

# 1) Cria
curl -X POST https://ominihub.app.br/api/v1/omini-media/briefings -H "X-API-Key: $KEY" -H "Content-Type: application/json" -d '{
  "objetivo": "Vender automação residencial em Alphaville",
  "produto_servico": "instalação Sonoff/Shelly com app",
  "regiao": "Alphaville"
}'

# 2) Gera (pipeline IA completo)
curl -X POST https://ominihub.app.br/api/v1/omini-media/briefings/42/gerar -H "X-API-Key: $KEY"

Mídia (vídeo/imagem/voz) está no roadmap — endpoints respondem 501 explicitamente com a lista de providers planejados (Veo/Kling/Flux/ElevenLabs). Quando você plugar as chaves, vira live sem mudar a API.

Brand Center

Identidade da marca (paleta, fontes, tom de voz, persona, diretrizes) que entra como contexto em toda geração de IA. Marque uma como padrao e ela é usada automaticamente pelo OminiMedia.

curl -X POST https://ominihub.app.br/api/v1/brands -H "X-API-Key: $KEY" -H "Content-Type: application/json" -d '{
  "nome": "Acme Automação",
  "tom_voz": "direto, técnico, próximo",
  "persona": "engenheiro pragmático que economiza tempo",
  "palavras_chave": ["eficiência", "casa inteligente"],
  "palavras_proibidas": ["barato"],
  "paleta": [{"nome":"primária","hex":"#8B7CFF"}],
  "padrao": true
}'

OminiLife (vida pessoal)

Tarefas, metas e rotinas. Concluir tarefa dispara tarefa.concluida; atingir 100% de progresso na meta dispara meta.atingida. Plugue no OminiFlow para reagir.

curl -X POST https://ominihub.app.br/api/v1/ominilife/tarefas -H "X-API-Key: $KEY" -H "Content-Type: application/json" -d '{
  "user_id": 1, "titulo": "Revisar contrato", "para_data": "2026-06-15T16:00:00-03:00", "prioridade": "alta"
}'

AI Provider Hub

Todo módulo do ecossistema consome IA por aqui — multi-provedor (Claude, GPT, Gemini, DeepSeek, Mistral, Groq, Cerebras...) com tiers economy/balanced/quality, fallback automático, cache e cost tracking.

Veja o resumo financeiro: GET /v1/ai/uso?de=2026-05-01&ate=2026-06-14 ou abra /admin/ai-cost-center.

# Resposta exemplificada
{
  "totais": { "chamadas": 1234, "custo_usd": 0.842, "cache_hits": 412, "latencia_media_ms": 1820 },
  "por_provider": [{"provider":"deepseek","chamadas":800,"custo_usd":0.41}],
  "por_feature": [{"feature":"omini_media.estrategia","chamadas":220,"custo_usd":0.32}]
}

Tier por feature configurado em config/ai.php → features. Trocar a política não exige mudança de código.

Mapa do ecossistema

Descubra dinamicamente quais módulos estão disponíveis, em beta ou no roadmap:

curl https://ominihub.app.br/api/v1/ecossistema -H "X-API-Key: $KEY"
# Filtros: ?status=live&pilar=cobranca

Status possíveis: live, beta, roadmap, external. A landing pública /ecossistema é gerada a partir desta mesma fonte.

Rate limit e retries

120 req/min por chave. Quando estourar você recebe 429 com header Retry-After. Use backoff exponencial no cliente (1s, 2s, 4s, 8s).

Erros

Exemplos em outras linguagens

JavaScript / Node

const headers = { 'X-API-Key': process.env.OMINIHUB_KEY, 'Content-Type': 'application/json' };
const r = await fetch('https://ominihub.app.br/api/v1/faturas', {
  method: 'POST', headers,
  body: JSON.stringify({ cliente_id: 123, descricao: 'X', valor_cents: 9900, vencimento: '2026-06-25', billing_type: 'PIX' })
});
const j = await r.json();

Python

import requests, os
r = requests.post(
  'https://ominihub.app.br/api/v1/faturas',
  headers={ 'X-API-Key': os.environ['OMINIHUB_KEY'] },
  json={ 'cliente_id': 123, 'descricao': 'X', 'valor_cents': 9900, 'vencimento': '2026-06-25', 'billing_type': 'PIX' }
)
print(r.json())

PHP

$client = new GuzzleHttp\Client();
$res = $client->post('https://ominihub.app.br/api/v1/faturas', [
  'headers' => ['X-API-Key' => getenv('OMINIHUB_KEY')],
  'json'    => ['cliente_id'=>123,'descricao'=>'X','valor_cents'=>9900,'vencimento'=>'2026-06-25','billing_type'=>'PIX'],
]);
$data = json_decode((string) $res->getBody(), true);

BI Financeiro

Dashboard enterprise com saúde do negócio em tempo real. Acesso em /admin/bi-financeiro ou no atalho do PWA.

• Score de saúde 0–100 — sinais ok/atenção/ruim por dimensão (caixa, resultado, inadimplência, MRR, base).
• Visão geral — Caixa PSP (Asaas ao vivo), Caixa contábil (ledger), Recebido, A receber, Inadimplência, Resultado.
• SaaS — MRR equivalente, ARR projetado, Ticket médio (3 meses), LTV estimado, Clientes ativos, Churn 90d.
• Fluxo de caixa 12 meses em barras horizontais — entradas vs saídas mês a mês.
• Forecast 6 meses — assinaturas ativas + faturas geradas; mostra o maior dos dois.
• Top clientes / Top atrasados / Receita por plataforma.

Tudo é derivado do ledger contábil (partidas dobradas) e tabelas de pagamentos/assinaturas. Cache de 60s para saldo Asaas, demais consultas em real-time.

Conciliação contábil

Em /admin/conciliacao-relatorio. Compara o que era esperado (faturas com vencimento no mês) vs o que foi efetivamente quitado:

• Esperado, Recebido, Em aberto, Taxa de recebimento — controle de inadimplência mensal.
• Antecipações — dinheiro de meses futuros que caiu agora (não conta para "do esperado").
• Integridade contábil — flags de "faturas pagas sem baixa" e "pagamentos sem lançamento". Tudo zerado = saúde 100%.
• O comando asaas:poll roda a cada minuto reconciliando webhooks perdidos.

DRE / Relatórios

Em /admin/dre-relatorio. Demonstração de Resultado do mês:

• Receita = créditos − estornos (corrigido para refletir saldo líquido real)
• Despesa = custos confirmados (lançamentos do tipo despesa)
• Resultado = receita − despesa
• Por plataforma · Centro de custo — receita/despesa/resultado de cada linha de negócio.

Minha Carteira

Em /admin/carteira-profissional. Separação vida profissional vs vida pessoal:

• Saldo no PSP ao vivo + Recebido no mês + A receber + Taxas repassadas + Retiradas vida pessoal (pró-labore explícito).
• Extrato profissional contábil (últimos lançamentos).
• API somente-leitura para o agente Athos: GET /api/v1/athos/resumo, /athos/extrato, /athos/faturas.

Cliente 360

Em /admin/cliente360. Timeline única do cliente agregando faturas (OminiPay), pagamentos, contratos (OminiDeal), agendamentos (OminiAgenda), chamados (OminiHelp) e conversas (OminiConnect). KPIs: Total recebido, Em aberto, Último contato, Lifetime Value.

PWA e App Mobile

O OminiHub é um Progressive Web App completo. Pode ser instalado como app nativo em Android, iOS, Windows, macOS e Linux.

• Android/Chrome/Edge — botão "Instalar app" flutua no canto inferior direito do admin; também aparece na barra de URL.
• iPhone/iPad (Safari) — banner "Compartilhar ⇪ → Adicionar à Tela de Início".
• Desktop — barra de URL → ícone de instalação.
• Atalhos do app — segure o ícone do app pra abrir direto em: BI Financeiro, Conciliação, DRE, Minha Carteira, Faturas.
• Offline — sem rede, mostra /offline.html. Conteúdo financeiro NUNCA é cacheado por segurança.
• Update prompt — banner roxo no topo aparece quando há nova versão; toque para atualizar.
• Mobile responsivo — sidebar vira drawer overlay com hambúrguer abaixo de 1024px de viewport.

Web Push (notificações)

Notificações push reais para todos os dispositivos via VAPID + Service Worker.

# 1) Pegar a chave pública VAPID
GET /api/push/public-key  →  { "public_key": "BAZ...", "configured": true }

# 2) Subscribe (auto pelo admin ao clicar "Ativar notificações")
POST /api/push/subscribe
{
  "endpoint": "https://fcm.googleapis.com/.../...",
  "keys": { "p256dh": "...", "auth": "..." }
}

# 3) Disparar push de teste
POST /api/push/test  →  { "ok": true, "entregues": 1 }

Payload rico no servidor — title, body, icon, image, badge, actions (até 3 botões), actionMap (deep-link por ação), vibrate, requireInteraction, tag, renotify.

// PHP — disparar push manualmente
use App\Services\PushService;

app(PushService::class)->enviarParaUsuario($user->id, PushService::payload(
    'Pagamento recebido',
    'Ulytech pagou R$ 10,00 — fatura #37 quitada',
    [
        'url' => '/admin/faturas/37',
        'tag' => 'pagamento-37',
        'actions' => [['action' => 'ver', 'title' => 'Ver fatura']],
        'actionMap' => ['ver' => '/admin/faturas/37'],
        'requireInteraction' => true,
    ]
));

Eventos automáticos com push: pagamento recebido (CEO), fatura nova, lembrete de vencimento (cliente), divergência na conciliação (CEO), saúde caindo no BI (CEO).

Pronto para começar? Vá em /admin/api-keys, gere sua primeira chave e abra a referência interativa ao lado. Ou instale o OminiHub como app pelo botão "Instalar app" no admin.