API do CRM: oportunidades, empresas e funis
Como criar e mover oportunidades, gerenciar empresas e consultar os funis (pipelines) do CRM do Omnifox via API.
Veja este passo no vídeo · CRM e calendário pela API
O módulo CRM do Omnifox organiza oportunidades de venda (deals) em funis (pipelines) com etapas, vinculadas a contatos e empresas. A API expõe esse mesmo modelo para integrar com seu ERP, planilha ou ferramenta de BI.
Requisitos
- O workspace precisa ter o recurso
crm_enabledhabilitado pelo plano; sem ele, esses endpoints retornam403. - Token Bearer do workspace.
Endpoints principais
GET/POST /api/v1/crm/pipelines— listar ou criar funis;GET /api/v1/crm/pipelines/{pipeline}/stagespara suas etapas.GET/POST /api/v1/crm/companies— empresas;POST /api/v1/crm/companies/{company}/contactspara vincular contatos.GET/POST /api/v1/crm/deals— oportunidades.PATCH /api/v1/crm/deals/{deal}/stage— mover uma oportunidade de etapa.GET /api/v1/crm/reports/funnele/forecast— relatórios agregados.
Campos de uma oportunidade (deal)
{
"pipeline_id": 1,
"stage_id": null,
"title": "Renovação anual",
"amount": 1200.0,
"currency": "USD",
"probability": 40,
"contact_id": 55,
"company_id": 12,
"expected_close_date": "2026-09-01"
}
Se você omitir stage_id, a oportunidade entra na primeira etapa do funil.
Exemplo: mover uma oportunidade para "Ganha"
curl -X PATCH "https://app.omnifox.io/api/v1/crm/deals/501/stage" \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"stage_id": 9}'
(A etapa 9 precisa ter is_won: true para que o forecast a conte como fechamento ganho.)
Contato obrigatório e moeda
- Ao criar uma oportunidade (
POST /api/v1/crm/deals),contact_idé obrigatório. Sem ele a API responde422com o erro emcontact_id. - Ao editar, uma oportunidade que já tem contato não pode ficar sem ele (
422). - Se você omitir
currency, a oportunidade nasce na Moeda principal do CRM do espaço (a escolhida nas Configurações; se não houver, a mais usada nas oportunidades, depois a do catálogo e, por fim, USD).
Dicas
- Toda empresa aceita
custom_fields; consulte-os comGET /api/v1/crm/companies/{company}/custom-fields. - Use
client_nonceao criar um deal a partir de uma integração com novas tentativas automáticas, para evitar duplicados por envio duplo.
Solução de problemas
- 403 em qualquer endpoint
/crm/*: o plano do workspace não inclui CRM; verifique Configurações > Faturamento. - Oportunidade não aparece no forecast: confirme se os campos
is_won/is_lostda etapa estão configurados corretamente no funil.
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.
-
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.
-
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.