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:
| API | Qué hace | Página |
|---|---|---|
| Consulta de contactos | Busca contactos por uno o varios campos y devuelve todos sus datos y sus redes o canales | Consulta de contactos |
| Contactos (listar, crear y editar) | Lista contactos y crea o edita los datos básicos | Más abajo |
| Conversaciones y mensajes | Lee conversaciones y mensajes | Más abajo |
| Oportunidades | Lee oportunidades y embudos, agrega un contacto a un embudo y la mueve de etapa | Más abajo |
| Pedidos | Lee, 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:
- 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.
- Webhooks: los avisos que Connecto envía a otros sistemas.
Generar una credencial («Generar API»)#
- Pulsa Generar API. Escribe el nombre del sistema que la usará (por ejemplo «Sitio web») y, si quieres, para qué se usa.
- 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.
- 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). - 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ón | Qué hace |
|---|---|
| Lápiz | Edita la credencial y sus permisos |
| Libro | Vuelve a mostrar la guía de esa credencial (sin la llave) |
| Reloj | Muestra la actividad: las últimas 60 peticiones, con su resultado, IP y tiempo |
| Flechas circulares | Rota 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 / play | Suspende o reanuda la credencial sin perderla |
| Papelera | Revoca 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 aceptaX-API-Key). - Guía propia:
GET /api/v1/ayudadevuelve, 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 encabezadosX-RateLimit-Limit,X-RateLimit-RemainingyRetry-Afterte lo indican. Cada respuesta traeX-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) ypagina; la respuesta traehay_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.
| Permiso | Qué permite |
|---|---|
contactos:leer | Consultar contactos |
contactos:escribir | Crear y editar contactos |
conversaciones:leer | Consultar conversaciones y sus mensajes |
oportunidades:leer | Consultar oportunidades y embudos |
oportunidades:escribir | Crear oportunidades (agregar un contacto a un embudo) y cambiarlas de etapa |
pedidos:leer | Consultar pedidos |
pedidos:escribir | Crear y actualizar pedidos (incluye pagos, reembolsos y entregas) |
Contactos#
| Petición | Qué hace |
|---|---|
GET /contactos | Lista (más recientes primero). Filtros: q (texto en nombre, correo o teléfono), email, telefono, actualizado_desde |
GET /contactos/{id} | Un contacto |
POST /contactos | Crea 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.
Conversaciones y mensajes#
| Petición | Qué hace |
|---|---|
GET /conversaciones | Lista. Filtros: estado (open, pending, resolved), contacto_id, actualizada_desde |
GET /conversaciones/{id} | Una conversación: contacto, canal, estado, asesor, fechas |
GET /conversaciones/{id}/mensajes | Mensajes, del más reciente al más antiguo. limite y antes_de_id para pasar a los anteriores. No incluye archivos adjuntos. |
Oportunidades#
| Petición | Qué hace |
|---|---|
GET /oportunidades | Lista. Filtros: estado (abierto, ganado, perdido), contacto_id |
GET /oportunidades/{id} | Una oportunidad: contacto, embudo, etapa, valor, fechas |
GET /embudos | Los 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 /oportunidades | Agrega 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:
| Campo | Para 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, nota | Opcionales |
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ías | Dato del pedido que cambia |
|---|---|
comprobante_url | Comprobante de pago: dirección (URL http o https) de la imagen |
envio_guia | Guía de envío |
envio_metodo | Método de envío |
envio_direccion | Dirección de envío |
notas | Notas 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.
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»):
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ón | Qué hace |
|---|---|
GET /pedidos | Lista (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 /pedidos | Crea 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:
| Campo | Para qué |
|---|---|
contacto_id (o numero_documento, o email) | El contacto del pedido. Obligatorio uno de los tres |
items | Lista de líneas: `{producto_id |
descuento_general | `{tipo: "pct" |
envio | Un monto, o {monto, impuesto_pct?, direccion?, metodo?, guia?} |
estado | borrador o pendiente (por defecto, el estado inicial de la configuración) |
pagos | Solo con estado: "pendiente": [{monto, metodo?, referencia?, nota?}] |
fuente, fuente_detalle, referencia_externa | De 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, terminos | Opcionales |
comprobante_url | Opcional: URL (http o https) de la imagen del comprobante de pago |
complemento_correo | Opcional: 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} |
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ía | En POST /pedidos (al crear) o en PATCH /pedidos/{id} (para cambiarlo). Con texto vacío se quita. |
| Qué se envía | Una 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 correo | En 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ía | La variable queda vacía y el correo sale sin ese bloque. |
| Qué se conserva | Connecto 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ño | Máximo 20.000 caracteres (si lo supera responde 422). |
| Buenas prácticas | Escapa 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. |
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.
PATCH /api/v1/pedidos/57
{ "pago": { "monto": 150000, "metodo": "transferencia", "referencia": "TRX-9981" }, "entrega": { "estado": "entregado" } }Ejemplo#
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#
- Pulsa Nuevo webhook, escribe un nombre y la dirección de tu sistema (debe empezar por
https://y ser pública). - Marca los eventos que quieres recibir.
- Copia el secreto (
whsec_…): lo necesitas para verificar la firma y no se vuelve a mostrar. - Pulsa Probar para enviar un evento de prueba y ver si tu sistema responde.
| Evento | Cuándo ocurre |
|---|---|
contacto.creado | Se creó un contacto |
contacto.actualizado | Cambió el nombre, teléfono, correo, tipo, propietario o estado de un contacto |
conversacion.creada | Empezó una conversación |
conversacion.resuelta | Se resolvió una conversación |
mensaje.recibido | Llegó un mensaje de un contacto (incluye el texto) |
oportunidad.creada | Se creó una oportunidad |
oportunidad.ganada / oportunidad.perdida | Se 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.
$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 -->