API del CRM: oportunidades, empresas y pipelines
Cómo crear y mover oportunidades, gestionar empresas y consultar pipelines del CRM de Omnifox por API.
Mira este paso en el video · CRM y calendario por API
El módulo CRM de Omnifox organiza oportunidades de venta (deals) en pipelines con etapas, asociadas a contactos y empresas. La API expone ese mismo modelo para integrarlo con tu ERP, hoja de cálculo o herramienta de BI.
Requisitos
- El workspace debe tener habilitado el feature
crm_enabledde tu plan; sin él, estos endpoints devuelven403. - Token Bearer del workspace.
Endpoints principales
GET/POST /api/v1/crm/pipelines— listar o crear pipelines;GET /api/v1/crm/pipelines/{pipeline}/stagespara sus etapas.GET/POST /api/v1/crm/companies— empresas;POST /api/v1/crm/companies/{company}/contactspara vincular contactos.GET/POST /api/v1/crm/deals— oportunidades.PATCH /api/v1/crm/deals/{deal}/stage— mover una oportunidad de etapa.GET /api/v1/crm/reports/funnely/forecast— reportes agregados.
Campos de una oportunidad (deal)
{
"pipeline_id": 1,
"stage_id": null,
"title": "Renovación anual",
"amount": 1200.0,
"currency": "USD",
"probability": 40,
"contact_id": 55,
"company_id": 12,
"expected_close_date": "2026-09-01"
}
Si omites stage_id, la oportunidad entra en la primera etapa del pipeline.
Ejemplo: mover una oportunidad a "Ganada"
curl -X PATCH "https://app.omnifox.io/api/v1/crm/deals/501/stage" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"stage_id": 9}'
(La etapa 9 debe tener is_won: true para que el forecast la cuente como cierre ganado.)
Contacto obligatorio y moneda
- Al crear una oportunidad (
POST /api/v1/crm/deals),contact_ides obligatorio. Sin él la API responde422con el error encontact_id. - Al editarla, no se puede dejar sin contacto una oportunidad que ya tiene uno (
422). - Si omites
currency, la oportunidad nace en la Moneda principal del CRM del espacio (la elegida en Configuración; si no hay, la más usada en las oportunidades, luego la del catálogo y, por último, USD).
Consejos
- Cada empresa acepta
custom_fields; consúltalos conGET /api/v1/crm/companies/{company}/custom-fields. - Usa
client_nonceal crear un deal desde una integración con reintentos automáticos, para evitar duplicados por doble envío.
Solución de problemas
- 403 en cualquier endpoint
/crm/*: el plan del workspace no incluye CRM; revisa Configuración > Facturación. - La oportunidad no aparece en el forecast: confirma que la etapa tenga
is_won/is_lostbien configurados en el pipeline.
Artículos relacionados
-
Cómo conectar integraciones y apps externas
Conecta Omnifox con tus herramientas favoritas desde el catálogo de integraciones en pocos pasos.
-
Guía completa de integraciones y API
Integraciones y API a fondo, en 30 capítulos: claves API, llamadas reales, webhooks firmados, n8n, MCP y SDK, todo funcionando de verdad.
-
Integrar Omnifox con Azur, Siigo, Alegra, QuickBooks u otro sistema contable o ERP
Omnifox no tiene hoy un conector nativo con sistemas contables o ERP. Te explicamos cómo conectarlos igual con workflows, el nodo HTTP, n8n, Make, Zapier o la API, con ejemplos.
-
Generar y usar API keys y webhooks
Crea claves de API para acceder a Omnifox por código y configura webhooks para recibir eventos en tiempo real.
-
Introducción a las integraciones (webhook / OAuth / API key)
Conecta Omnifox con tus otras herramientas: qué está disponible hoy, qué llega pronto y cuándo usar un webhook, una conexión OAuth o una clave de API.