Oportunidades (Deals)

Crear, listar y gestionar oportunidades de venta con pipelines, etapas, productos y conversaciones

Endpoints

Metodo	Ruta	Descripcion
`GET`	`/crm/organizations/{organization_id}/deals`	Listar oportunidades con filtros
`POST`	`/crm/organizations/{organization_id}/deals`	Crear una oportunidad
`GET`	`/crm/organizations/{organization_id}/deals/:id`	Obtener oportunidad por ID
`PATCH`	`/crm/organizations/{organization_id}/deals/:id`	Actualizar una oportunidad
`PATCH`	`/crm/organizations/{organization_id}/deals/:id/stage`	Mover de etapa
`DELETE`	`/crm/organizations/{organization_id}/deals/:id`	Eliminar (soft delete)
`POST`	`/crm/organizations/{organization_id}/deals/:id/line-items`	Agregar producto
`PATCH`	`/crm/organizations/{organization_id}/deals/:id/line-items/:itemId`	Actualizar producto
`DELETE`	`/crm/organizations/{organization_id}/deals/:id/line-items/:itemId`	Eliminar producto
`POST`	`/crm/organizations/{organization_id}/deals/:id/conversations`	Vincular conversacion
`DELETE`	`/crm/organizations/{organization_id}/deals/:id/conversations/:linkId`	Desvincular conversacion
`GET`	`/crm/organizations/{organization_id}/deals/:id/stage-times`	Tiempo por etapa

Crear oportunidad

POST /crm/organizations/{organization_id}/deals

Body

Campo	Tipo	Requerido	Descripcion
`name`	string	Si	Nombre de la oportunidad
`pipeline_id`	string	Si	UUID del pipeline
`stage_id`	string	Si	UUID de la etapa inicial
`amount`	number	No	Monto estimado
`currency`	string	No	Codigo ISO 4217 (default: `MXN`). Soportados: MXN, USD, EUR, COP, ARS, BRL, CLP, PEN, UYU, BOB, PYG, CRC, DOP, GTQ, HNL, NIO, PAB, GBP, CAD
`status`	string	No	`open` (default), `won`, `lost`
`owner_id`	string	No	UUID del miembro responsable
`account_id`	string	No	UUID de la cuenta vinculada
`expected_close_date`	string	No	Fecha ISO (YYYY-MM-DD)
`conversation_ids`	string[]	No	IDs de conversaciones a vincular
`contacts`	array	No	Contactos: `[{ contact_id, role?, is_primary? }]`

Ejemplo

curl -X POST https://api.mirlo.com/v1/crm/organizations/{organization_id}/deals \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plan Enterprise Acme Corp",
    "pipeline_id": "878132de-d23d-4ee8-afd4-92835b92632d",
    "stage_id": "c2a2e188-216d-4695-b356-aa6b1d13b878",
    "amount": 85000,
    "currency": "MXN",
    "owner_id": "dee2b7d5-1069-4580-bc5b-aa84d9899c5f",
    "expected_close_date": "2026-08-15"
  }'

Respuesta

{
  "id": "deal_5a8509f7-9066-4ab0-8255-e8d7577f71f1",
  "number": 3,
  "reference": "VNT-3",
  "name": "Plan Enterprise Acme Corp",
  "amount": "85000",
  "currency": "MXN",
  "status": "open",
  "pipeline_id": "878132de-d23d-4ee8-afd4-92835b92632d",
  "stage_id": "c2a2e188-216d-4695-b356-aa6b1d13b878",
  "expected_close_date": "2026-08-15T00:00:00.000Z",
  "created_at": "2026-07-12T00:00:00.000Z",
  "pipeline": { "id": "...", "name": "Ventas", "key": "VNT" },
  "stage": { "id": "...", "name": "Prospecto", "stage_order": 0 }
}

Listar oportunidades

GET /crm/organizations/{organization_id}/deals

Query Parameters

Parametro	Tipo	Descripcion
`search`	string	Busqueda por nombre
`pipeline_id`	string	Filtrar por pipeline
`stage_id`	string	Filtrar por etapa
`owner_id`	string	Filtrar por responsable
`status`	string	`open`, `won`, `lost`
`account_id`	string	Filtrar por cuenta
`product_id`	string	Filtrar por producto asociado
`amount_min`	number	Monto minimo
`amount_max`	number	Monto maximo
`unassigned`	boolean	`true` para deals sin responsable
`currency`	string	Filtrar por moneda
`expected_close_before`	string	Fecha cierre esperada antes de (YYYY-MM-DD)
`expected_close_after`	string	Fecha cierre esperada despues de (YYYY-MM-DD)
`created_after`	string	Fecha creacion desde (YYYY-MM-DD)
`created_before`	string	Fecha creacion hasta (YYYY-MM-DD)
`sort_by`	string	Ordenar por: `amount`, `created_at`, `updated_at`, `name`, `expected_close_date`
`sort_dir`	string	`asc` o `desc`
`timezone`	string	Ej: `America/Mexico_City`
`limit`	number	Maximo de resultados (default: 100)
`offset`	number	Offset para paginacion

Ejemplo

curl "https://api.mirlo.com/v1/crm/organizations/{organization_id}/deals?status=open&sort_by=amount&sort_dir=desc&limit=20" \
  -H "X-API-Key: <YOUR_API_KEY>"

Mover de etapa

PATCH /crm/organizations/{organization_id}/deals/:id/stage

Mueve el deal a una nueva etapa del pipeline. Si la etapa destino tiene status won o lost, el deal se actualiza automaticamente.

curl -X PATCH https://api.mirlo.com/v1/crm/organizations/{organization_id}/deals/:id/stage \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "stage_id": "ba6a8df0-5e2b-42de-abe2-575c888b4232"
  }'

Actualizar oportunidad

PATCH /crm/organizations/{organization_id}/deals/:id

Body

Campo	Tipo	Descripcion
`name`	string	Nombre
`amount`	number	Monto
`currency`	string	Moneda
`status`	string	`open`, `won`, `lost`
`owner_id`	string	Responsable
`account_id`	string	Cuenta vinculada
`expected_close_date`	string	Fecha cierre esperada
`pipeline_id`	string	Cambiar de pipeline
`stage_id`	string	Cambiar de etapa

curl -X PATCH https://api.mirlo.com/v1/crm/organizations/{organization_id}/deals/:id \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 95000,
    "status": "won"
  }'

Productos (Line Items)

Cada oportunidad puede tener productos asociados con cantidad, precio unitario y descuento. El monto del deal se recalcula automaticamente como la suma de los line items.

Agregar producto

POST /crm/organizations/{organization_id}/deals/:id/line-items

Campo	Tipo	Requerido	Descripcion
`name`	string	Si	Nombre del producto
`product_id`	string	No	UUID del producto del catalogo
`quantity`	number	Si	Cantidad
`unit_price`	number	Si	Precio unitario
`discount`	number	No	Descuento fijo (default: 0)
`currency`	string	No	Moneda (default: MXN)
`sku`	string	No	SKU del producto
`notes`	string	No	Notas adicionales

curl -X POST https://api.mirlo.com/v1/crm/organizations/{organization_id}/deals/:id/line-items \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plan Enterprise",
    "product_id": "prod-uuid",
    "quantity": 10,
    "unit_price": 8500,
    "discount": 0
  }'

Respuesta

{
  "id": "item-uuid",
  "deal_id": "deal_...",
  "product_id": "prod-uuid",
  "name": "Plan Enterprise",
  "quantity": 10,
  "unit_price": "8500",
  "discount": "0",
  "total": "85000",
  "currency": "MXN"
}

Eliminar producto

DELETE /crm/organizations/{organization_id}/deals/:id/line-items/:itemId

Conversaciones

Vincular conversacion

POST /crm/organizations/{organization_id}/deals/:id/conversations

Campo	Tipo	Requerido	Descripcion
`conversation_id`	string	Si	ID de la conversacion o llamada
`channel`	string	No	`whatsapp`, `voice`, `email`, `sms`, `webchat`
`linked_by`	string	No	UUID del miembro que vincula

Al vincular, el sistema captura automaticamente el resumen de IA de la conversacion o llamada y lo almacena en la actividad.

curl -X POST https://api.mirlo.com/v1/crm/organizations/{organization_id}/deals/:id/conversations \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv-uuid",
    "channel": "whatsapp"
  }'

Desvincular conversacion

DELETE /crm/organizations/{organization_id}/deals/:id/conversations/:linkId

Tiempo por etapa

GET /crm/organizations/{organization_id}/deals/:id/stage-times

Retorna cuanto tiempo estuvo el deal en cada etapa del pipeline.

curl "https://api.mirlo.com/v1/crm/organizations/{organization_id}/deals/:id/stage-times" \
  -H "X-API-Key: <YOUR_API_KEY>"

Respuesta

{
  "deal_id": "deal_...",
  "stages": [
    {
      "stage_id": "...",
      "stage_name": "Prospecto",
      "stage_order": 0,
      "duration_ms": 64800000,
      "is_current": false
    },
    {
      "stage_id": "...",
      "stage_name": "Contactado",
      "stage_order": 1,
      "duration_ms": 21600000,
      "is_current": true
    }
  ]
}

En esta pagina