API do CRM: oportunidades, empresas e funis

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_enabled habilitado pelo plano; sem ele, esses endpoints retornam 403.
• Token Bearer do workspace.

Endpoints principais

• GET/POST /api/v1/crm/pipelines — listar ou criar funis; GET /api/v1/crm/pipelines/{pipeline}/stages para suas etapas.
• GET/POST /api/v1/crm/companies — empresas; POST /api/v1/crm/companies/{company}/contacts para 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/funnel e /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.)

Dicas

• Toda empresa aceita custom_fields; consulte-os com GET /api/v1/crm/companies/{company}/custom-fields.
• Use client_nonce ao 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 > Plano e faturamento.
• Oportunidade não aparece no forecast: confirme se os campos is_won/is_lost da etapa estão configurados corretamente no funil.