Documentación · Opengency

Inicio rápido

Regístrate e inicia sesión en la app Web.
Crea un nuevo flujo de trabajo: el lienzo ya tiene un nodo de «Disparador», que es el punto de partida.
Arrastra un nodo de «Acción», elige un conector (por ejemplo, Correo) y completa su configuración.
Conecta el nodo de disparador con el nodo de acción y guarda.
Haz clic en Ejecutar, introduce unos datos de prueba y revisa el resultado de cada nodo en el registro de ejecución.

Guía de edición de flujos de trabajo

Un flujo de trabajo se compone de tres tipos de nodos:

Disparador: el punto de partida; cada flujo de trabajo tiene exactamente uno. Los datos que llegan al ejecutarlo son su salida.
Condición: realiza una comprobación, con salidas «Sí» y «No»; solo se recorre la rama que coincide.
Acción: llama a un conector, por ejemplo para enviar un correo, llamar a una API o escribir en una base de datos.

Al guardar se comprueba: que haya exactamente un nodo de disparador, que toda conexión tenga ambos extremos conectados, que no se formen ciclos, que las salidas de las condiciones estén etiquetadas como Sí/No y que los campos obligatorios de cada acción estén completos. Cualquier problema se señala uno por uno.

En cada ejecución, el flujo avanza desde el nodo de disparador siguiendo las conexiones; si un nodo falla, toda la ejecución se detiene de inmediato y se marca como fallida.

Condiciones

Una condición tiene un valor izquierdo, un operador y un valor derecho; cualquiera de los dos lados puede ser un valor fijo o una referencia (ver la siguiente sección).

Operador	Significado	Ejemplo
eq / ne	igual / distinto	$.input.status eq "paid"
gt / gte	mayor que / mayor o igual que	$.input.amount gt 1000
lt / lte	menor que / menor o igual que	$.input.stock lt 10
in	el valor izquierdo está en la lista de la derecha	$.input.city in ["北京", "上海"]
contains	el valor izquierdo contiene el valor derecho	$.input.tags contains "VIP"
exists	el campo existe y no está vacío	$.input.coupon exists

Si el campo referenciado no existe, exists se evalúa como «No», y el resto de operadores también se evalúan como «No».

Paso de valores entre nodos

En la configuración de una condición o una acción, cualquier valor que empiece por $. se reemplaza con los datos de la ejecución:

$.input.amount          运行时传入数据的 amount 字段
$.query.data.0.name     节点 query 输出中 data 列表第 1 项的 name
$.notify.status         节点 notify 输出的 status

Cuando el valor completo de un campo es exactamente una referencia, el reemplazo conserva su tipo original (números, listas y objetos funcionan igual). Para insertar datos en medio de un texto, usa {{$.path}}:

大额订单 {{$.input.order_id}}：金额 {{$.input.amount}}，请风控复核

Las cadenas se insertan tal cual; los números, listas y objetos se convierten a JSON; los valores vacíos se insertan como vacío.
Si la ruta no existe, se reemplaza por nada (una referencia de valor completo queda vacía); esto no hace fallar al nodo, pero se señala en el paso correspondiente del registro de ejecución.
Solo cuentan como referencia los valores que empiezan por $.; por ejemplo, «$100 de descuento» es solo texto normal.
El asunto y el cuerpo del correo admiten además plantillas {{variable}}, con variables tomadas de la salida de un nodo anterior.

Guía de conectores

De dónde vienen la dirección y las credenciales de cada conector, dónde está la documentación oficial y qué hacer ante errores habituales. El panel «¿Cómo obtengo esta información?» situado encima de cada formulario de conector en la aplicación resume esta guía.

HTTP

Pasos de configuración

Ten lista la URL del endpoint (url) y el método de la solicitud (GET, POST, …).
Si la API necesita autenticación, elige basic o bearer en auth_type e introduce el usuario y la contraseña o el token. No pongas las credenciales directamente en headers: se guardarían en texto plano.

Documentación oficial ↗

Obligatorio: url
Opcional: method (GET por defecto), headers, body, query_params, auth_type (none / basic / bearer), timeout, retries

Si body está vacío, se envía la salida del nodo anterior. Solo puede acceder a direcciones públicas.

Errores frecuentes

«not a public address»: el destino es una dirección interna o local (incluso si una redirección termina en una), y se bloquea por seguridad.
Solo se admiten URL http y https.
Cuando body está vacío, se envía la salida del nodo anterior.
El tiempo de espera predeterminado es de 30 segundos y puede ser de hasta 60.

DingTalk

Pasos de configuración

Abre el grupo de DingTalk → Configuración del grupo → Asistente del grupo → Añadir robot → Personalizado (mediante Webhook).
En la configuración de seguridad elige Firma o Palabras clave personalizadas (puedes activar ambas). Con Firma, copia en secret la clave que empieza por SEC. Con palabras clave, escribe una palabra que siempre aparezca en tus mensajes y añade también Opengency como palabra clave, porque «Probar conexión» envía el texto «Opengency 连接测试».
Copia la URL del webhook generada en webhook_url.

Documentación oficial ↗

Obligatorio: webhook_url
Opcional: secret (clave de firma), msg_type (text / markdown / link / card), message, at_mobiles, at_all

Obtén webhook_url en la configuración del grupo de DingTalk → Asistente del grupo → Añadir bot. «Probar conexión» envía de verdad un mensaje de prueba al grupo. El texto del mensaje de prueba es fijo: «Opengency 连接测试». Si el robot usa palabras clave personalizadas, una de ellas debe ser «Opengency»; si no, la prueba se rechaza por no coincidir la palabra clave (no ocurre si solo está activada la firma).

Errores frecuentes

La firma no coincide (sign not match): el robot usa Firma, pero secret está vacío o es incorrecto. Introduce la clave de firma que empieza por SEC, no el access_token de la URL del webhook.
La palabra clave no coincide: el mensaje no contiene ninguna de las palabras clave del robot. Incluye una palabra clave en el mensaje, o añade al robot una palabra clave que tus mensajes contengan.
Marca de tiempo no válida: el reloj del servidor donde se ejecuta Opengency difiere del de DingTalk en más de una hora. Corrige la hora del servidor.
«Probar conexión» no es una simulación: de verdad publica «Opengency 连接测试» en el grupo.

WeCom

Pasos de configuración

Abre el grupo de WeCom → «…» en la esquina superior derecha → Robots del grupo → Añadir robot.
La URL del webhook se muestra en cuanto se crea el robot.
Copia esa URL en webhook_url.

Documentación oficial ↗

Obligatorio: webhook_url
Opcional: msg_type (text / markdown / card), message, at_mobiles, at_all, url y title (para card)

Obtén webhook_url en tu grupo de WeCom → Bot del grupo; la key de la URL es la credencial. Las menciones @ solo funcionan con text. «Probar conexión» envía de verdad un mensaje de prueba al grupo.

Errores frecuentes

La key en la URL del webhook es la credencial: cualquiera que tenga la URL puede publicar en el grupo. Si se filtra, elimina el robot del grupo y añade uno nuevo.
Las menciones @ solo funcionan con el tipo text. El tipo card también necesita url (adónde enlaza la tarjeta); sin eso, no se puede guardar.
WeCom limita la frecuencia de los robots que publican demasiado a menudo, y los mensajes dejan de llegar. No programes las ejecuciones demasiado seguidas.
«Probar conexión» publica de verdad un mensaje de prueba en el grupo.

Feishu

Pasos de configuración

Abre el grupo de Feishu → Configuración → Robots del grupo → Añadir robot → Robot personalizado.
Por seguridad puedes activar Verificación por firma e introducir en secret la clave que se muestra en esa página. Las palabras clave personalizadas también funcionan; añade ahí «Opengency» como palabra clave también.
Copia la URL del webhook generada en webhook_url.

Documentación oficial ↗

Obligatorio: webhook_url
Opcional: secret (si el bot tiene activada la verificación de firma), msg_type (text / post / markdown / card), message, title, at_open_ids, at_all

Obtén webhook_url en la configuración del grupo de Feishu → Bots del grupo → Bot personalizado. «Probar conexión» envía de verdad un mensaje de prueba al grupo.

Errores frecuentes

La verificación por firma está activada pero secret está vacío o es incorrecto: Feishu rechaza el mensaje (falló la verificación de firma). Puedes volver a ver la clave en la configuración del robot.
Hay palabras clave personalizadas configuradas pero el mensaje no contiene ninguna: el mensaje se rechaza.
at_open_ids necesita open_ids que empiecen por ou_, no números de teléfono ni nombres.
«Probar conexión» publica de verdad un mensaje de prueba en el grupo.

Slack

Pasos de configuración

Abre https://api.slack.com/apps, crea una app (o elige una existente) y activa Incoming Webhooks en Features.
Haz clic en Add New Webhook to Workspace, elige el canal donde publicar y autoriza.
Copia la URL del webhook generada (empieza por https://hooks.slack.com/services/) en webhook_url.

Documentación oficial ↗

Obligatorio: webhook_url
Opcional: message, username, icon_emoji, channel

webhook_url es en sí misma la credencial (cualquiera que la tenga puede publicar en ese canal); Opengency la guarda cifrada y la enmascara en la interfaz y los registros. Un webhook de una app de Slack actual siempre publica en el canal elegido al crearlo, así que username, icon_emoji y channel se ignoran; para publicar en otro sitio, crea otro webhook. «Probar conexión» publica de verdad un mensaje de prueba en el canal.

Errores frecuentes

no_service: el webhook se eliminó, se desactivó, o la dirección es incorrecta. Revisa la página de Incoming Webhooks de la app, y vuelve a crearlo y actualiza la conexión si es necesario.
channel_not_found: el canal no existe, o este webhook no tiene acceso a él. Comprueba el nombre del canal, o vuelve a crear el webhook para el canal correcto.
channel_is_archived: el canal está archivado. Desarchívalo, o usa el webhook de otro canal.
action_prohibited: un administrador del espacio de trabajo restringe lo que este webhook puede hacer. Contacta con el administrador de Slack.
invalid_payload o no_text: el mensaje está vacío o mal formado. Asegúrate de que message no esté vacío.
HTTP 429: estás publicando con demasiada frecuencia y Slack te limita. Inténtalo más tarde, y no programes ejecuciones demasiado seguidas.
«Probar conexión» no es una simulación: de verdad publica «Opengency connection test» en el canal.

Teams

Pasos de configuración

En Teams, abre el canal donde publicar → el «…» junto al nombre del canal → Workflows.
Elige la plantilla «Send webhook alerts to a channel», selecciona el equipo y el canal según se indique, y guarda.
Una vez creado, copia la URL del webhook desde la página de detalles del flujo en webhook_url.

Documentación oficial ↗

Obligatorio: webhook_url
Opcional: message, title

webhook_url es en sí misma la credencial (el sig de la dirección es la firma del flujo); Opengency la guarda cifrada y la enmascara en la interfaz y los registros. Solo se admiten webhooks de Workflows (Power Automate); los antiguos webhooks del Office 365 connector (outlook.office.com/webhook/…) están siendo retirados por Microsoft y no son compatibles. Los mensajes se envían como una Adaptive Card: title es el título en negrita en la parte superior de la tarjeta, message es el cuerpo (el Markdown básico funciona). Un mensaje no puede superar los 28 KB; un cuerpo demasiado largo se trunca. «Probar conexión» publica de verdad un mensaje de prueba en el canal.

Errores frecuentes

HTTP 401 / 403 (dirección no válida o revocada): la firma en la URL del webhook es incorrecta o se regeneró. Abre el flujo en Teams, copia la dirección más reciente y actualiza la conexión.
HTTP 404 (flujo no encontrado): puede que el flujo se haya eliminado. Vuelve a crearlo a partir de la plantilla y actualiza la dirección en la conexión.
Un mensaje indicando que el flujo está desactivado: actívalo de nuevo en la app de Teams Workflows o en Power Automate. Un flujo pertenece a quien lo creó, y puede desactivarse si esa persona se va o su cuenta se deshabilita; pide a un administrador que se lo transfiera a otra persona.
HTTP 400 (el disparador no aceptó el mensaje): asegúrate de que el flujo se creó a partir de la plantilla «Send webhook alerts to a channel», de que su disparador es When a Teams webhook request is received, y de que no has cambiado el formato de mensaje que acepta.
HTTP 429: Teams limita la tasa de los webhooks (unas cuatro solicitudes por segundo), y publicar con demasiada frecuencia se rechaza. Inténtalo más tarde, y no programes ejecuciones demasiado seguidas.
«Probar conexión» no es una simulación: de verdad publica «Opengency connection test» en el canal.

Correo electrónico

Pasos de configuración

Activa el SMTP en la configuración de tu proveedor de correo.
Genera una contraseña de aplicación (algunos proveedores la llaman código de autorización). La mayoría de proveedores, incluidos Gmail, Outlook y Yahoo, no permiten que apps externas envíen correo con tu contraseña de inicio de sesión.
Anota el servidor SMTP y el puerto, por ejemplo smtp.gmail.com:587 o smtp.qq.com:465.
Pon tu dirección en sender_email y la contraseña de aplicación del paso 2 en sender_password.

Documentación oficial ↗

Obligatorio: smtp_server, sender_email, sender_password, to
Opcional: smtp_port (por defecto 587), smtp_ssl (auto / implicit / starttls / none), use_tls, cc, bcc, subject, body, format (text / html / markdown)

subject y body admiten {{variables}}, tomadas de la salida de un nodo anterior. La mayoría de proveedores requieren una contraseña de aplicación en lugar de tu contraseña de inicio de sesión.

Errores frecuentes

Fallo de autenticación: sender_password es tu contraseña de inicio de sesión. Usa en su lugar una contraseña de aplicación o un código de autorización.
Tiempo de espera agotado o fallo en el protocolo de enlace: el puerto y el cifrado no coinciden. El puerto 465 usa TLS implícito y el 587 usa STARTTLS; con smtp_ssl en auto se elige el correcto según el puerto, así que rara vez hace falta cambiarlo.
«not a public address»: el servidor SMTP resuelve a una dirección interna o local (habitual en servidores de correo internos) y se bloquea por seguridad. Usa un servidor SMTP accesible desde internet público.
to necesita al menos un destinatario; separa varios con comas.

SQLite

Pasos de configuración

No hace falta cuenta ni contraseña: el archivo de la base de datos está en tu propio directorio de datos.
Pon solo un nombre de archivo en database_path, por ejemplo orders.db; el archivo se crea si no existe.

Documentación oficial ↗

Obligatorio: database_path, sql
Opcional: params, operation (select / insert / update / delete / execute), return_type (dict por defecto), timeout

database_path solo necesita un nombre de archivo (por ejemplo, orders.db); el archivo se guarda automáticamente en tu propio directorio de datos. Usa marcadores ? en el SQL, con los valores en params.

Errores frecuentes

«no such table»: un nombre de archivo mal escrito no da un error de archivo no encontrado. En su lugar, se crea una base de datos nueva y vacía, así que la tabla no está. Comprueba primero el nombre del archivo.
database_path es solo un nombre de archivo. La base de datos se queda dentro de tu propio directorio de datos y no puede acceder a archivos de otro lugar.
Usa ? como marcador de posición, con los valores en params.

MySQL

Pasos de configuración

Ten listos el host, el puerto (por defecto 3306), el usuario, la contraseña y el nombre de la base de datos.
Crea una cuenta de base de datos dedicada para esta conexión; si solo se hacen consultas, concede únicamente SELECT.
Asegúrate de que la base de datos sea accesible desde internet público: el firewall o el grupo de seguridad de tu proveedor de nube deben permitir el puerto.

Documentación oficial ↗

Obligatorio: host, user, password, database, sql
Opcional: port (3306 por defecto), ssl (disabled / required / verify), params, read_only (activado por defecto), max_rows (1000 por defecto), timeout

Usa marcadores %s en el SQL, con los valores en params (un % literal debe escribirse %% cuando se usan params). Es de solo lectura por defecto; desactiva read_only para escribir. Para nodos de solo lectura, usa una cuenta con privilegios únicamente de SELECT. Solo se ejecuta una instrucción a la vez, y solo puede acceder a direcciones públicas.

Errores frecuentes

«not a public address»: host es una dirección interna (10.x, 172.16–31.x, 192.168.x, 127.0.0.1). El conector solo puede acceder a direcciones públicas, así que la base de datos necesita un punto de acceso público.
Se rechazan las escrituras: read_only está activado por defecto y el SQL se ejecuta en una transacción de solo lectura. Desactiva read_only cuando realmente necesites escribir, y comprueba que la cuenta tenga permisos de escritura.
Los resultados están incompletos: por defecto se devuelven como máximo 1000 filas (max_rows, hasta 10000); lo que exceda se corta y se marca como truncated.
Solo se ejecuta una sentencia SQL a la vez. Usa %s como marcador de posición con los valores en params; no construyas los valores dentro de la cadena SQL.
Tiempo de espera de conexión agotado: normalmente el firewall o el grupo de seguridad no está dejando pasar el puerto.

Webhook

Pasos de configuración

Ten lista una URL pública que acepte solicitudes POST y ponla en webhook_url.
Si el receptor debe poder confirmar que una solicitud viene de tu flujo de trabajo, acuerda una clave y ponla en secret_key.
En el lado receptor: cada solicitud incluye X-Webhook-Timestamp; si se configura secret_key, también incluye X-Webhook-Signature, el HMAC-SHA256 en hexadecimal de (timestamp + "." + raw_body) calculado con esa clave.

Obligatorio: webhook_url
Opcional: secret_key, verify_signature, event_types, retry_count, timeout

Cuando se configura secret_key, las solicitudes incluyen la cabecera X-Webhook-Signature (HMAC-SHA256), que el receptor puede usar para verificarlas.

Errores frecuentes

«Probar conexión» envía de verdad un evento con event_type ping al receptor.
Una respuesta 4xx o 500, o un tiempo de espera agotado, no se reintenta (el receptor puede haberla procesado ya). Solo se reintentan los códigos 429, 502, 503, 504 y las conexiones que nunca llegaron a establecerse.
«not a public address»: la URL de recepción es una dirección interna o local.
Un event_types vacío reenvía todo; si tiene elementos, se omiten los datos cuyo event_type no esté en la lista.

Restricción de seguridad: HTTP, DingTalk, WeCom, Feishu, Slack, Teams, correo electrónico, MySQL y Webhook solo pueden acceder a direcciones públicas (se rechazan direcciones internas como 127.0.0.1, 10.x y 192.168.x); SQLite solo puede acceder a tu propio directorio de datos.

Claves de API

Para que scripts y otros sistemas llamen a la API, por ejemplo un script programado que dispara un flujo de trabajo. Crea una en la app, en Cuenta → Claves de API; la clave completa se muestra solo una vez, así que guárdala de inmediato: después, la lista solo muestra los primeros caracteres, para identificarla. Límites: 1 en Free, 5 en Pro, ilimitadas en Business y Enterprise (contando solo las claves no revocadas).

curl -X POST https://app.opengency.ai/api/executions/workflows/<工作流 ID>/execute \
  -H "Authorization: Bearer ofk_…" \
  -H "Content-Type: application/json" \
  -d '{"input_data": {"order_id": 7}}'

Tiene los mismos permisos que la cuenta que la creó; las ejecuciones que dispara se etiquetan como «API» en el registro de ejecución, mostrando los primeros caracteres de la clave.
Gestionar claves de API, cambiar tu contraseña o eliminar tu cuenta requiere iniciar sesión con la contraseña de tu cuenta; una clave de API no puede hacer nada de eso.
Revocar una clave la desactiva de inmediato (devuelve 401). Cambiar la contraseña no invalida las claves existentes; si sospechas que se filtró una, revócalas una por una.
Guarda las claves solo en el servidor: nunca las pongas en código del front-end ni las compartas en un chat.

Preguntas frecuentes

¿Por qué mi nodo HTTP dice "not a public address"?: El destino es una dirección interna o local y se bloqueó por seguridad. Usa una dirección accesible públicamente.
¿Puedo recibir un aviso si falla la ejecución de un flujo de trabajo?: Sí, en todos los planes. En Cuenta → Notificaciones de fallos, elige enviarlas al correo de tu cuenta o a una conexión guardada de DingTalk, WeCom, Feishu o correo electrónico. Los fallos repetidos en unos 10 minutos se agrupan en un solo mensaje, con el número de fallos de cada flujo de trabajo, el nodo con el error y un enlace a los detalles; las ejecuciones canceladas manualmente no generan notificación.
¿Se pueden hacer bucles?: Todavía no: los flujos de trabajo no pueden formar un ciclo, y al guardar se avisará si lo intentas.
¿Se pueden ejecutar flujos de trabajo de forma programada?: Sí. En el editor, cambia el disparador a «Programado», elige una frecuencia (cada N minutos, cada hora, diaria, semanal) o escribe tu propia expresión cron, y elige una zona horaria; guarda el flujo de trabajo y luego activa el interruptor «Habilitado» en la página de detalle del flujo de trabajo. Free permite 1 flujo de trabajo programado activo a la vez; Pro permite 10.