Guia completo de integrações e API
Integrações e API a fundo, em 30 capítulos: chaves de API, chamadas reais, webhooks assinados, n8n, MCP e SDKs, tudo funcionando de verdade.
Capítulos do vídeo
- 00:00 Introdução
- 00:41 As formas de conectar o Omnifox Ler este passo →
- 01:17 Requisitos: plano e permissões Ler este passo →
- 01:37 Criar uma chave de API Ler este passo →
- 02:16 Escopos: o que a chave pode fazer Ler este passo →
- 02:53 Copiar a chave uma única vez
- 03:13 A lista de chaves: editar, regenerar e excluir
- 03:37 A documentação da API Ler este passo →
- 04:13 A sua primeira chamada
- 04:41 Contatos pela API Ler este passo →
- 05:08 Escopos em ação: o erro 403 Ler este passo →
- 05:37 Conversas e mensagens pela API Ler este passo →
- 06:13 CRM e calendário pela API Ler este passo →
- 06:44 Paginação e limites Ler este passo →
- 07:06 Webhooks: criar uma assinatura Ler este passo →
- 07:40 Segredo de assinatura, novas tentativas e cabeçalhos Ler este passo →
- 08:19 Entrega de teste
- 08:38 Um evento real
- 09:08 Verificar a assinatura no seu servidor Ler este passo →
- 09:36 Histórico de entregas Ler este passo →
- 10:11 A página de integrações Ler este passo →
- 10:39 Webhook personalizado: entrada e saída
- 11:14 n8n: instalar o nó do Omnifox Ler este passo →
- 11:37 n8n: a credencial do Omnifox
- 12:01 n8n: responder só quando perguntam o preço
- 12:48 n8n: todas as operações
- 13:21 MCP: que uma IA opere o Omnifox Ler este passo →
- 13:51 Testar o servidor MCP com o Inspector Ler este passo →
- 14:32 SDKs oficiais: Node, Python e PHP Ler este passo →
- 15:05 Boas práticas de segurança Ler este passo →
- 15:29 Solução de problemas Ler este passo →
- 15:57 Encerramento
Este é o guia completo de integrações e API, em 30 capítulos: chaves de API com escopos, a documentação, chamadas reais (contatos, conversas, CRM, calendário), erros e paginação, webhooks assinados com o histórico, os cartões de integrações, o n8n, o servidor MCP e os SDKs de Node, Python e PHP. O manual em PDF tem os mesmos capítulos com capturas e exemplos.
1. As formas de conectar o Omnifox
Tudo o que é para desenvolvedores está em Configurações, na seção Desenvolvimento: Webhooks, Chaves de API e Integrações.
A ideia é simples. Com a API REST o seu sistema fala com o Omnifox: cria contatos, responde conversas, agenda horários. Com os webhooks é o contrário: o Omnifox avisa o seu sistema cada vez que algo acontece, por exemplo quando chega uma mensagem.
E por cima disso há atalhos: os nós para o n8n, o servidor MCP para que uma IA opere o Omnifox, e os SDKs para Node, Python e PHP. Todos usam a mesma chave de API.
2. Requisitos: plano e permissões
A API e os webhooks vêm nos planos Crece, Escala e Enterprise. Num plano sem API, a API responde que o seu plano não a inclui.
Para criar chaves de API é preciso poder gerenciar a configuração do espaço, e os webhooks só podem ser criados por um administrador. Cada chave fica presa a um espaço de trabalho.
3. Criar uma chave de API
Vamos em Chaves de API. Ainda não há nenhuma. Clicamos em Nova chave de API.
Damos um nome que diga para que serve, neste caso Tienda en línea, a loja virtual, e escolhemos o espaço de trabalho. A chave só poderá trabalhar nesse espaço, e por isso quase nunca você vai precisar escrever o número do espaço nas suas chamadas.
Expira em é opcional: se ficar vazio, a chave não vence. Para um fornecedor externo ou um teste, convém colocar uma data.
E Token de serviço, ou bot, é para integrações: o que você enviar com esta chave não é atribuído ao seu usuário, não muda o seu status online nem manda notificações para o seu celular. Marcamos.
4. Escopos: o que a chave pode fazer
Agora as permissões, chamadas escopos. Estão agrupadas por módulo: contatos, mensagens, canais, CRM, projetos, calendário e webhooks, cada um com ler e escrever.
Se você não marcar nenhum, a chave tem acesso completo. O recomendável é dar só o que ela precisa. Para a nossa loja marcamos ler e escrever contatos, ler e enviar mensagens, CRM e calendário, e gerenciar webhooks. De propósito não damos canais.
Escrever inclui ler no mesmo módulo. E Admin equivale a todos os escopos, então use com cuidado.
5. Copiar a chave uma única vez
Clicamos em Criar chave e o Omnifox a mostra uma única vez. Copie e guarde num lugar seguro, como o gerenciador de segredos do seu servidor: depois não dá para vê-la de novo. Neste guia a chave aparece desfocada por segurança.
Se você a perder, sem problema: ela é regenerada e a anterior deixa de funcionar.
6. A lista de chaves: editar, regenerar e excluir
Na lista você vê cada chave com o tipo, usuário ou bot, o espaço, os escopos, quando foi usada pela última vez e quando vence. No topo dá para filtrar por tipo.
Com o lápis você muda o nome, os escopos ou o vencimento sem quebrar a integração. Regenerar cria um token novo com as mesmas permissões, ideal se suspeitar de vazamento. E excluir a revoga na hora: qualquer sistema que a use deixa de entrar.
7. A documentação da API
A documentação completa está em omnifox.io barra docs. No topo há atalhos para os nós do n8n, o servidor MCP e os SDKs.
Abaixo está a referência de cada endpoint, agrupada por módulo: contatos, conversas, mensagens, CRM, calendário, webhooks e muito mais. Cada um mostra os parâmetros, um exemplo de resposta e os erros possíveis.
Com Authorize você cola a sua chave e pode testar qualquer chamada na mesma página. E se você usa Postman ou um gerador de código, baixe o arquivo openapi ponto json.
8. A sua primeira chamada
Vamos ao terminal. Guardamos a chave numa variável de ambiente, assim ela nunca fica escrita nos comandos nem no código.
Toda chamada leva o cabeçalho Authorization com a palavra Bearer e a sua chave. Perguntamos quem sou eu: a API responde com o seu usuário e o seu plano.
Todas as respostas têm o mesmo formato: success, message e data. Repare também nos cabeçalhos de limite de uso: quantas chamadas por minuto o seu plano permite e quantas restam.
9. Contatos pela API
Criamos um contato com um POST em contacts: nome, telefone, e-mail e cidade. A resposta traz o identificador.
Buscamos pelo nome com contacts search, e atualizamos com um PUT, por exemplo para adicionar a empresa. Para não duplicar clientes, também existe o upsert, que cria ou atualiza conforme o telefone ou o e-mail.
E aqui está ele, em Contatos do Omnifox, com os dados que mandamos pelo terminal.
10. Escopos em ação: o erro 403
O que acontece se a chave tentar algo que não tem permissão? Não demos canais à nossa chave. Pedimos a lista de canais e a API responde 403, com o escopo que falta: read channels.
Os erros sempre dizem o que aconteceu: 401 se a chave não existe, venceu ou foi revogada; 403 se falta um escopo ou o seu plano não inclui essa função; 422 se um dado não é válido, com o campo e o motivo; e 429 se você passar do limite de chamadas por minuto.
11. Conversas e mensagens pela API
Agora, o mais útil: responder a um cliente pelo seu sistema. A Gabriela escreveu no chat do site perguntando se fazem envios para Quito. Listamos as conversas abertas e lá está a dela.
Lemos as mensagens e respondemos com um POST em conversations, o número dela, barra messages. O Omnifox envia pelo mesmo canal pelo qual o cliente escreveu.
E na caixa de entrada do Omnifox aparece a resposta, enviada à Gabriela pelo chat do site. Antes de escrever pelo WhatsApp, consulte o window status: ele diz se a janela de vinte e quatro horas está aberta ou se é preciso um modelo.
12. CRM e calendário pela API
A API chega à plataforma inteira. No CRM, criamos uma oportunidade para a Gabriela no funil de vendas no atacado, com o valor.
No calendário pedimos os horários livres da degustação de cafés e reservamos um. O agendamento aparece no calendário do Omnifox como se tivesse sido feito à mão, e também pode ser remarcado ou cancelado pela API.
O mesmo vale para projetos, catálogo, pedidos, relatórios, equipes, etiquetas e campanhas: está tudo na documentação.
13. Paginação e limites
As listas vêm em páginas. Com per page você escolhe quantos itens e com page qual página. A resposta diz o total e a última página.
Percorra as páginas até o fim e não peça além do necessário: se chegar ao limite por minuto, a API responde 429; espere alguns segundos e tente de novo. Os SDKs fazem as duas coisas sozinhos.
14. Webhooks: criar uma assinatura
Agora, os webhooks. Em Configurações, Webhooks, clicamos em Novo webhook.
Damos um nome e a URL do seu servidor, que precisa ser https. Para este guia usamos um pequeno servidor receptor de testes que mostra na tela tudo o que chega.
Escolhemos os eventos: mensagem recebida, mensagem enviada, conversa criada e fechada, contato criado e atualizado, campanha concluída e os de agendamentos, de agendado a atendido. Marcamos mensagem recebida e conversa criada.
15. Segredo de assinatura, novas tentativas e cabeçalhos
O segredo de assinatura é a chave com que o Omnifox assina cada envio. Copie-o para o seu servidor para conferir que o aviso vem mesmo do Omnifox. Com Regenerar você obtém um novo.
Na política de novas tentativas você escolhe a estratégia: exponencial, que é a recomendada e espera dois, quatro, oito, dezesseis segundos e assim até cinco minutos; linear, a cada sessenta segundos; ou sem novas tentativas. E o máximo de tentativas.
O circuit breaker protege o seu servidor: depois de tantas falhas seguidas, o Omnifox para de enviar por um tempo e depois tenta de novo. Você também pode adicionar cabeçalhos próprios, por exemplo uma chave do seu lado.
16. Entrega de teste
Antes de salvar, Enviar teste manda um evento test ponto ping para a sua URL e mostra a resposta do seu servidor, o código e o tempo. Não conta para as métricas nem para o circuit breaker.
Salvamos o webhook e vamos ao receptor: lá está o ping, assinado e com a assinatura válida.
17. Um evento real
Agora um evento de verdade. Um cliente novo escreve no chat do site da Café Montañero.
Na hora, o receptor recebe message ponto received: o texto, o contato, a conversa e o canal, tudo em JSON. E como a conversa é nova, também chega conversation ponto created.
Cada envio traz cabeçalhos: o evento, um identificador único da entrega, para você não processar duas vezes a mesma coisa, o número da tentativa, o carimbo de tempo e a assinatura.
18. Verificar a assinatura no seu servidor
Verificar a assinatura leva dez linhas. Você junta o carimbo de tempo, um ponto e o corpo exato que recebeu, calcula um HMAC SHA duzentos e cinquenta e seis com o seu segredo, e compara com o cabeçalho, que começa com sha256 igual.
Com o envio real, a assinatura confere. Se alguém mudar uma única letra do corpo, ela já não confere e o seu servidor deve rejeitar. Rejeite também os carimbos de tempo de mais de cinco minutos, para evitar repetições.
19. Histórico de entregas
Na lista de webhooks você vê cada assinatura com o status e os eventos. Ao abrir, no topo há a taxa de sucesso das últimas vinte e quatro horas e sete dias, o tempo médio e as falhas seguidas.
Abaixo, o status do circuit breaker e o histórico de cada entrega: data, evento, status, tentativas e código HTTP, com filtros. Ver payload mostra exatamente o que foi enviado e o que o seu servidor respondeu.
Se o seu servidor ficou fora do ar, as entregas com falha são tentadas de novo sozinhas; e se o circuito ficou aberto, você pode fechá-lo à mão quando resolver.
20. A página de integrações
Em Integrações estão os conectores prontos. n8n, Make, Zapier e Webhook personalizado funcionam com webhooks nos dois sentidos. A Azur conecta a nota fiscal eletrônica do Equador, e o Cal.com as suas reservas.
As que dizem Em breve, como HubSpot, Shopify, Google Sheets, Zoom ou DocuSign, ainda não podem ser conectadas. Enquanto isso, quase tudo isso se resolve com a API, os webhooks e o n8n.
21. Webhook personalizado: entrada e saída
Abrimos Webhook personalizado. No topo está a sua URL de entrada: o seu sistema manda um POST com uma ação, como criar um contato, etiquetá-lo ou enviar uma mensagem, assinado com o segredo de baixo.
Abaixo vai a sua URL de saída e os eventos que você quer receber. Ao salvar, o Omnifox cria a assinatura e começa a enviar esses eventos, assinados com o mesmo segredo.
Vamos testar: pelo terminal mandamos a ação create contact, assinada. O Omnifox responde que criou, e o contato já está na lista.
22. n8n: instalar o nó do Omnifox
O n8n é uma ferramenta de automação que você pode usar na nuvem dele ou instalar grátis no seu servidor. Aqui temos uma instalação própria.
Em Settings, Community nodes, clicamos em Install, digitamos n8n nodes omnifox, aceitamos o aviso e instalamos. Ficam dois nós: Omnifox, com as ações, e Omnifox Trigger, que escuta os eventos.
23. n8n: a credencial do Omnifox
Criamos a credencial Omnifox API e colamos uma chave de API do Omnifox. Aqui usamos a que criamos, que é do tipo bot; o ideal é uma chave própria para cada integração.
A URL base é a do Omnifox, e o espaço de trabalho pode ficar em zero: ele vem da chave. Ao salvar, o n8n testa a conexão e diz que funciona.
24. n8n: responder só quando perguntam o preço
Este fluxo tem três nós. O primeiro, Omnifox Trigger, escuta o evento mensagem recebida. Ao ativar, ele cria sozinho a assinatura de webhook no Omnifox e verifica a assinatura de cada aviso.
O segundo, um If, confere se o texto da mensagem contém a palavra precio, preço. E o terceiro, Omnifox, com o recurso mensagem e a operação enviar, responde na mesma conversa com a lista de preços.
Ativamos. E no Omnifox, em Webhooks, já aparece a assinatura que o n8n criou.
E a prova de fogo: um cliente pergunta o preço no chat do site. Em um ou dois segundos chega a resposta automática, e no n8n fica registrada a execução, passo a passo.
25. n8n: todas as operações
O nó do Omnifox tem cento e quarenta operações: conversas, contatos, mensagens, etiquetas, campanhas, canais, equipes, agentes de IA, CRM, quadros, calendário, catálogo e pedidos. As listas, como canais ou etiquetas, carregam sozinhas da sua conta.
Dois erros típicos: uma chave de outro espaço de trabalho, que devolve dados vazios ou um 403, e a URL base com barra api no final, que não é necessária: o nó adiciona.
26. MCP: que uma IA opere o Omnifox
MCP, o Model Context Protocol, é o padrão para que assistentes de IA como Claude, Cursor ou ChatGPT usem ferramentas. O servidor MCP do Omnifox dá a eles setenta e duas ferramentas: contatos, conversas, calendário, catálogo, pedidos, fluxos, campanhas e mais.
Instala-se com npx, e só precisa de duas variáveis: a sua chave de API e a URL da API. A IA só pode fazer o que os escopos dessa chave permitirem.
27. Testar o servidor MCP com o Inspector
Para ver o que ele faz sem conectar ainda um assistente, usamos o MCP Inspector, a ferramenta oficial de teste. Conectamos e listamos as ferramentas, cada uma com a descrição e os parâmetros.
Escolhemos search contacts, buscamos Gabriela e a resposta traz a ficha real dela. Agora create contact, com um cliente novo: executamos e ele fica criado no Omnifox, igual a se um assistente fizesse.
Para conectar ao Claude Desktop ou ao Cursor, cole este bloco na configuração de MCP deles: o comando npx, o pacote e as duas variáveis. E para um servidor remoto, o MCP também funciona por HTTP.
28. SDKs oficiais: Node, Python e PHP
Se você programa, os SDKs poupam trabalho: cuidam da autenticação, da paginação, das novas tentativas e dos erros. Com Node, você instala arroba omnifox barra sdk.
Este script cria um cliente com a chave, percorre os contatos de Loja e coloca a etiqueta Cliente atacadista em um deles. Executamos e pronto.
Em Python é igual, com pip install omnifox, e também tem versão assíncrona. E em PHP, com composer require omnifox barra sdk. Os três têm os mesmos recursos e nomes.
29. Boas práticas de segurança
Algumas boas práticas: uma chave por integração, com o mínimo de escopos e do tipo bot. Guarde-a em variáveis de ambiente, nunca no código nem no navegador. Coloque vencimento se for temporária, e regenere se alguém que a conhecia sair.
Nos seus webhooks: verifique sempre a assinatura, responda rápido com um 200 e processe depois numa fila, e use o identificador de entrega para não processar duas vezes o mesmo evento.
30. Solução de problemas
Um 401? A chave foi copiada errada, venceu ou foi regenerada. Um 403? Confira os escopos da chave e se o seu plano inclui a API. Dados vazios? Provavelmente a chave é de outro espaço de trabalho.
O webhook não chega? Olhe o histórico de entregas: se houver erros, o código HTTP diz o que o seu servidor respondeu; se o circuito estiver aberto, feche quando resolver; e confirme que a URL é https e pública.
Artigos relacionados
-
Como conectar integrações e apps externos
Conecte o Omnifox às suas ferramentas favoritas a partir do catálogo de integrações em poucos passos.
-
Integrar o Omnifox com Azur, Siigo, Alegra, QuickBooks ou outro sistema contábil ou ERP
O Omnifox não tem hoje um conector nativo com sistemas contábeis ou ERP. Veja como fazer essa conexão mesmo assim com fluxos de trabalho, o nó HTTP, n8n, Make, Zapier ou a API, com exemplos.
-
Gerar e usar API keys e webhooks
Crie chaves de API para acessar o Omnifox por código e configure webhooks para receber eventos em tempo real.
-
Introdução às integrações (webhook / OAuth / chave de API)
Conecte o Omnifox às suas outras ferramentas: o que está disponível hoje, o que chega em breve e quando usar um webhook, uma conexão OAuth ou uma chave de API.
-
A API REST do Omnifox: introdução e requisitos de plano
O que é a API REST do Omnifox, qual plano você precisa (a partir do Crece), como autenticar com o cabeçalho X-API-Key e onde fica a documentação.