Ir al contenido
Documentación de Connecto
connecto.lat
Guía de usuarioConfiguración general e IA

APIs y webhooks

Para qué sirve#

  • Las APIs permiten que otros sistemas (tu sitio web, Zapier, Make, un programa de contabilidad o uno hecho a la medida) lean y escriban datos en Connecto sin entrar a la pantalla. Cada API hace una cosa (por ejemplo, consultar contactos) y se enciende o se apaga por separado.
  • Los webhooks son lo contrario: Connecto avisa a tu sistema en cuanto algo ocurre (llegó un mensaje, se creó un contacto, se ganó una oportunidad), enviando los datos a una dirección tuya.

Las APIs se van sumando con el tiempo. Cada API nueva aparece sola como una opción más al generar o editar una credencial (con su casilla de lectura y/o de escritura), viene habilitada y queda documentada en la Referencia de las APIs (se genera sola desde el catálogo) y, si es grande, en su propia página:

APIQué hacePágina
Consulta de contactosBusca contactos por uno o varios campos y devuelve todos sus datos y sus redes o canalesConsulta de contactos
Contactos (listar, crear y editar)Lista contactos y crea o edita los datos básicosMás abajo
Conversaciones y mensajesLee conversaciones y mensajesMás abajo
OportunidadesLee oportunidades y embudos, agrega un contacto a un embudo y la mueve de etapaMás abajo
PedidosLee, crea y actualiza pedidos (productos con descuentos, IVA y envío; pagos, reembolsos y entregas)Más abajo

Quién puede usarlo y cómo llegar#

Solo administradores, en Configuración → APIs y Webhooks (menú de la izquierda). La pantalla tiene dos pestañas:

  1. Credenciales (la vista principal): una tabla con todas las credenciales: sus permisos, vencimiento, último uso y estado. Desde aquí generas, editas, pausas, rotas y revocas.
  2. Webhooks: los avisos que Connecto envía a otros sistemas.

Generar una credencial («Generar API»)#

  1. Pulsa Generar API. Escribe el nombre del sistema que la usará (por ejemplo «Sitio web») y, si quieres, para qué se usa.
  2. Elige los permisos en la matriz de tres columnas: la primera lista todas las opciones (cada API y cada función), la segunda es Lectura (consultar datos) y la tercera Escritura (crear o modificar datos). Marca solo las casillas que necesitas; donde una opción no tiene lectura o escritura, la casilla no existe. La fila «Todas las APIs» da todos los permisos de lectura y/o de escritura, incluidos los de las APIs y funciones que se construyan después; úsala solo si de verdad la necesitas.
  3. Define el vencimiento (recomendado: 1 año), el límite de peticiones por minuto (120 por defecto) y, si el sistema que la usa tiene IP fija, las IPs permitidas (una por línea; admite rangos como 203.0.113.0/24).
  4. Pulsa Generar. Verás la dirección de la API, la llave (empieza por cnx_; cópiala ahora, no se vuelve a mostrar) y, debajo, la guía de uso según los permisos que elegiste: cada endpoint con ejemplos listos para copiar (curl, JavaScript y PHP), los datos que puedes enviar y, en la consulta de contactos, la lista de campos por los que puedes consultar, incluidos los que creaste a mano.

Editar los permisos de una credencial#

Cada credencial tiene permisos específicos que puedes cambiar cuando quieras, sin cambiar la llave. Pulsa el lápiz de la credencial: se abre la misma matriz con sus permisos marcados. Activa o quita lectura y escritura en cualquier opción, ajusta el nombre, el vencimiento (mantenerlo, quitarlo o ponerlo a N días desde hoy), el límite o las IPs, y pulsa Guardar cambios. Los cambios rigen de inmediato.

Cuando se agrega una API o una función nueva aparece sola como una opción más en esa matriz (para generar y para editar): basta con editar la credencial y activar su casilla de lectura, de escritura o de ambas. Las credenciales con «Todas las APIs» ya la incluyen. No se puede editar una credencial revocada.

Los demás botones de la tabla de credenciales:

BotónQué hace
LápizEdita la credencial y sus permisos
LibroVuelve a mostrar la guía de esa credencial (sin la llave)
RelojMuestra la actividad: las últimas 60 peticiones, con su resultado, IP y tiempo
Flechas circularesRota la llave: crea una nueva con los mismos permisos y deja que la anterior siga funcionando unas horas (o la revoca ya) para que alcances a cambiarla
Pausa / playSuspende o reanuda la credencial sin perderla
PapeleraRevoca la credencial: deja de funcionar al instante y no se puede deshacer

Seguridad#

  • La llave nunca se guarda: en Connecto solo queda su huella (SHA-256). Si la pierdes, rótala o genera otra.
  • Solo por https y solo desde servidores: no pongas la llave en el JavaScript de una página web.
  • Permisos mínimos, vencimiento, límite e IPs por credencial; cada credencial se puede pausar, rotar o revocar sin afectar a las demás.
  • Frenos: tras 30 intentos con llaves no válidas desde una misma IP en 10 minutos, esa IP queda bloqueada un rato.
  • Registro: cada petición queda registrada 90 días (fecha, ruta, resultado, IP, tiempo y qué campos se usaron, no los valores consultados, para no guardar datos personales en el registro). Los cambios que haces en esta pantalla quedan en la auditoría.
  • Los datos de los contactos son personales: consúltalos solo cuando haga falta y revisa con tu abogado el aviso y la autorización de tratamiento de datos (Ley 1581 de 2012) antes de exponer consultas desde una página pública.

Cómo se usa#

  • Dirección base: https://tu-dominio/api/v1
  • Autenticación: en cada petición, el encabezado Authorization: Bearer cnx_TU_LLAVE (también se acepta X-API-Key).
  • Guía propia: GET /api/v1/ayuda devuelve, para la llave que lo pide, las APIs que puede usar, cómo llamarlas y los campos que acepta.
  • Límite: el de cada credencial (120 por minuto por defecto). Al pasarlo responde 429; los encabezados X-RateLimit-Limit, X-RateLimit-Remaining y Retry-After te lo indican. Cada respuesta trae X-Request-Id.
  • Formato: siempre JSON. Fechas en formato ISO 8601 con zona horaria. Los errores llegan así: {"error":{"codigo":"no_encontrado","mensaje":"…"}}.
  • Listas: se piden por páginas con limite (hasta 100) y pagina; la respuesta trae hay_mas.

APIs heredadas#

Estas tres APIs ya existían y siguen funcionando igual; sus permisos se dan en la matriz de «Generar API» o al editar una credencial.

PermisoQué permite
contactos:leerConsultar contactos
contactos:escribirCrear y editar contactos
conversaciones:leerConsultar conversaciones y sus mensajes
oportunidades:leerConsultar oportunidades y embudos
oportunidades:escribirCrear oportunidades (agregar un contacto a un embudo) y cambiarlas de etapa
pedidos:leerConsultar pedidos
pedidos:escribirCrear y actualizar pedidos (incluye pagos, reembolsos y entregas)

Contactos#

PeticiónQué hace
GET /contactosLista (más recientes primero). Filtros: q (texto en nombre, correo o teléfono), email, telefono, actualizado_desde
GET /contactos/{id}Un contacto
POST /contactosCrea un contacto: nombre (obligatorio), apellidos, telefono, email (al menos uno de los dos) y tipo_contacto_id; también acepta numero_documento, tipo_documento, pais, departamento, ciudad y direccion. Si ya existe uno con ese teléfono, correo o número de documento responde 409 con su contacto_id.
PATCH /contactos/{id}Cambia nombre, apellidos, telefono, email o tipo_contacto_id

Cada contacto devuelve: id, nombre, apellidos, telefono, email, pais, idioma, estado, tipo_contacto_id, propietario_id, creado_at, actualizado_at y ultima_actividad_at.

Un contacto creado por la API no tiene autorización para recibir difusiones: la API no la registra por ti. Queda autorizado cuando la persona te escribe o cuando lo marcas desde Connecto. Los cambios hechos por la API quedan en el historial del contacto como «API: nombre de la llave».

Conversaciones y mensajes#

PeticiónQué hace
GET /conversacionesLista. Filtros: estado (open, pending, resolved), contacto_id, actualizada_desde
GET /conversaciones/{id}Una conversación: contacto, canal, estado, asesor, fechas
GET /conversaciones/{id}/mensajesMensajes, del más reciente al más antiguo. limite y antes_de_id para pasar a los anteriores. No incluye archivos adjuntos.

Oportunidades#

PeticiónQué hace
GET /oportunidadesLista. Filtros: estado (abierto, ganado, perdido), contacto_id
GET /oportunidades/{id}Una oportunidad: contacto, embudo, etapa, valor, fechas
GET /embudosLos embudos activos con su identificador y sus etapas (id, nombre, tipo abierta/ganada/perdida): sirve para saber qué embudo_id y etapa_id usar
POST /oportunidadesAgrega un contacto a un proceso de venta: crea su oportunidad en el embudo y la etapa que indiques (permiso oportunidades:escribir)
PATCH /oportunidades/{id}Cambia la etapa de la oportunidad y/o edita sus datos (permiso oportunidades:escribir)

Crear (POST /oportunidades). Cuerpo JSON:

CampoPara qué
contacto_id (o numero_documento, o email)Qué contacto entra al proceso. Obligatorio uno de los tres
embudo_id (o embudo: su nombre o su identificador, el nombre con «_» en lugar de espacios, que ves en Configuración → Oportunidades → Datos del embudo)En qué embudo. Si no lo envías se usa el embudo por defecto
etapa_id (o etapa: su nombre)Etapa abierta de inicio. Por defecto, la primera del embudo
titulo, valor, moneda, producto_id, fecha_cierre_esperada (AAAA-MM-DD), propietario_id, notaOpcionales
Texto
POST /api/v1/oportunidades
{ "numero_documento": "1020304050", "embudo": "Venta de cursos", "etapa": "Carrito", "titulo": "Matrícula Procuraduría", "valor": 325000 }

Responde 201 con la oportunidad (id, embudo, etapa, estado…). Reglas: un contacto solo puede tener una oportunidad abierta por embudo (si ya la tiene responde 409 duplicado con el oportunidad_id existente); la etapa de inicio debe ser una etapa abierta; se ejecutan las acciones automáticas de la etapa de entrada, igual que al crearla desde la pantalla. Si el módulo de Oportunidades está apagado responde 503 modulo_apagado.

Cambiar de etapa (PATCH /oportunidades/{id}). Envía etapa_id (o etapa con su nombre; vale cualquier etapa del embudo de la oportunidad, incluidas Ganado y Perdido) y, si hace falta, motivo_perdida_id y nota. Se aplican las mismas reglas que en la pantalla: transiciones permitidas, datos requeridos por la etapa y motivo obligatorio al perder; si no se cumplen responde 422 con el detalle (movimiento_no_permitido). Si la etapa exige aprobación de un supervisor responde 202 con pendiente_aprobacion. También puedes editar titulo, valor, moneda, producto_id, fecha_cierre_esperada y propietario_id en la misma petición.

Datos del pedido junto con el cambio de etapa. Una etapa puede tener la acción «Cambiar un dato» sobre el pedido de la oportunidad (Configuración → Oportunidades → acciones de la etapa → Cambiar un dato → «Pedido: …»). El valor de ese dato se envía en la misma petición, con el nombre del dato como nombre del campo; al entrar la oportunidad a la etapa, la acción lo guarda en el pedido que está vinculado a ella (el que se creó con su oportunidad_id).

Campo que envíasDato del pedido que cambia
comprobante_urlComprobante de pago: dirección (URL http o https) de la imagen
envio_guiaGuía de envío
envio_metodoMétodo de envío
envio_direccionDirección de envío
notasNotas del pedido

Reglas: el campo solo tiene efecto si la etapa destino tiene la acción correspondiente (si no, se ignora); una URL que no sea http o https responde 422; si el pedido está cancelado o reembolsado, o la oportunidad no tiene pedido, la acción se omite. También se acepta en POST /oportunidades cuando la oportunidad nace directamente en una etapa con esa acción.

Texto
PATCH /api/v1/oportunidades/45
{ "etapa": "Pago confirmado" }

Con el comprobante de pago (la etapa «Pago confirmado» tiene la acción «Cambiar un dato → Pedido: Comprobante de pago»):

Texto
PATCH /api/v1/oportunidades/45
{ "etapa": "Pago confirmado", "comprobante_url": "https://w3.grupogeard.com/comprobantes/GG-261021-7C0451.jpg" }

Las acciones quedan en el historial de la oportunidad (sin usuario, como cambios hechos por la API) y en la bitácora de auditoría con el nombre de la credencial.

Pedidos#

El módulo debe estar encendido (Configuración → Pedidos y compras); si no, responde 503 modulo_apagado.

PeticiónQué hace
GET /pedidosLista (más recientes primero) con totales y estados. Filtros: estado, estado_pago, estado_entrega, fuente, contacto_id, oportunidad_id, cotizacion_id, referencia_externa, q, desde, hasta, limite, pagina
GET /pedidos/{id}El pedido completo: líneas (producto, precio, descuento, IVA, total, entregado), descuento general, envío, totales, pagos y reembolsos
POST /pedidosCrea un pedido para un contacto (permiso pedidos:escribir)
PATCH /pedidos/{id}Actualiza líneas, descuentos, envío, notas; cambia el estado; registra pagos, reembolsos y entregas (permiso pedidos:escribir)

Crear (POST /pedidos). Cuerpo JSON:

CampoPara qué
contacto_id (o numero_documento, o email)El contacto del pedido. Obligatorio uno de los tres
itemsLista de líneas: `{producto_id
descuento_general`{tipo: "pct"
envioUn monto, o {monto, impuesto_pct?, direccion?, metodo?, guia?}
estadoborrador o pendiente (por defecto, el estado inicial de la configuración)
pagosSolo con estado: "pendiente": [{monto, metodo?, referencia?, nota?}]
fuente, fuente_detalle, referencia_externaDe dónde viene: api (por defecto), web, woocommerce u otro. Con referencia_externa repetida (misma fuente) responde 409 pedido_duplicado con el pedido_id, para reintentar sin duplicar
moneda, oportunidad_id, cotizacion_id, responsable_id, notas, terminosOpcionales
comprobante_urlOpcional: URL (http o https) de la imagen del comprobante de pago
complemento_correoOpcional: bloque HTML con el medio de pago y los datos de la cuenta. El correo del pedido lo incrusta tal cual con la variable {{pedido:complemento_correo}} (máx. 20.000 caracteres; se limpia: sin scripts ni formularios, solo estilos en línea, imágenes y enlaces http/https). También se puede cambiar con PATCH /pedidos/{id}
Texto
POST /api/v1/pedidos
{ "numero_documento": "1020304050", "estado": "pendiente", "referencia_externa": "WEB-10234",
  "items": [ { "producto_id": 12, "cantidad": 1, "descuento": { "tipo": "pct", "valor": 10 } }, { "nombre": "Material impreso", "cantidad": 2, "precio": 15000, "impuesto_pct": 0 } ],
  "descuento_general": { "tipo": "valor", "valor": 5000 }, "envio": { "monto": 12000, "direccion": "Calle 1 # 2-3" } }

Responde 201 con el pedido (numero, estado, estado_pago, estado_entrega, líneas y totales).

Variable adicional complemento_correo (texto HTML para el correo del pedido). Además de los datos normales del pedido, la API permite enviar un bloque de HTML en el campo complemento_correo. Sirve para que el correo que Connecto envía por ese pedido (por ejemplo, el de la plantilla «Pedido creado») incluya contenido que solo conoce el sistema que crea el pedido, como el medio de pago y los datos de la cuenta.

Dónde se envíaEn POST /pedidos (al crear) o en PATCH /pedidos/{id} (para cambiarlo). Con texto vacío se quita.
Qué se envíaUna cadena de texto con HTML ya armado. Ejemplo: "complemento_correo": "<div style=\"border:1px solid #1C89C2;padding:12px\"><b>Transferencia bancaria</b><br>Banco X · Cuenta de ahorros <b>123-456</b><br>Titular: Empresa S.A.S.</div>"
Cómo se usa en el correoEn la plantilla de correo se inserta con la variable {{pedido:complemento_correo}} (menú «Insertar variable» → «Pedido: complemento del correo»). Se incrusta tal cual, como HTML, no como texto. La plantilla «Pedido creado» ya la trae.
Si no se envíaLa variable queda vacía y el correo sale sin ese bloque.
Qué se conservaConnecto limpia el HTML por seguridad: elimina <script>, <style>, formularios, <iframe> y atributos de eventos; deja etiquetas de texto y tablas, estilos en línea (style="…"), imágenes y enlaces http/https. No uses clases CSS: no llegan al correo.
TamañoMáximo 20.000 caracteres (si lo supera responde 422).
Buenas prácticasEscapa los valores dinámicos (banco, titular, números) antes de armar el HTML; usa solo estilos en línea; escribe el valor a pagar y la referencia del pedido para que el cliente la ponga en el concepto.
Texto
PATCH /api/v1/pedidos/57
{ "complemento_correo": "<div style=\"font-family:Arial,sans-serif;font-size:14px\"><b>Bre-B</b><br>Llave: <b>@grupogeard</b><br>Titular: Grupo Geard S.A.S.</div>" }

Actualizar (PATCH /pedidos/{id}). Acepta items, descuento_general, envio, notas, responsable_id, estado (solo transiciones válidas), pago / pagos, reembolso y entrega ({estado: "entregado"} o {items: {id_de_linea: cantidad}}). Los productos, descuentos y el envío solo se cambian mientras el pedido es borrador (o pendiente sin pagos). Todo se aplica en una sola operación: si algo falla (422), no se guarda nada.

Texto
PATCH /api/v1/pedidos/57
{ "pago": { "monto": 150000, "metodo": "transferencia", "referencia": "TRX-9981" }, "entrega": { "estado": "entregado" } }

Ejemplo#

Texto
curl -H "Authorization: Bearer cnx_TU_LLAVE" "https://tu-dominio/api/v1/[email protected]"

curl -X POST -H "Authorization: Bearer cnx_TU_LLAVE" -H "Content-Type: application/json" \
     -d '{"nombre":"Ana Pérez","telefono":"+57 300 123 4567","email":"[email protected]"}' \
     "https://tu-dominio/api/v1/contactos"

Webhooks#

  1. Pulsa Nuevo webhook, escribe un nombre y la dirección de tu sistema (debe empezar por https:// y ser pública).
  2. Marca los eventos que quieres recibir.
  3. Copia el secreto (whsec_…): lo necesitas para verificar la firma y no se vuelve a mostrar.
  4. Pulsa Probar para enviar un evento de prueba y ver si tu sistema responde.
EventoCuándo ocurre
contacto.creadoSe creó un contacto
contacto.actualizadoCambió el nombre, teléfono, correo, tipo, propietario o estado de un contacto
conversacion.creadaEmpezó una conversación
conversacion.resueltaSe resolvió una conversación
mensaje.recibidoLlegó un mensaje de un contacto (incluye el texto)
oportunidad.creadaSe creó una oportunidad
oportunidad.ganada / oportunidad.perdidaSe cerró una oportunidad

Cada envío es un POST JSON con id, evento, ocurrio_at y datos (los identificadores y los datos principales; para el detalle consulta la API con esos identificadores).

Verificar que viene de Connecto#

Cada envío trae X-Connecto-Timestamp y X-Connecto-Signature: v1=…, que es el HMAC-SHA256 de marca_de_tiempo + "." + cuerpo con tu secreto. Verifica la firma y descarta envíos con más de 5 minutos de antigüedad.

PHP
$cuerpo = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_CONNECTO_TIMESTAMP'];
$esperada = 'v1=' . hash_hmac('sha256', $ts . '.' . $cuerpo, 'whsec_TU_SECRETO');
if (!hash_equals($esperada, $_SERVER['HTTP_X_CONNECTO_SIGNATURE']) || abs(time() - $ts) > 300) { http_response_code(401); exit; }

Si tu sistema falla#

Tu sistema debe responder con un código 2xx en menos de 8 segundos. Si no, Connecto reintenta a 1 minuto, 5 minutos, 30 minutos, 2 horas y 6 horas; después la entrega queda fallida (puedes pulsar Reintentar). Tras 30 fallos seguidos el webhook se desactiva solo y se avisa a los administradores; cuando lo arregles, vuelve a activarlo con su interruptor. Los envíos pueden repetirse: usa el id para no procesar dos veces lo mismo. El historial de entregas se conserva 14 días.

Seguridad#

  • Solo se envía a direcciones https públicas: no se aceptan direcciones internas ni con usuario y contraseña, y la conexión se fija a la dirección ya validada.
  • Los webhooks se alimentan de la base de datos, así que no afectan el funcionamiento de los chats, correos ni llamadas; si no hay webhooks activos no se hace nada.

<!-- Fuente: tenant-app/public/api/v1/index.php, tenant-app/public/api/api_admin.php, tenant-app/views/partials/cfg_api.php, shared/src/Core/ApiLlaves.php, shared/src/Core/Webhooks.php, tenant-app/public/internal/difusiones_tick.php, docker/nginx/app.conf, db/migrations/0135_api_publica_webhooks.sql -->

¿Te fue útil esta página?
Última actualización: 14/11/2026