# Oportunidades

> Cree, gestione y dé seguimiento a las oportunidades de su pipeline

Source: https://docs.graph8.com/es/developers/deals/

Las oportunidades representan ingresos potenciales en su pipeline. Cada oportunidad tiene un nombre, un valor, una etapa y puede asociarse a una empresa y a contactos.

---

## Listar pipelines

`GET /deals/pipelines`

Devuelve todos los pipelines de oportunidades y sus etapas. Utilícelo para obtener los valores válidos de `pipeline_id` y `stage_id` antes de crear oportunidades.

### Ejemplo

**cURL**

```bash
curl "https://be.graph8.com/api/v1/deals/pipelines" \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
response = requests.get(
    f"{BASE_URL}/deals/pipelines",
    headers=HEADERS
)
pipelines = response.json()
```

### Respuesta

```json
{
  "data": [
    {
      "id": "pipe-123",
      "name": "Sales Pipeline",
      "is_default": true,
      "stages": [
        {
          "id": "stage-1",
          "name": "Qualification",
          "probability": 10,
          "position": 0,
          "stage_type": "open",
          "color": "#3B82F6"
        },
        {
          "id": "stage-2",
          "name": "Proposal",
          "probability": 50,
          "position": 1,
          "stage_type": "open",
          "color": "#F59E0B"
        }
      ]
    }
  ]
}
```

---

## Listar oportunidades

`GET /deals`

Devuelve todas las oportunidades de la organización con paginación y filtros opcionales.

### Parámetros de consulta

| Parámetro | Tipo | Predeterminado | Descripción |
|-----------|------|----------------|-------------|
| `page` | integer | 1 | Número de página |
| `limit` | integer | 50 | Elementos por página (máx. 200) |
| `stage_id` | string | - | Filtrar por ID de etapa |
| `pipeline_id` | string | - | Filtrar por ID de pipeline |
| `search` | string | - | Buscar por nombre de oportunidad |

### Ejemplo

**cURL**

```bash
curl "https://be.graph8.com/api/v1/deals?search=Enterprise&limit=10" \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
response = requests.get(
    f"{BASE_URL}/deals",
    headers=HEADERS,
    params={"search": "Enterprise", "limit": 10}
)
```

### Respuesta

```json
{
  "data": [
    {
      "id": "deal-abc",
      "name": "Enterprise Contract",
      "amount": 50000,
      "currency": "USD",
      "stage_id": "stage-2",
      "stage_name": "Proposal",
      "pipeline_id": "pipe-123",
      "company_id": 456,
      "close_date": "2026-06-30T00:00:00",
      "created_at": "2026-02-20T10:00:00",
      "updated_at": "2026-02-25T14:30:00"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "has_next": false
  }
}
```

---

## Crear oportunidad

`POST /deals`

Crea una nueva oportunidad. Si no se especifica `pipeline_id`, se utiliza el pipeline predeterminado de la organización. Si no se especifica `stage_id`, se utiliza la primera etapa del pipeline.

### Cuerpo de la solicitud

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| `name` | string | Sí | Nombre de la oportunidad |
| `company_id` | integer | No | Empresa a asociar |
| `description` | string | No | Descripción de la oportunidad |
| `amount` | number | No | Valor monetario |
| `currency` | string | No | Código de moneda (predeterminado: `USD`) |
| `stage_id` | string | No | ID de etapa obtenido de `/deals/pipelines` |
| `pipeline_id` | string | No | ID de pipeline (usa el predeterminado de la organización) |
| `close_date` | string | No | Fecha de cierre prevista (ISO 8601) |

### Ejemplo

**cURL**

```bash
curl -X POST "https://be.graph8.com/api/v1/deals" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enterprise Contract",
    "amount": 50000,
    "company_id": 456,
    "close_date": "2026-06-30"
  }'
```

**Python**

```python
response = requests.post(
    f"{BASE_URL}/deals",
    headers=HEADERS,
    json={
        "name": "Enterprise Contract",
        "amount": 50000,
        "company_id": 456,
        "close_date": "2026-06-30"
    }
)
```

Devuelve `201 Created` con el nuevo objeto de oportunidad.

---

## Obtener oportunidad

`GET /deals/{deal_id}`

Devuelve una oportunidad por ID.

---

## Actualizar oportunidad

`PATCH /deals/{deal_id}`

Actualización parcial: envíe solo los campos que desea modificar.

### Cuerpo de la solicitud

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `name` | string | Nombre de la oportunidad |
| `description` | string | Descripción de la oportunidad |
| `amount` | number | Valor monetario |
| `currency` | string | Código de moneda |
| `stage_id` | string | ID de etapa |
| `close_date` | string | Fecha de cierre prevista (ISO 8601) |

---

## Eliminar oportunidad

`DELETE /deals/{deal_id}`

Devuelve `200` con `{"data": {"deleted": true}}` si la operación tiene éxito.

---

## Obtener oportunidades de un contacto

`GET /contacts/{contact_id}/deals`

Devuelve todas las oportunidades asociadas a un contacto específico.

### Ejemplo

**cURL**

```bash
curl "https://be.graph8.com/api/v1/contacts/12345/deals" \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
response = requests.get(
    f"{BASE_URL}/contacts/12345/deals",
    headers=HEADERS
)
```

### Respuesta

```json
{
  "data": [
    {
      "deal_id": "deal-abc",
      "name": "Enterprise Contract",
      "stage": "Proposal",
      "value": 50000,
      "currency": "USD",
      "pipeline_id": "pipe-123",
      "close_date": "2026-06-30",
      "created_at": "2026-02-20T10:00:00"
    }
  ]
}
```

---

## Obtener oportunidades de una empresa

`GET /companies/{company_id}/deals`

Devuelve todas las oportunidades asociadas a una empresa específica. La estructura de la respuesta es idéntica a la de las oportunidades de un contacto.