Elementos personalizados: API

Una interfaz de API es un formulario cuyos valores rellenados Skava envía como JSON a una dirección que usted especifique (su backend). De esta forma puede conectar Skava de forma segura con sus propios sistemas.

Configurar 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 se muestra en tiempo real la vista previa JSON, que se envía a su servidor exactamente de esta forma.
2. Dirección (URL): la dirección https:// de su servidor. Solo se permiten direcciones HTTPS y accesibles públicamente (consulte 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: Establezca el nombre del encabezado (por ejemplo, Authorization) y el prefijo del valor (por ejemplo, Bearer ), luego guarde el token. Opcionalmente, establezca una fecha de caducidad.
5. Campos de respuesta (opcional): Defina por ruta qué valores de la respuesta del servidor deben mostrarse: por ejemplo, order.id o items[0].sku.
6. Compruebe con Ping y Test Request, luego Release.

Almacenar el token de forma segura

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

Pruebas: Ping y Test Request

• Ping : una comprobación ligera de accesibilidad. Solo verifica si tu dirección responde y no envía token ni datos de 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 que incluyen 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 un borrador y puede editarse libremente. Una vez que todo esté listo, la publicas con Publicar.

Seguridad

Cómo el equipo utiliza una interfaz publicada

Una vez publicada una interfaz, todos los miembros de la empresa pueden activarla directamente desde un chat: sin necesidad de editor. El flujo es el mismo que con las plantillas de documentos: seleccionar, rellenar y enviar.

1. En el chat, pulsa Más en la parte inferior y elige Elemento personalizado.
2. Selecciona la plantilla o interfaz deseada de la lista.
3. Rellena el formulario y pulsa Enviar.
4. El resultado aparece como una tarjeta en el chat: visible para todos en el chat.

Deja que la IA cree 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 genera un borrador, puede modificar los campos uno a uno más tarde y conoce tu catálogo de artículos cargado: para los pedidos sugiere el selector de productos en lugar de un campo de texto para el número de artículo.

Lo que 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 explícitamente no toca: el token de acceso. Nunca lo solicita ni lo acepta, porque los mensajes del chat se guardan. Tú lo introduces tú mismo en el editor; de lo contrario, no se realiza ninguna llamada. Y no puede publicar: el último paso queda en tus manos, para que nada sea visible para los clientes sin tu verificació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á diseñado, el cliente que hace un pedido contigo. Cuando tu empresa abandona el chat, el permiso termina automáticamente.

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 para 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 al lado.

Define la tarjeta tú mismo

Tu backend decide qué dice la tarjeta. Skava solo verifica la forma, el tamaño y la seguridad, nunca el significado: no conoce ni 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 ello, la respuesta no cuenta como una tarjeta y se aplica el mapeo de respuesta configurado en el elemento.
• state es solo color e icono: ok, pending, warn o error. Todo lo que tenga significado va 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 su backend. Son el registro en el chat de lo que se envió realmente.

Informar el estado más tarde

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

• seq: tu propio contador. Se descarta un informe con un valor menor o igual, por lo que dos informes no pueden adelantarse el uno al otro.
• final: cierra la interacción. El token se vuelve inválido y la tarjeta queda finalizada.
• notify: establece en false para publicar la tarjeta en silencio, sin contador de no leídos ni notificación. Para pasos intermedios que no deben despertar a nadie. Sin ello, la tarjeta es un mensaje perfectamente normal.

Una interacción puede publicar como máximo 50 tarjetas. 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 usable. Una interacción acepta informes durante 90 días.

Las tarjetas son publicadas por el remitente del sistema de Skava, no por la persona que ejecutó el elemento ni por una cuenta de tu propia 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