Oportunidades

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.

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

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

Respuesta

{
  "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
Python

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

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

Respuesta

{
  "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
Python

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"
  }'

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
Python

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

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

Respuesta

{
  "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.