API del CRM: oportunidades, empresas y pipelines

Cómo crear y mover oportunidades, gestionar empresas y consultar pipelines del CRM de Omnifox por API.

Jul 11, 2026

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_enabled de tu plan; sin él, estos endpoints devuelven 403.
  • Token Bearer del workspace.

Endpoints principales

  • GET/POST /api/v1/crm/pipelines — listar o crear pipelines; GET /api/v1/crm/pipelines/{pipeline}/stages para sus etapas.
  • GET/POST /api/v1/crm/companies — empresas; POST /api/v1/crm/companies/{company}/contacts para 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/funnel y /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_id es obligatorio. Sin él la API responde 422 con el error en contact_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 con GET /api/v1/crm/companies/{company}/custom-fields.
  • Usa client_nonce al 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_lost bien configurados en el pipeline.
¿Te fue útil?

Artículos relacionados

Escríbenos por WhatsApp