Fuentes y claves
Consulta un catálogo o envía un pedido a otro servicio: guarda su dirección y clave de acceso y configura la solicitud en una reacción.
En esta página
Si los productos están en tu sitio web, el bot puede consultar allí el catálogo y, cuando alguien haga un pedido, enviar los datos de vuelta. Para ello el servicio necesita una API, una interfaz para que dos programas intercambien datos.
En Conexiones → API propia → Fuentes, guarda la conexión con el servicio, llamada conector. Contiene la dirección de su API y los ajustes de las solicitudes. En Conexiones → Claves, añade los datos de acceso. Después, en una reacción, elige la conexión en Consulta a la fuente o Escribir en la fuente. Si el servicio tiene una configuración preparada, consulta primero Integraciones.
Conectores (Fuentes)
En Fuentes, cada conector tiene Nombre, Tipo, URL base, Credenciales y Encabezados:
| Tipo | Para qué sirve | Qué debes tener en cuenta |
|---|---|---|
| REST | Cualquier API HTTP/JSON | Indica la dirección y los datos de acceso del servicio externo |
| OzmaDB | Tu base OzmaDB/FunDB | Necesita la raíz de su API REST; leer consultas guardadas (view) tiene una configuración propia |
| IMAP | Conexiones antiguas | No se pueden crear conexiones IMAP nuevas. Las guardadas siguen en la lista como «no admitidas» y se pueden borrar normalmente |
El botón Probar hace una solicitud de prueba y muestra el estado y el tiempo de respuesta, o un error. Así puedes comprobar la URL y la clave.
Credenciales (Claves)
Abre Claves. Elige el método de acceso indicado por la documentación del servicio externo. Las claves se guardan cifradas:
| Método | Datos necesarios |
|---|---|
| Clave API | Clave y nombre del encabezado, Authorization por defecto |
| Token Bearer | Token para el encabezado Authorization: Bearer |
| OAuth2 (password) | Token URL, Client ID/Secret, usuario, contraseña y scope |
| OAuth2 (refresh) | Token URL, Client ID/Secret, refresh token y scope |
Con OAuth2, GetMyBot obtiene un token de acceso temporal y lo renueva cuando caduca o el servicio responde 401. Si el servicio entrega un refresh token nuevo, la plataforma lo guarda. Al editar una credencial, dejar vacío un campo secreto significa conservar su valor anterior.
Leer y escribir desde reacciones
- Consulta a la fuente (
ds_query): lee datos y los guarda en el contexto temporal de la reacción (ctx). Indica la ruta de la solicitud, la ruta a la lista dentro de la respuesta (JSONPath) y el nombre del resultado. Una lista de productos guardada comoproductspuede alimentar botones dinámicos o un bucle de lista. - Escribir en la fuente (
ds_write): envía datos conPOST,PUToDELETEy un cuerpo JSON.
Cuerpo de la solicitud, reintentos y comprobación de la respuesta
Puedes construir el cuerpo de POST o PUT en Solicitud web y Escribir en la fuente como un Typed JSON body: cada valor tiene su propio tipo (texto, número, booleano, JSON o null) y admite sustituciones. Así un número no se convierte en texto y no tienes que escapar a mano los objetos anidados. Por ejemplo, para una solicitud:
{
"customer": { "name": "{{param.name}}", "phone": "{{user.phone}}" },
"amount": 4900,
"paid": false
}
Los cuerpos de texto anteriores siguen funcionando; al cambiar el modo del cuerpo se conserva lo que ya introdujiste.
Los reintentos (retry_count) se aplican solo a errores de red y respuestas 429 o 5xx. Las demás respuestas 4xx no se reintentan. Pueden reintentarse GET, HEAD, OPTIONS, PUT y DELETE. Para POST y PATCH, debes añadir tú mismo el encabezado Idempotency-Key: así indicas que la API receptora sabe descartar duplicados por esa clave. La plataforma también envía una clave propia por ejecución de paso, pero por sí sola no habilita los reintentos de POST o PATCH; si no aportas tu clave, el primer fallo es definitivo para evitar pedidos duplicados. La plataforma tampoco reintenta por su cuenta las escrituras de integraciones y CRM cuyo resultado sea incierto. La excepción es una solicitud web con tu propio Idempotency-Key.
Comprobar la respuesta del conector. En el editor de una conexión REST, Check the connection response envía un único GET mediante la conexión guardada, con la ruta y los parámetros indicados, sin sustituciones. Muestra el estado, el tipo y hasta 64 KiB del cuerpo. No escribe nada. Si devuelve JSON, puedes usarlo como ejemplo para Parse response.
Parse response está disponible en todas las acciones con datos externos: solicitud web, consulta y escritura en una fuente, IA, Google Sheets, Google Drive, GetCourse y acciones de CRM. Action result es el resultado normalizado de la acción; Full response es el cuerpo antes de procesarlo. Las reglas se aplican juntas: si falla una, no se guarda ninguna variable.
Para una solicitud aislada sin conector guardado, usa Solicitud web. Para descargar el texto de una página, usa Cargar URL. Consulta Acciones.
Vistas y tablas de OzmaDB
Guarda una conexión de tipo OzmaDB, selecciónala en Consulta a la fuente o Escribir en la fuente y activa el modo OzmaDB. Las solicitudes HTTP existentes conservan su modo y parámetros generales. Si cambias el modo expresamente, los campos HTTP permanecen en la acción y la configuración Ozma se recupera mientras el editor siga abierto.
Para leer, indica nombres fijos en Schema y View, o pulsa Load catalog. Load more añade otras páginas del catálogo sin perder el objeto elegido. Load arguments and fields propone argumentos según los metadatos. Para cada argumento, indica el nombre, tipo y valor. Si no tienes acceso al catálogo o sus metadatos, aún puedes introducir el objeto y los valores manualmente.
Una vista (view) es una consulta guardada que puede combinar tablas y calcular valores. Se elige para leer. Para crear o actualizar un registro, elige aparte una tabla Entity.
Por ejemplo, para leer usr.people_by_team con el argumento numérico team_id:
{
"connection": "ozma",
"ozma": {
"schema": "usr",
"view": "people_by_team",
"args": { "team_id": { "type": "number", "value": "42" } },
"limit": 100,
"offset": 0
},
"save_to_ctx": "people"
}
En ctx.people se guarda una lista de objetos con los nombres de las columnas, por ejemplo [{"id":7,"name":"Ana"}]. Puedes usarla en un bucle de lista y en las acciones siguientes. El tamaño de página es 100 por defecto, 500 como máximo; el desplazamiento permitido es de 0 a 100000. Si lees varias páginas, define un orden estable en la vista.
Preview read solo lee datos y muestra 20 filas como máximo. Sus argumentos deben ser valores literales, sin sustituciones del evento. Para comprobar una acción con variables, sustitúyelas temporalmente por valores de prueba. No existe vista previa de una escritura.
Para escribir, elige Schema y la tabla Entity, selecciona Insert o Update y añade campos con sus tipos. Una actualización exige un Record ID positivo, que también puede venir de una acción anterior:
{
"connection": "ozma",
"ozma": {
"schema": "usr",
"entity": "person",
"operation": "update",
"id": "{{ctx.person_id}}",
"fields": {
"name": { "type": "string", "value": "{{text}}" },
"active": { "type": "boolean", "value": "true" },
"details": { "type": "json", "value": "{\"tags\":[\"member\"]}" },
"note": { "type": "null", "value": "" }
}
},
"save_to_ctx": "saved_person"
}
La clave opcional del resultado guarda la respuesta de la transacción. El ID del primer registro está en ctx.saved_person.results[0].id. Para crear un registro, usa insert sin id. Un objeto fields vacío al crear aplica los valores predeterminados de la entidad; al actualizar debes indicar al menos un campo. Las sugerencias de metadatos excluyen los campos calculados y los no permitidos para la operación elegida. OzmaDB realiza la comprobación final de derechos y restricciones.
Se admiten los tipos string, number, boolean, json y null. En el JSON de la acción, value siempre es una cadena; el tipo elegido se aplica después de las sustituciones, durante la ejecución. El texto de un número conserva su precisión y string no se interpreta como sintaxis JSON. json acepta un JSON válido o una variable completa que contenga JSON. Un JSON inválido da error. Los nombres de esquemas, objetos y campos son fijos y no admiten sustituciones.
Si se pierde la respuesta después de enviar una escritura, puede que no sepas si se aplicó. Comprueba los datos en OzmaDB antes de repetirla. El reintento automático es inseguro si el servicio no ha confirmado cómo elimina duplicados. Para transacciones explícitas por lotes sigue disponible el modo HTTP request.
Extraer cualquier dato de una respuesta JSON
En cualquiera de las dos acciones de fuente, incluido el modo HTTP request, abre Parse response. Activa la extracción y elige Action result (después de result_path o la normalización de Ozma) o Full response (antes de esas transformaciones). La clave principal del resultado sigue funcionando; las reglas añaden valores a claves explícitas del contexto.
Después de Preview read, las filas aparecen automáticamente en el árbol de Parse response. Verlas no activa la extracción ni cambia los parámetros de la acción. Selecciona un campo para crear una variable con nombre o usa Collect from all records junto a un campo para reunir sus valores de todas las filas. Por ejemplo, id se convierte en una lista ids. Las reglas nuevas se añaden a las existentes y los nombres duplicados reciben sufijos únicos. Puedes cambiar el nombre propuesto y copiar la sustitución preparada.
Whole response, First record y All IDs ofrecen elecciones frecuentes; las dos últimas necesitan una lista adecuada en el ejemplo. Para una escritura, Created record ID añade la variable obligatoria created_id sin hacer una escritura de prueba. Una extracción nueva usa la respuesta completa; una ya configurada conserva su fuente. Puedes cambiarla expresamente. También puedes pegar un JSON de ejemplo y ajustar la ruta, el modo y el análisis de cadenas JSON anidadas en la configuración avanzada. Los árboles grandes se muestran parcialmente. El ejemplo no pasa a formar parte de los parámetros de la acción ni del análisis del escenario. Preview extraction procesa el ejemplo localmente, sin llamar a la fuente.
Por ejemplo, para esta respuesta anidada:
{
"results": [{ "id": 9007199254740993 }],
"groups": [
{ "members": [{ "name": "Ana", "active": false }] },
{ "members": [{ "name": "Sam", "active": true }] }
],
"extra": "{\"status\":{\"ready\":false}}"
}
Añade a los parámetros de la acción:
{
"response_parser": {
"source": "raw",
"decode_json_strings": true,
"rules": [
{ "path": "$.results[0].id", "save_to_ctx": "created_id", "mode": "value", "required": true },
{ "path": "$.groups[*].members[*].name", "save_to_ctx": "member_names", "mode": "list" },
{ "path": "/extra/status/ready", "save_to_ctx": "ready", "mode": "value" }
]
}
}
Las reglas conservan el valor exacto de created_id, obtienen la lista ["Ana","Sam"] y guardan el booleano false. Tras crear un registro correctamente, usa {{ctx.created_id}} como Record ID de una actualización posterior. Puedes elegir texto, números, booleanos, objetos, listas y null, incluido el valor raíz $. La opción Parse JSON inside strings también despliega un JSON válido guardado dentro de una cadena en el árbol del ejemplo.
Se admiten .name, ["a.b"] con escape JSON, índices positivos y negativos ([0], [-1]), todos los elementos ([*], .*), tramos ([1:3]) y JSON Pointer según RFC 6901. Para una clave literal a/b, usa /a~1b; ~ se codifica como ~0 y la ruta / selecciona una clave vacía. No se admiten filtros, expresiones ni scripts.
El modo One value da error si encuentra varias coincidencias. Para rutas con comodines, elige List of values. Una regla obligatoria falla si no encuentra nada. Un valor opcional ausente se convierte en null; una lista opcional ausente, en []. La vista previa distingue un null encontrado de la ausencia de un valor. Todas las reglas se evalúan antes de modificar el contexto. Límites: 32 reglas, 1024 bytes por ruta, 1 MiB de entrada y salida, 1000 coincidencias por regla y límites de profundidad y recorrido.
ID del registro y etiquetas de referencias de Ozma
Las opciones de lectura Include main record ID (mainId) y Include reference labels (pun) se activan por separado. include_main_id: true conserva el mainId de la fila; parse_pun: true representa una celda con etiqueta como { "id": 42, "data": "Etiqueta" }. Si una columna de la vista ya se llama mainId, se produce un error explícito. Estas opciones no cambian la respuesta original completa.
Tras una lectura, en Advanced parser settings puedes elegir entre usar las filas o la respuesta completa como ejemplo. Si ya está configurada la respuesta completa, se muestra automáticamente su ejemplo correspondiente. Al cambiar el objeto, los argumentos o las opciones de lectura, se borra el ejemplo automático anterior. El árbol aparece de inmediato; JSON example y JSON response se abren cuando los necesites. Si el ejemplo supera el límite, se abren automáticamente el aviso y el editor.
En la acción siguiente, abre Sustituciones, busca created_id en De acciones anteriores y pulsa Insertar junto a {{ctx.created_id}} en Record ID o en el valor de un argumento. Se inserta en la posición del cursor. Solo se proponen los resultados de acciones anteriores dentro del ámbito actual; el listado se actualiza inmediatamente al reordenar, renombrar o borrar acciones.
Búsqueda en el catálogo y metadatos
En una lectura Ozma nueva, Result context key está antes de los controles del objeto. Al elegir Ozma se propone ozma_rows, con un sufijo si una regla de extracción ya usa ese nombre. Se respetan los nombres existentes y los campos vaciados manualmente. La clave es obligatoria para leer y opcional para escribir. Si falta en una lectura, aparece un error junto al campo.
Pulsa Load catalog para cargar 50 vistas de lectura o 50 entidades de escritura. Abre Object from catalog y busca por schema.name en todo el catálogo remoto. La búsqueda encuentra una subcadena literal sin distinguir mayúsculas: _ y % son caracteres normales. Load more continúa la misma búsqueda desde la posición que devolvió el servidor. El objeto seleccionado permanece visible durante otras búsquedas y los campos manuales de esquema y nombre siguen disponibles si no hay acceso a los metadatos. Puedes cambiar la búsqueda o reintentar una página fallida sin volver a introducir el objeto.
Load arguments and fields indica qué argumentos son obligatorios, las entidades a las que apuntan las referencias, los tipos de columna y la entidad principal. Additional metadata muestra campos desconocidos y objetos o listas codificados dentro de cadenas JSON. Los valores numéricos conservan su escritura exacta. Para datos grandes o profundamente anidados, aparece un aviso sobre el límite de visualización. Consultar los metadatos no modifica la acción ni las reglas de extracción.
Configurar Ozma de principio a fin
El formulario de conexión Ozma separa el nombre y tipo de la dirección del servidor y la credencial guardada. Additional HTTP headers está cerrado mientras la lista esté vacía y se abre si hay encabezados configurados. La comprobación de la conexión aparece junto a su resultado; la credencial se elige por referencia. Si cambias los ajustes, se oculta el estado de la comprobación anterior: una respuesta tardía para los ajustes viejos no valida los nuevos.
En una acción, la conexión y el modo aparecen juntos, la clave de resultado está al principio y el schema.view o schema.entity elegido se muestra sobre los controles del objeto. Enter schema and name manually contiene los campos manuales; se cierra para un objeto bien configurado y se abre si faltan nombres, son inválidos o falla el acceso. Los argumentos y campos de escritura se editan en filas alineadas con nombre, tipo, valor y eliminación. Las sugerencias obligatorias de metadatos siguen visibles; Types and substitutions abre la ayuda detallada.
Read settings reúne la paginación y las opciones de ID y etiquetas de referencia. Los valores predeterminados están contraídos; los valores modificados y los errores de página muestran los campos. Read preview presenta primero los registros normalizados en una tabla y permite abrir JSON response. Una lectura vacía indica qué comprobar y conserva los valores exactos. El JSON normalizado y Full OzmaDB response están disponibles por separado.
El editor Parse response de Ozma agrupa las selecciones rápidas, las variables de resultado, los controles avanzados, el ejemplo y árbol locales, y la validación. Las acciones HTTP existentes mantienen su presentación y el comportamiento de su parser. Los metadatos adicionales se abren directamente en sus campos, sin otra sección raíz innecesaria.
Qué sigue
- Acciones: Consulta a la fuente y Escribir en la fuente.
- Sustituciones y fórmulas: cómo usar los resultados de
ctx. - Integraciones: conexiones preparadas para servicios populares.