Crear una oportunidad

Referencia › Crear una oportunidad

Oportunidades (CRM)

# Crear una oportunidad

POST https://api.wizerp.com/api/v1/oportunidades

Da de alta un trato en el embudo del CRM (DBCTEOPO). La empresa sale de tu llave.

Necesita «nombre» y «etapa» (una etapa ABIERTA de tu embudo). El cliente es opcional: puedes mandar «cliente» (uno de tu cartera, no de una plataforma de marketplace ni un registro vacío) o sólo los datos de «contacto» cuando todavía no es cliente.

QUIÉN QUEDA COMO VENDEDOR: si mandas «vendedor», debe ser un usuario activo de tu empresa y el trato nace asignado a él. Si no lo mandas, el trato nace SIN vendedor (trabajo libre del equipo, visible para cualquiera) y el usuario que creó tu llave queda sólo como autor interno del alta — no se escribe en ningún campo visible. Si ese usuario ya no está activo en tu empresa y tampoco mandas «vendedor», la operación responde 422: nunca se inventa un dueño.

Esto NO crea una cotización ni toca tu cartera: para eso está POST /ventas. No crea clientes nuevos: para eso está POST /clientes o POST /leads.

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. Obligatorio. 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 una etapa ABIERTA del embudo de tu empresa (GET /etapas-oportunidad). Obligatorio.
- `cliente` (entero): Clave de un cliente de tu cartera (GET /clientes). Opcional: un trato puede nacer sin cliente ligado, sólo con los datos de «contacto». No puede ser un cliente de una plataforma (marketplace) ni un registro vacío.
- `origen` (texto): Texto libre de dónde salió el trato (p. ej. "Feria", "Referido"). Máximo 40.

POST https://api.wizerp.com/api/v1/oportunidades

https://api.wizerp.com/api/v1/oportunidades

Da de alta un trato en el embudo del CRM (DBCTEOPO). La empresa sale de tu llave.

Necesita «nombre» y «etapa» (una etapa ABIERTA de tu embudo). El cliente es opcional: puedes mandar «cliente» (uno de tu cartera, no de una plataforma de marketplace ni un registro vacío) o sólo los datos de «contacto» cuando todavía no es cliente.

QUIÉN QUEDA COMO VENDEDOR: si mandas «vendedor», debe ser un usuario activo de tu empresa y el trato nace asignado a él. Si no lo mandas, el trato nace SIN vendedor (trabajo libre del equipo, visible para cualquiera) y el usuario que creó tu llave queda sólo como autor interno del alta — no se escribe en ningún campo visible. Si ese usuario ya no está activo en tu empresa y tampoco mandas «vendedor», la operación responde 422: nunca se inventa un dueño.

Esto NO crea una cotización ni toca tu cartera: para eso está POST /ventas. No crea clientes nuevos: para eso está POST /clientes o POST /leads.

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

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 obligatorio

De qué trata el trato. Obligatorio. 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 obligatorio

Clave de una etapa ABIERTA del embudo de tu empresa (GET /etapas-oportunidad). Obligatorio.

cliente entero

Clave de un cliente de tu cartera (GET /clientes). Opcional: un trato puede nacer sin cliente ligado, sólo con los datos de «contacto». No puede ser un cliente de una plataforma (marketplace) ni un registro vacío.

origen texto

Texto libre de dónde salió el trato (p. ej. "Feria", "Referido"). Máximo 40.

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 POST https://api.wizerp.com/api/v1/oportunidades \
  -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 '{"nombre":"Licencias anuales — Distribuidora Olvera","etapa":1,"cliente":5,"monto":85000,"moneda":"MXN","fecha_cierre":"2026-11-30"}'

$ch = curl_init('https://api.wizerp.com/api/v1/oportunidades');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
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,
    '{"nombre":"Licencias anuales — Distribuidora Olvera","etapa":1,"cliente":5,"monto":85000,"moneda":"MXN","fecha_cierre":"2026-11-30"}');
$r = json_decode(curl_exec($ch), true);

const r = await fetch(
  "https://api.wizerp.com/api/v1/oportunidades",
  {
    method: "POST",
    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({"nombre":"Licencias anuales — Distribuidora Olvera","etapa":1,"cliente":5,"monto":85000,"moneda":"MXN","fecha_cierre":"2026-11-30"}),
  }
);
const datos = await r.json();

import requests

r = requests.post(
    "https://api.wizerp.com/api/v1/oportunidades",
    headers={
        "Authorization": "Bearer wzk_live_…",
        "X-Wizerp-Key-Id": "208_a3f91c7d",
        "Idempotency-Key": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    },
    json={"nombre":"Licencias anuales — Distribuidora Olvera","etapa":1,"cliente":5,"monto":85000,"moneda":"MXN","fecha_cierre":"2026-11-30"},
)
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