Elementos personalizados: API

Una interfaz de API es un formulario cuyos valores rellenos Skava envía como JSON a una dirección que tú especificas (tu backend). De esta forma, puedes conectar Skava de manera segura con tus propios sistemas.

Configura una interfaz de API

Una interfaz consta de campos de entrada (que forman el JSON), la dirección de destino y la autenticación.

1. Crear campos: Cada campo recibe una clave JSON. A la derecha verás en vivo la previsualización JSON, que se envía a tu backend exactamente de esta manera.
2. Dirección (URL): la dirección https:// de tu backend. Solo se permiten direcciones HTTPS y accesibles públicamente (ver Seguridad más abajo).
3. Método: POST (predeterminado), PUT, PATCH o GET. Con GET, los valores se agregan como parámetros de consulta en lugar de enviarse en el cuerpo.
4. Autenticación: Establece el nombre de la cabecera (p. ej. Authorization) y el prefijo del valor (p. ej. Bearer ), luego guarda el token. Opcionalmente, establece una fecha de expiración.
5. Campos de respuesta (opcional): Define por ruta qué valores de la respuesta del backend deben mostrarse: p. ej. order.id o items[0].sku.
6. Comprueba con Ping y Solicitud de prueba, y luego Publica.

Almacena el token de forma segura

El token se almacena cifrado y nunca se devuelve a los clientes: la app solo muestra si hay un token configurado y cuándo expira. Al enviar, Skava lo añade en el servidor al encabezado configurado. Si configuras una fecha de expiración, Skava rechaza la llamada tras la expiración y te pide que renueves el token.

Pruebas: Ping y Solicitud de prueba

• Ping: comprobación ligera de accesibilidad. Solo verifica si tu dirección responde, sin enviar datos de token o formulario en el proceso. Muestra la accesibilidad, el estado y el tiempo de respuesta. Ideal como primer paso.
• Solicitud de prueba: la prueba real: envía datos de muestra, incluido el token, a tu dirección y te muestra la respuesta completa, así como los campos de respuesta extraídos.

Como administrador, puedes ejecutar ambas acciones mientras aún estás en modo borrador para verificar la integración antes de la publicación.

Borrador y publicación

Cada interfaz comienza como borrador y se puede editar libremente. Cuando todo esté listo, la publicas con Publicar.

Seguridad

Cómo el equipo utiliza una interfaz publicada

Una vez que una interfaz se publica, todos los miembros de la empresa pueden activarla directamente desde un chat, sin necesidad de editor. No hay entrada colectiva ni diálogo intermedio: cada elemento publicado aparece en el menú de más con su propio nombre, junto con el logotipo de la empresa que lo ofrece.

1. En el chat, toca Más en la parte inferior y selecciona el elemento que desees, por ejemplo Pedido de materiales.
2. Completa el formulario y pulsa Enviar.
3. El resultado aparece como una tarjeta en el chat, visible para todos los participantes.

Deja que la IA construya un elemento

Como administrador de la empresa, no tienes que usar el editor tú mismo. Dile al asistente de Skava en el chat, por ejemplo, "créame un formulario de pedido para mi catálogo con cantidad y dirección de entrega". A partir de eso crea un borrador, puede modificar los campos uno a uno más tarde y conoce tu catálogo de artículos subido: para los pedidos sugiere el selector de productos en lugar de un campo de texto para el número de artículo.

También puede configurar: el punto de conexión y el método, así como la audiencia ("solo miembros de la empresa" o "también personas externas en el mismo chat"). Para la audiencia, pregunta primero en lugar de configurarla directamente, porque decide quién puede ejecutar algo desde fuera.

Lo que no toca explícitamente: el token de acceso. Nunca lo pide ni lo acepta, porque los mensajes del chat se guardan. Lo introduces tú mismo en el editor; de lo contrario, no se envía ninguna llamada. Y no puede publicar: el último paso queda en tus manos, para que nada sea visible para los clientes sin revisión.

Quién puede ejecutarlo

La pestaña "Punto de conexión" indica quién puede usar un elemento. El valor predeterminado son los miembros de tu empresa. La segunda configuración lo abre a personas externas, pero solo en un chat donde también esté presente alguien de tu empresa: exactamente el caso para el que está pensado, el cliente que te hace un pedido. Cuando tu empresa sale del chat, el permiso termina por sí solo.

Productos de tu propio catálogo

Una vez que hayas subido tu catálogo de artículos, el constructor ofrece un bloque de selector de productos. No hay opciones que mantener: la lista es tu catálogo. La persona que realiza el pedido lo busca, ve la imagen, el nombre y el número de artículo, y tu backend recibe el número de artículo. Skava rechaza un número que no esté en tu catálogo. Para la cantidad, coloca un campo numérico normal junto a él.

Define la tarjeta tú mismo

Tu backend decide qué dice la tarjeta. Skava solo comprueba la forma, el tamaño y la seguridad, nunca el significado: no conoce los estados del pedido ni los nombres de los campos. Para hacer eso, responde con un objeto card:

{"card": {"v": 1, "title": "Order 10001", "state": "pending", "status_text": "Being picked", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}}

• v debe ser el entero 1. Sin él, la respuesta no cuenta como tarjeta y se aplica el mapeo de respuesta configurado en el elemento.
• state solo define color e icono: ok, pending, warn o error. Todo lo que transmita significado se incluye en status_text como texto libre.
• fields es una lista de etiquetas y valores, con un máximo de 20 entradas. Los valores demasiado largos se acortan en lugar de rechazarse, para que un pedido nunca falle por un detalle.

Las entradas del usuario pertenecen al servidor: permanecen intactas sin importar lo que envíe tu backend. Son el registro en el chat de lo que realmente se envió.

Informar el estado más tarde

Cuando el elemento se ejecuta, Skava envía dos valores adicionales: callback_url y callback_token. Informa un nuevo estado allí más tarde y aparecerá una nueva tarjeta en el chat, también en el teléfono, mientras alguien la mira. La anterior se mantiene, para que sea legible qué estado se informó. Envía el mismo objeto card que arriba, mediante POST con la cabecera Authorization: Bearer <callback_token>. Tres valores opcionales van junto a la tarjeta:

• seq: tu contador propio. Un informe con un valor menor o igual se descarta, por lo que dos informes no pueden adelantarse entre sí.
• final: cierra la interacción. El token se vuelve inválido y la tarjeta queda final.
• notify: establécelo en false para publicar la tarjeta en silencio, sin contador de no leídos y sin notificación. Ideal para pasos intermedios que no deben despertar a nadie. Sin esta opción, la tarjeta es un mensaje perfectamente normal.

Una interacción puede publicar como máximo 50 tarjetas. Enviar el mismo informe dos veces no genera una segunda tarjeta.

Skava responde con 200 y una lista de hints si algo se acortó o se descartó, y con 422 si la tarjeta no era utilizable. Una interacción acepta informes durante 90 días.

Las tarjetas se publican mediante el emisor de sistema de Skava, no por la persona que ejecutó el elemento ni por una cuenta de tu empresa. El título de la tarjeta indica qué sistema está escribiendo.

Un ejemplo completo para copiar se encuentra en el repositorio bajo example_order_server/ y se ejecuta en api.skava.io.

Relacionado

¿Prefieres crear una plantilla de documento rellenable? Consulta Elementos personalizados: Documentos.

Preguntas frecuentes