Editar una oportunidad

Referencia › Editar una oportunidad

Oportunidades (CRM)

# Editar una oportunidad

PUT https://api.wizerp.com/api/v1/oportunidades/{clave}

Cambia los datos de un trato de tu empresa y/o lo mueve de etapa, igual que el tablero del CRM. La clave va en la URL y es la que devuelve GET /oportunidades.

Es una edición parcial: sólo se tocan los campos que mandes; lo demás se conserva. El cliente ligado NO se puede cambiar aquí (nace con el alta).

MOVER DE ETAPA: manda «etapa» con la clave de una etapa de tu empresa (GET /etapas-oportunidad). Si la etapa destino es de tipo «ganada», el trato queda ganado. Si es de tipo «perdida», tienes que mandar también «motivo» (GET /motivos-perdida) — igual que la pantalla, que pide el motivo antes de dejar perder un trato; si tu empresa tiene más de una etapa «perdida», el trato se cierra en la etapa «perdida» con menor orden, sin importar cuál mandaste (así lo hace también el tablero: perder no elige entre varias).

QUIÉN QUEDA COMO VENDEDOR: manda «vendedor» con un usuario activo de tu empresa para asignarlo, o null para dejar el trato sin vendedor. Si no mandas el campo, el vendedor actual no se toca.

Toda escritura necesita la cabecera Idempotency-Key: un valor único por operación (por ejemplo un UUID) que repites tal cual al reintentar. Con la misma clave y los mismos datos se devuelve la respuesta guardada, sin duplicar; con la misma clave y datos distintos responde 409.

Permiso: oportunidades:write

## Cuerpo JSON
- `nombre` (texto): De qué trata el trato. Máximo 160.
- `monto` (decimal): Monto estimado del trato. No negativo, máximo 999,999,999,999.
- `moneda` (texto): Código de la moneda (MXN, USD…). Máximo 4. Por omisión MXN en el alta.
- `fecha_cierre` (texto): Fecha estimada de cierre, AAAA-MM-DD.
- `probabilidad` (entero): Probabilidad de cerrar, 0 a 100. Si no la mandas, se usa la de la etapa.
- `nota` (texto): Nota libre. Máximo 5000.
- `vendedor` (entero): Clave de usuario (DBUSERS) que queda como vendedor del trato. Debe ser un vendedor activo de tu empresa (ver «Decisiones» arriba). Si no lo mandas en el alta, el trato nace sin vendedor (trabajo libre del equipo).
- `contacto` (objeto): Datos de la persona de contacto cuando el trato no tiene un cliente de tu cartera ligado: nombre, empresa, puesto, correo, telefono.
- `etapa` (entero): Clave de la etapa destino (GET /etapas-oportunidad). Si es de tipo «perdida», exige «motivo».
- `motivo` (entero): Clave del motivo de pérdida (GET /motivos-perdida). Sólo aplica junto con «etapa» cuando la etapa destino es de tipo «perdida».

PUT https://api.wizerp.com/api/v1/oportunidades/{clave}

https://api.wizerp.com/api/v1/oportunidades/{clave}

Cambia los datos de un trato de tu empresa y/o lo mueve de etapa, igual que el tablero del CRM. La clave va en la URL y es la que devuelve GET /oportunidades.

Es una edición parcial: sólo se tocan los campos que mandes; lo demás se conserva. El cliente ligado NO se puede cambiar aquí (nace con el alta).

MOVER DE ETAPA: manda «etapa» con la clave de una etapa de tu empresa (GET /etapas-oportunidad). Si la etapa destino es de tipo «ganada», el trato queda ganado. Si es de tipo «perdida», tienes que mandar también «motivo» (GET /motivos-perdida) — igual que la pantalla, que pide el motivo antes de dejar perder un trato; si tu empresa tiene más de una etapa «perdida», el trato se cierra en la etapa «perdida» con menor orden, sin importar cuál mandaste (así lo hace también el tablero: perder no elige entre varias).

QUIÉN QUEDA COMO VENDEDOR: manda «vendedor» con un usuario activo de tu empresa para asignarlo, o null para dejar el trato sin vendedor. Si no mandas el campo, el vendedor actual no se toca.

Toda escritura necesita la cabecera Idempotency-Key: un valor único por operación (por ejemplo un UUID) que repites tal cual al reintentar. Con la misma clave y los mismos datos se devuelve la respuesta guardada, sin duplicar; con la misma clave y datos distintos responde 409.

Requiere el permiso oportunidades:write en la llave · contrato del 2026-10-12

Parámetros de ruta

clave entero en la URL

La clave de la oportunidad (la de GET /oportunidades). Va en la URL.

Cuerpo JSON

Además, toda escritura necesita la cabecera Idempotency-Key: un valor único por operación (por ejemplo un UUID) que repites tal cual al reintentar.

nombre texto

De qué trata el trato. Máximo 160.

monto decimal

Monto estimado del trato. No negativo, máximo 999,999,999,999.

moneda texto

Código de la moneda (MXN, USD…). Máximo 4. Por omisión MXN en el alta.

fecha_cierre texto

Fecha estimada de cierre, AAAA-MM-DD.

probabilidad entero

Probabilidad de cerrar, 0 a 100. Si no la mandas, se usa la de la etapa.

nota texto

Nota libre. Máximo 5000.

vendedor entero

Clave de usuario (DBUSERS) que queda como vendedor del trato. Debe ser un vendedor activo de tu empresa (ver «Decisiones» arriba). Si no lo mandas en el alta, el trato nace sin vendedor (trabajo libre del equipo).

contacto objeto

Datos de la persona de contacto cuando el trato no tiene un cliente de tu cartera ligado: nombre, empresa, puesto, correo, telefono.

etapa entero

Clave de la etapa destino (GET /etapas-oportunidad). Si es de tipo «perdida», exige «motivo».

motivo entero

Clave del motivo de pérdida (GET /motivos-perdida). Sólo aplica junto con «etapa» cuando la etapa destino es de tipo «perdida».

Respuestas

400 Petición mal formada: filtro no permitido, filtro vacío, cursor o límite inválidos, o una cabecera de navegador

401 La llave no es válida, está revocada o venció (llave_invalida), o el usuario dueño de la llave ya no tiene acceso a la empresa (llave_sin_titular)

402 Tu empresa no tiene un plan Pro vigente (plan_requerido). Mientras los límites estén en modo de aviso, esta situación sigue contestando 401 llave_invalida

403 La llave no tiene el permiso que pide esta operación (sin_permiso), o no tiene aceptados los términos de uso de la API vigentes (terminos_pendientes: acéptalos en Wizerp, Configuración › Llaves de API)

404 La ruta no existe, o tu empresa no tiene la API habilitada

409 Conflicto: misma Idempotency-Key con datos distintos, o ya existe un registro con ese identificador (RFC, SKU)

413 El cuerpo pasa del máximo

415 El cuerpo no va como JSON (falta Content-Type: application/json)

422 Un dato no es válido para tu empresa

429 Pasaste el ritmo de 150 peticiones por minuto de tu llave (limite_excedido) o el cupo mensual de tu empresa (cupo_agotado). La respuesta trae Retry-After

500 Falló de nuestro lado. Reintenta y reporta el valor de peticion

503 Tu empresa tiene demasiadas peticiones en curso, o la búsqueda no está disponible. Trae Retry-After

Lenguaje

Petición · cURL

curl -X PUT https://api.wizerp.com/api/v1/oportunidades/{clave} \
  -H "Authorization: Bearer wzk_live_…" \
  -H "X-Wizerp-Key-Id: 208_a3f91c7d" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -d '{"etapa":5,"probabilidad":90}'

$ch = curl_init('https://api.wizerp.com/api/v1/oportunidades/{clave}');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer wzk_live_…',
    'X-Wizerp-Key-Id: 208_a3f91c7d',
    'Content-Type: application/json',
    'Idempotency-Key: 3fa85f64-5717-4562-b3fc-2c963f66afa6',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    '{"etapa":5,"probabilidad":90}');
$r = json_decode(curl_exec($ch), true);

const r = await fetch(
  "https://api.wizerp.com/api/v1/oportunidades/{clave}",
  {
    method: "PUT",
    headers: {
      Authorization: "Bearer wzk_live_…",
      "X-Wizerp-Key-Id": "208_a3f91c7d",
      "Content-Type": "application/json",
      "Idempotency-Key": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    },
    body: JSON.stringify({"etapa":5,"probabilidad":90}),
  }
);
const datos = await r.json();

import requests

r = requests.put(
    "https://api.wizerp.com/api/v1/oportunidades/{clave}",
    headers={
        "Authorization": "Bearer wzk_live_…",
        "X-Wizerp-Key-Id": "208_a3f91c7d",
        "Idempotency-Key": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    },
    json={"etapa":5,"probabilidad":90},
)
datos = r.json()

Las escrituras se prueban desde tu propio sistema con tu llave; la consola pública es solo para consultas. Copia el ejemplo de arriba: ya lleva el cuerpo y la cabecera Idempotency-Key.

Respuesta elige un ejemplo

{
    "ok": true,
    "oportunidad": 184027,
    "etapa": 184027,
    "estatus": "texto"
}

{
    "ok": false,
    "error": {
        "codigo": "json_invalido",
        "mensaje": "Petición mal formada: filtro no permitido, filtro vacío, cursor o límite inválidos, o una cabecera de navegador",
        "peticion": "req_dca2d22e3324f9a8"
    }
}

{
    "ok": false,
    "error": {
        "codigo": "llave_invalida",
        "mensaje": "La llave no es válida, está revocada o venció (llave_invalida), o el usuario dueño de la llave ya no tiene acceso a la empresa (llave_sin_titular)",
        "peticion": "req_dca2d22e3324f9a8"
    }
}

{
    "ok": false,
    "error": {
        "codigo": "limite_excedido",
        "mensaje": "Pasaste el ritmo de 150 peticiones por minuto de tu llave (limite_excedido) o el cupo mensual de tu empresa (cupo_agotado). La respuesta trae Retry-After",
        "peticion": "req_dca2d22e3324f9a8"
    }
}

Ver la referencia completa