Pipelines y oportunidades

Gestiona tus pipelines, sus etapas y las oportunidades que avanzan por ellas — incluyendo etiquetas, notas y propiedades personalizadas. Todo cuelga de /workspaces/:workspaceId/pipelines, salvo la consulta puntual de una oportunidad por id (/workspaces/:workspaceId/opportunities/:opportunityId).

Consejo

Una oportunidad pertenece a un único pipeline durante toda su vida — el pipelineId va en la ruta y no se puede cambiar con PATCH. Para “moverla” a otro pipeline hay que crear una nueva oportunidad en el pipeline destino y eliminar la original.

Pipelines

Método	Ruta	Descripción
GET	/workspaces/:workspaceId/pipelines	Listar pipelines (search, sortBy, order, page, pageSize)
POST	/workspaces/:workspaceId/pipelines	Crear pipeline
PATCH	/workspaces/:workspaceId/pipelines/reorder	Reordenar los pipelines del workspace
PATCH	/workspaces/:workspaceId/pipelines/:pipelineId	Actualizar pipeline
DELETE	/workspaces/:workspaceId/pipelines/:pipelineId	Eliminar pipeline

reorder reordena los pipelines entre sí (no las etapas dentro de un pipeline): recibe la lista completa de ids en el orden deseado.

Etapas

Etapas (columnas del pipeline) dentro de un pipeline concreto.

Método	Ruta	Descripción
GET	/workspaces/:workspaceId/pipelines/:pipelineId/stages	Listar etapas del pipeline
POST	/workspaces/:workspaceId/pipelines/:pipelineId/stages	Crear etapa
PATCH	/workspaces/:workspaceId/pipelines/:pipelineId/stages/:stageId	Actualizar etapa (name, color)
DELETE	/workspaces/:workspaceId/pipelines/:pipelineId/stages/:stageId	Eliminar etapa

Oportunidades

Método	Ruta	Descripción
GET	/workspaces/:workspaceId/pipelines/:pipelineId/opportunities/board	Tablero kanban: columnas por etapa, con tope por columna (perStage)
GET	/workspaces/:workspaceId/pipelines/:pipelineId/opportunities	Listar oportunidades del pipeline (ver filtros abajo)
POST	/workspaces/:workspaceId/pipelines/:pipelineId/opportunities	Crear oportunidad
GET	/workspaces/:workspaceId/pipelines/:pipelineId/opportunities/:opportunityId	Obtener oportunidad
PATCH	/workspaces/:workspaceId/pipelines/:pipelineId/opportunities/:opportunityId	Actualizar oportunidad — cambiar de etapa, asignar responsable, marcar ganada/perdida
DELETE	/workspaces/:workspaceId/pipelines/:pipelineId/opportunities/:opportunityId	Eliminar oportunidad
GET	/workspaces/:workspaceId/opportunities/:opportunityId	Obtener una oportunidad por id, sin conocer su pipeline (vista de detalle standalone)

Filtros de GET .../opportunities (query string, todos opcionales): status (OPEN/WON/LOST), stageIds (csv), tagIds (csv), assignedUserIds (csv), contactIds (csv — así se listan las oportunidades de un contacto), search, sortBy (name/createdAt/updatedAt/stage), order (asc/desc), createdAtPeriod/createdAtAmount y updatedAtPeriod/updatedAtAmount (ej. updatedAtPeriod=week&updatedAtAmount=2 = actualizadas en las últimas 2 semanas), page, pageSize.

Cambiar de etapa, asignar responsable y marcar ganada/perdida

Las tres acciones usan el mismo PATCH .../opportunities/:opportunityId, cada una con su campo:

Campo	Tipo	Descripción
stageId	string	Mueve la oportunidad a otra etapa (debe pertenecer al mismo pipeline).
assignedUserId	string | null	Asigna un responsable, o null para dejarla sin asignar.
status	OPEN | WON | LOST	Marca la oportunidad como ganada o perdida (o la reabre con OPEN).
name, contactId, budget	—	También editables en la misma llamada.

Etiquetas de oportunidades

Catálogo de etiquetas a nivel workspace, y su asignación a cada oportunidad.

Método	Ruta	Descripción
GET	/workspaces/:workspaceId/pipelines/opportunity-tags	Listar catálogo de etiquetas
POST	/workspaces/:workspaceId/pipelines/opportunity-tags	Crear etiqueta (name, color)
PATCH	/workspaces/:workspaceId/pipelines/opportunity-tags/:tagId	Actualizar etiqueta
DELETE	/workspaces/:workspaceId/pipelines/opportunity-tags/:tagId	Eliminar etiqueta
GET	/workspaces/:workspaceId/pipelines/opportunity-tags/:tagId/opportunities	Listar oportunidades que tienen esa etiqueta
POST	/workspaces/:workspaceId/pipelines/:pipelineId/opportunities/:opportunityId/tags	Agregar etiquetas (por tagIds, array) a una oportunidad
DELETE	/workspaces/:workspaceId/pipelines/:pipelineId/opportunities/:opportunityId/tags/:tagId	Quitar una etiqueta de una oportunidad

Notas de oportunidades

Notas internas propias de la oportunidad — no son las notas del contacto asociado (ver operaciones de contactos).

Método	Ruta	Descripción
GET	/workspaces/:workspaceId/pipelines/:pipelineId/opportunities/:opportunityId/notes	Listar notas
POST	/workspaces/:workspaceId/pipelines/:pipelineId/opportunities/:opportunityId/notes	Agregar una nota (content)
PATCH	/workspaces/:workspaceId/pipelines/:pipelineId/opportunities/:opportunityId/notes/:noteId	Editar una nota (content)
DELETE	/workspaces/:workspaceId/pipelines/:pipelineId/opportunities/:opportunityId/notes/:noteId	Eliminar una nota

Propiedades personalizadas de oportunidades

Definiciones a nivel workspace y sus valores por oportunidad. Tipos soportados: TEXT, NUMBER, DATE, BOOLEAN.

Método	Ruta	Descripción
GET	/workspaces/:workspaceId/pipelines/opportunity-schema	Schema de campos nativos de la oportunidad (fuente única de validación)
GET	/workspaces/:workspaceId/pipelines/opportunity-custom-properties	Listar propiedades personalizadas definidas
POST	/workspaces/:workspaceId/pipelines/opportunity-custom-properties	Crear una propiedad (name, type, key?, description?, isRequired?)
PATCH	/workspaces/:workspaceId/pipelines/opportunity-custom-properties/:propertyId	Actualizar name/description/isRequired/order (el type es inmutable)
DELETE	/workspaces/:workspaceId/pipelines/opportunity-custom-properties/:propertyId	Eliminar la propiedad (falla si alguna oportunidad la usa)
GET	/workspaces/:workspaceId/pipelines/opportunity-custom-properties/:propertyId/usage	Oportunidades que usan la propiedad, con su valor
GET	/workspaces/:workspaceId/pipelines/:pipelineId/opportunities/:opportunityId/custom-properties	Valores de las propiedades personalizadas de una oportunidad
PUT	/workspaces/:workspaceId/pipelines/:pipelineId/opportunities/:opportunityId/custom-properties	Guardar en lote (values: [{ propertyId, value }])
PUT	/workspaces/:workspaceId/pipelines/:pipelineId/opportunities/:opportunityId/custom-properties/:propertyId	Guardar el valor de una sola propiedad (value)

Ejemplo — crear una oportunidad

POST /workspaces/:workspaceId/pipelines/:pipelineId/opportunities Copiar

Parámetros de ruta

Parámetro	Tipo	Descripción
workspaceId	string	Identificador del workspace.
pipelineId	string	Pipeline donde se crea la oportunidad.

Cuerpo de la petición

Campo	Tipo	Requerido	Descripción
contactId	string	Sí	Contacto asociado.
name	string	Sí	Nombre/título del trato.
stageId	string	No	Etapa inicial; por defecto la primera etapa del pipeline.
budget	number | null	No	Presupuesto estimado.
status	OPEN | WON | LOST	No	Por defecto OPEN.
assignedUserId	string | null	No	Responsable de la oportunidad.

cURL

curl -X POST "https://api.waiify.com/workspaces/WORKSPACE_ID/pipelines/PIPELINE_ID/opportunities" \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "CONTACT_ID",
    "name": "Plan Pro",
    "stageId": "STAGE_ID",
    "budget": 29
  }'

Node

await fetch(
  'https://api.waiify.com/workspaces/WORKSPACE_ID/pipelines/PIPELINE_ID/opportunities',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer TU_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      contactId: 'CONTACT_ID',
      name: 'Plan Pro',
      stageId: 'STAGE_ID',
      budget: 29,
    }),
  }
);

Python

import requests

requests.post(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/pipelines/PIPELINE_ID/opportunities",
    headers={"Authorization": "Bearer TU_API_KEY"},
    json={"contactId": "CONTACT_ID", "name": "Plan Pro", "stageId": "STAGE_ID", "budget": 29},
)

Respuesta 201

{
  "success": true,
  "data": {
    "id": "opp_ab12cd34ef",
    "name": "Plan Pro",
    "pipelineId": "PIPELINE_ID",
    "stageId": "STAGE_ID",
    "status": "OPEN",
    "budget": 29,
    "assignedUserId": null,
    "createdAt": "2026-06-18T09:00:00.000Z"
  }
}

Ejemplo — mover de etapa, asignar y marcar ganada

PATCH /workspaces/:workspaceId/pipelines/:pipelineId/opportunities/:opportunityId Copiar

Cuerpo de la petición

Campo	Tipo	Requerido	Descripción
stageId	string	No	Nueva etapa dentro del mismo pipeline.
assignedUserId	string | null	No	Nuevo responsable.
status	OPEN | WON | LOST	No	Marca ganada/perdida.

Consejo

Al marcar status: "WON" o "LOST" se notifica a los miembros del workspace. No hace falta un endpoint aparte para “cerrar” la oportunidad.

cURL

curl -X PATCH "https://api.waiify.com/workspaces/WORKSPACE_ID/pipelines/PIPELINE_ID/opportunities/OPPORTUNITY_ID" \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "WON" }'

Node

await fetch(
  'https://api.waiify.com/workspaces/WORKSPACE_ID/pipelines/PIPELINE_ID/opportunities/OPPORTUNITY_ID',
  {
    method: 'PATCH',
    headers: {
      Authorization: 'Bearer TU_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ status: 'WON' }),
  }
);

Python

import requests

requests.patch(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/pipelines/PIPELINE_ID/opportunities/OPPORTUNITY_ID",
    headers={"Authorization": "Bearer TU_API_KEY"},
    json={"status": "WON"},
)

Respuesta 200

{
  "success": true,
  "data": {
    "id": "opp_ab12cd34ef",
    "name": "Plan Pro",
    "pipelineId": "PIPELINE_ID",
    "stageId": "STAGE_ID",
    "status": "WON",
    "budget": 29,
    "assignedUserId": null,
    "updatedAt": "2026-06-18T09:10:00.000Z"
  }
}

Relacionado

• Pipelines · Oportunidades
• Crear contacto · Operaciones de contactos