API del CRM: oportunidades, empresas y pipelines

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 omitís 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.)

Consejos

• Cada empresa acepta custom_fields; consultalos con GET /api/v1/crm/companies/{company}/custom-fields.
• Usá 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; revisá Configuración > Plan y facturación.
• La oportunidad no aparece en el forecast: confirmá que la etapa tenga is_won/is_lost bien configurados en el pipeline.