Consulta las oportunidades (procesos de venta), agrega un contacto a un embudo definido y la mueve de etapa.
Permisos#
| Permiso | Para qué sirve | Tipo |
|---|---|---|
oportunidades:leer | Leer oportunidades y embudos | lectura |
oportunidades:escribir | Crear oportunidades y cambiarlas de etapa | escritura |
Endpoints#
GET /oportunidades#
Lista oportunidades. Filtros: estado (abierto, ganado, perdido), contacto_id, limite, pagina.
Permiso: oportunidades:leer · lectura
Parámetros de la consulta#
| Parámetro | Descripción |
|---|---|
estado | abierto | ganado | perdido |
contacto_id | id del contacto |
limite | 1 a 100 |
pagina | página |
curl "https://TU_SUBDOMINIO.connecto.lat/api/v1/oportunidades?estado=valor" \
-H "Authorization: Bearer cnx_TU_LLAVE"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();$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
curl "https://TU_SUBDOMINIO.connecto.lat/api/v1/oportunidades/{id}" \
-H "Authorization: Bearer cnx_TU_LLAVE"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();$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
curl "https://TU_SUBDOMINIO.connecto.lat/api/v1/embudos" \
-H "Authorization: Bearer cnx_TU_LLAVE"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();$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)#
| Campo | Descripción |
|---|---|
codigo | obligatorio: identificador estable del embudo (3 a 12 letras o números) |
nombre | obligatorio |
descripcion | opcional |
reglas | opcional: {saltar, retroceder, motivo_obligatorio (true/false), reabrir (todos|jefes)} |
etapas | obligatorio: lista en orden de {nombre, tipo: abierta|ganada|perdida, color: #RRGGBB, probabilidad: 0 a 100} |
{
"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"
}
]
}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"}]}'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();$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)#
| Campo | Descripción |
|---|---|
items | opcional: 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_id | id del contacto (o bien numero_documento, o bien email) |
embudo_id | id del embudo (o «embudo»: su nombre). Si no lo envías se usa el embudo por defecto |
etapa_id | opcional: id de una etapa abierta (o «etapa»: su nombre). Por defecto, la primera etapa del embudo |
titulo | opcional |
valor | opcional |
moneda | opcional |
producto_id | opcional |
fecha_cierre_esperada | opcional, AAAA-MM-DD |
propietario_id | opcional: id del usuario responsable |
varias | opcional (true/false): permite que el contacto tenga varias oportunidades abiertas en el embudo (una por cada pedido); por defecto solo una |
pedido_id | opcional: id de un pedido ya creado del mismo contacto (o «pedido_numero»: su número); queda enlazado a la oportunidad |
nota | opcional: nota inicial |
{
"numero_documento": "1020304050",
"embudo": "Ventas",
"etapa": "Contactado",
"titulo": "Matrícula Procuraduría",
"valor": 325000
}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}'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();$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)#
| Campo | Descripción |
|---|---|
items | opcional: 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_id | id de la etapa destino (o «etapa»: su nombre) |
motivo_perdida_id | obligatorio si el embudo lo exige y la etapa es de pérdida |
nota | opcional |
titulo | opcional |
valor | opcional |
moneda | opcional |
producto_id | opcional |
fecha_cierre_esperada | opcional |
propietario_id | opcional |
comprobante_url | dato 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_guia | dato del pedido (ver comprobante_url): guía de envío |
envio_metodo | dato del pedido: método de envío |
envio_direccion | dato del pedido: dirección de envío |
notas | dato del pedido: notas |
{
"etapa": "Pago confirmado",
"comprobante_url": "https://w3.grupogeard.com/comprobantes/GG-261021-7C0451.jpg"
}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"}'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();$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);