Ir al contenido
Documentación de Connecto
connecto.lat
API para desarrolladoresReferencia

Oportunidades

Consulta las oportunidades (procesos de venta), agrega un contacto a un embudo definido y la mueve de etapa.

Permisos#

PermisoPara qué sirveTipo
oportunidades:leerLeer oportunidades y embudoslectura
oportunidades:escribirCrear oportunidades y cambiarlas de etapaescritura

Endpoints#

GET /oportunidades#

Lista oportunidades. Filtros: estado (abierto, ganado, perdido), contacto_id, limite, pagina.

Permiso: oportunidades:leer · lectura

Parámetros de la consulta#

ParámetroDescripción
estadoabierto | ganado | perdido
contacto_idid del contacto
limite1 a 100
paginapágina
Ejemplo en curl
curl "https://TU_SUBDOMINIO.connecto.lat/api/v1/oportunidades?estado=valor" \
  -H "Authorization: Bearer cnx_TU_LLAVE"
Ejemplo en javascript
const respuesta = await fetch("https://TU_SUBDOMINIO.connecto.lat/api/v1/oportunidades?estado=valor", {
  method: "GET",
  headers: { "Authorization": "Bearer " + process.env.CONNECTO_API_KEY }
});
const datos = await respuesta.json();
Ejemplo en php
$ch = curl_init("https://TU_SUBDOMINIO.connecto.lat/api/v1/oportunidades?estado=valor");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("CONNECTO_API_KEY")],
]);
$datos = json_decode(curl_exec($ch), true);

GET /oportunidades/{id}#

Una oportunidad.

Permiso: oportunidades:leer · lectura

Ejemplo en curl
curl "https://TU_SUBDOMINIO.connecto.lat/api/v1/oportunidades/{id}" \
  -H "Authorization: Bearer cnx_TU_LLAVE"
Ejemplo en javascript
const respuesta = await fetch("https://TU_SUBDOMINIO.connecto.lat/api/v1/oportunidades/{id}", {
  method: "GET",
  headers: { "Authorization": "Bearer " + process.env.CONNECTO_API_KEY }
});
const datos = await respuesta.json();
Ejemplo en php
$ch = curl_init("https://TU_SUBDOMINIO.connecto.lat/api/v1/oportunidades/{id}");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("CONNECTO_API_KEY")],
]);
$datos = json_decode(curl_exec($ch), true);

GET /embudos#

Lista los embudos activos con sus etapas (id, nombre, tipo abierta/ganada/perdida): sirven para saber qué embudo_id y etapa_id usar.

Permiso: oportunidades:leer · lectura

Ejemplo en curl
curl "https://TU_SUBDOMINIO.connecto.lat/api/v1/embudos" \
  -H "Authorization: Bearer cnx_TU_LLAVE"
Ejemplo en javascript
const respuesta = await fetch("https://TU_SUBDOMINIO.connecto.lat/api/v1/embudos", {
  method: "GET",
  headers: { "Authorization": "Bearer " + process.env.CONNECTO_API_KEY }
});
const datos = await respuesta.json();
Ejemplo en php
$ch = curl_init("https://TU_SUBDOMINIO.connecto.lat/api/v1/embudos");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("CONNECTO_API_KEY")],
]);
$datos = json_decode(curl_exec($ch), true);

POST /embudos/sincronizar#

Crea o actualiza un embudo y sus etapas, identificándolo por su «codigo». Las etapas se buscan por nombre (las que existen se actualizan, las que faltan se crean; no se borra ninguna). Responde 201 al crear el embudo y 200 al actualizarlo.

Permiso: oportunidades:escribir · escritura

Cuerpo (JSON)#

CampoDescripción
codigoobligatorio: identificador estable del embudo (3 a 12 letras o números)
nombreobligatorio
descripcionopcional
reglasopcional: {saltar, retroceder, motivo_obligatorio (true/false), reabrir (todos|jefes)}
etapasobligatorio: lista en orden de {nombre, tipo: abierta|ganada|perdida, color: #RRGGBB, probabilidad: 0 a 100}
Ejemplo de cuerpo
{
  "codigo": "FACTURACION",
  "nombre": "Facturación de suscripciones",
  "etapas": [
    {
      "nombre": "En prueba",
      "color": "#6366F1"
    },
    {
      "nombre": "Pagado",
      "color": "#10B981",
      "probabilidad": 100
    },
    {
      "nombre": "Cancelado",
      "tipo": "perdida",
      "color": "#6B7280"
    }
  ]
}
Ejemplo en curl
curl -X POST "https://TU_SUBDOMINIO.connecto.lat/api/v1/embudos/sincronizar" \
  -H "Authorization: Bearer cnx_TU_LLAVE" \
  -H "Content-Type: application/json" \
  -d '{"codigo":"FACTURACION","nombre":"Facturación de suscripciones","etapas":[{"nombre":"En prueba","color":"#6366F1"},{"nombre":"Pagado","color":"#10B981","probabilidad":100},{"nombre":"Cancelado","tipo":"perdida","color":"#6B7280"}]}'
Ejemplo en javascript
const respuesta = await fetch("https://TU_SUBDOMINIO.connecto.lat/api/v1/embudos/sincronizar", {
  method: "POST",
  headers: { "Authorization": "Bearer " + process.env.CONNECTO_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "codigo": "FACTURACION",
    "nombre": "Facturación de suscripciones",
    "etapas": [
        {
            "nombre": "En prueba",
            "color": "#6366F1"
        },
        {
            "nombre": "Pagado",
            "color": "#10B981",
            "probabilidad": 100
        },
        {
            "nombre": "Cancelado",
            "tipo": "perdida",
            "color": "#6B7280"
        }
    ]
})
});
const datos = await respuesta.json();
Ejemplo en php
$ch = curl_init("https://TU_SUBDOMINIO.connecto.lat/api/v1/embudos/sincronizar");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("CONNECTO_API_KEY"), "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(array (
  'codigo' => 'FACTURACION',
  'nombre' => 'Facturación de suscripciones',
  'etapas' => 
  array (
    0 => 
    array (
      'nombre' => 'En prueba',
      'color' => '#6366F1',
    ),
    1 => 
    array (
      'nombre' => 'Pagado',
      'color' => '#10B981',
      'probabilidad' => 100,
    ),
    2 => 
    array (
      'nombre' => 'Cancelado',
      'tipo' => 'perdida',
      'color' => '#6B7280',
    ),
  ),
)),
]);
$datos = json_decode(curl_exec($ch), true);

POST /oportunidades#

Agrega un contacto a un proceso de venta: crea su oportunidad en el embudo (y la etapa) que indiques. Un contacto solo puede tener UNA oportunidad abierta por embudo (si ya la tiene responde 409 con su id), salvo que envíes «varias»: true (p. ej. una oportunidad por cada pedido de la web). Se ejecutan las acciones automáticas de la etapa.

Permiso: oportunidades:escribir · escritura

Cuerpo (JSON)#

CampoDescripción
itemsopcional: los productos de la oportunidad, una lista de {producto_id (o «nombre»), cantidad (1 por defecto), precio (el del catálogo por defecto), descuento_tipo: pct|valor, descuento_valor, impuesto_pct (el IVA de Pedidos por defecto)}. Reemplaza los anteriores y el valor de la oportunidad pasa a ser el total (con descuentos e impuestos); la respuesta trae «productos» y «totales»
contacto_idid del contacto (o bien numero_documento, o bien email)
embudo_idid del embudo (o «embudo»: su nombre). Si no lo envías se usa el embudo por defecto
etapa_idopcional: id de una etapa abierta (o «etapa»: su nombre). Por defecto, la primera etapa del embudo
tituloopcional
valoropcional
monedaopcional
producto_idopcional
fecha_cierre_esperadaopcional, AAAA-MM-DD
propietario_idopcional: id del usuario responsable
variasopcional (true/false): permite que el contacto tenga varias oportunidades abiertas en el embudo (una por cada pedido); por defecto solo una
pedido_idopcional: id de un pedido ya creado del mismo contacto (o «pedido_numero»: su número); queda enlazado a la oportunidad
notaopcional: nota inicial
Ejemplo de cuerpo
{
  "numero_documento": "1020304050",
  "embudo": "Ventas",
  "etapa": "Contactado",
  "titulo": "Matrícula Procuraduría",
  "valor": 325000
}
Ejemplo en curl
curl -X POST "https://TU_SUBDOMINIO.connecto.lat/api/v1/oportunidades" \
  -H "Authorization: Bearer cnx_TU_LLAVE" \
  -H "Content-Type: application/json" \
  -d '{"numero_documento":"1020304050","embudo":"Ventas","etapa":"Contactado","titulo":"Matrícula Procuraduría","valor":325000}'
Ejemplo en javascript
const respuesta = await fetch("https://TU_SUBDOMINIO.connecto.lat/api/v1/oportunidades", {
  method: "POST",
  headers: { "Authorization": "Bearer " + process.env.CONNECTO_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "numero_documento": "1020304050",
    "embudo": "Ventas",
    "etapa": "Contactado",
    "titulo": "Matrícula Procuraduría",
    "valor": 325000
})
});
const datos = await respuesta.json();
Ejemplo en php
$ch = curl_init("https://TU_SUBDOMINIO.connecto.lat/api/v1/oportunidades");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("CONNECTO_API_KEY"), "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(array (
  'numero_documento' => '1020304050',
  'embudo' => 'Ventas',
  'etapa' => 'Contactado',
  'titulo' => 'Matrícula Procuraduría',
  'valor' => 325000,
)),
]);
$datos = json_decode(curl_exec($ch), true);

PATCH /oportunidades/{id}#

Cambia la oportunidad de etapa (por etapa_id o por nombre, dentro de su embudo) y/o edita sus datos. Respeta las reglas del embudo y de la etapa: transiciones permitidas, datos requeridos y motivo al perder (422 si no se cumplen); si la etapa pide aprobación responde 202. DATOS DEL PEDIDO: si la etapa destino tiene acciones «Cambiar un dato» sobre el pedido (Configuración › Oportunidades › acciones de la etapa), el valor de cada dato se envía en el MISMO cuerpo, con el nombre del dato como nombre del campo (por ejemplo comprobante_url); al entrar a la etapa, la acción lo guarda en el pedido de la oportunidad. Si la etapa no tiene esa acción, el dato se ignora. También se aceptan en POST /oportunidades cuando nace directamente en una etapa con esa acción. Respuesta 422 si el valor no es válido (la URL debe ser http o https).

Permiso: oportunidades:escribir · escritura

Cuerpo (JSON)#

CampoDescripción
itemsopcional: los productos de la oportunidad, una lista de {producto_id (o «nombre»), cantidad (1 por defecto), precio (el del catálogo por defecto), descuento_tipo: pct|valor, descuento_valor, impuesto_pct (el IVA de Pedidos por defecto)}. Reemplaza los anteriores y el valor de la oportunidad pasa a ser el total (con descuentos e impuestos); la respuesta trae «productos» y «totales»
etapa_idid de la etapa destino (o «etapa»: su nombre)
motivo_perdida_idobligatorio si el embudo lo exige y la etapa es de pérdida
notaopcional
tituloopcional
valoropcional
monedaopcional
producto_idopcional
fecha_cierre_esperadaopcional
propietario_idopcional
comprobante_urldato del pedido: URL de la imagen del comprobante de pago. Se guarda en el pedido de la oportunidad SOLO si la etapa destino tiene la acción «Cambiar un dato → Comprobante de pago»; el nombre del campo es el nombre del dato
envio_guiadato del pedido (ver comprobante_url): guía de envío
envio_metododato del pedido: método de envío
envio_direcciondato del pedido: dirección de envío
notasdato del pedido: notas
Ejemplo de cuerpo
{
  "etapa": "Pago confirmado",
  "comprobante_url": "https://w3.grupogeard.com/comprobantes/GG-261021-7C0451.jpg"
}
Ejemplo en curl
curl -X PATCH "https://TU_SUBDOMINIO.connecto.lat/api/v1/oportunidades/{id}" \
  -H "Authorization: Bearer cnx_TU_LLAVE" \
  -H "Content-Type: application/json" \
  -d '{"etapa":"Pago confirmado","comprobante_url":"https://w3.grupogeard.com/comprobantes/GG-261021-7C0451.jpg"}'
Ejemplo en javascript
const respuesta = await fetch("https://TU_SUBDOMINIO.connecto.lat/api/v1/oportunidades/{id}", {
  method: "PATCH",
  headers: { "Authorization": "Bearer " + process.env.CONNECTO_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "etapa": "Pago confirmado",
    "comprobante_url": "https://w3.grupogeard.com/comprobantes/GG-261021-7C0451.jpg"
})
});
const datos = await respuesta.json();
Ejemplo en php
$ch = curl_init("https://TU_SUBDOMINIO.connecto.lat/api/v1/oportunidades/{id}");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("CONNECTO_API_KEY"), "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(array (
  'etapa' => 'Pago confirmado',
  'comprobante_url' => 'https://w3.grupogeard.com/comprobantes/GG-261021-7C0451.jpg',
)),
]);
$datos = json_decode(curl_exec($ch), true);
¿Te fue útil esta página?
Última actualización: 14/11/2026