Integración de Ventas – Guía de Integración
Integración de Ventas – Guía de Integración
Objetivo
Reúnes aquí toda la información técnica necesaria para integrar los datos de ventas de tu sistema con la plataforma KSI.
Completar esta guía te permitirá implementar una integración confiable, automatizada y alineada con las necesidades operativas de tu tienda.
Recomendaciones para Escalabilidad
- Utiliza criterios consistentes para los códigos de referencia externa de las tiendas.
- Mantén nomenclaturas idénticas entre tus sistemas internos y KSI.
- Centraliza el proceso de integración en un único responsable técnico interno.
- Guarda esta guía como plantilla para futuras integraciones o ampliaciones.
Información General de la Integración
Completa esta sección con todos los datos necesarios de tu API de ventas.
👉 Antes de comenzar, asegúrate de contar con:
- Un endpoint accesible por KSI.
- Un token Bearer válido.
- Los códigos de referencia externa (ext_ref_codes) de cada tienda.
Explicación de los Datos Necesarios (Tabla unificada)
| Sección / Campo | Qué tienes que ingresar | Ejemplo / Nota |
|---|---|---|
| URL del endpoint | Dirección URL desde donde KSI consumirá los datos de ventas. | Ejemplo: https://api.suservidor.com/ventas |
| Autenticación | Método de autenticación requerido. | Bearer Token |
| Parámetro: fromTime | Fecha/hora de inicio en formato ISO 8601. | 2023-02-08T00:00:00-03:00 |
| Parámetro: toTime | Fecha/hora de fin en formato ISO 8601. | 2023-02-09T23:59:59-03:00 |
| Parámetro: ext_ref_codes | Códigos externos que vinculan cada tienda a su configuración en KSI. | Se pueden enviar múltiples códigos: ext_ref_codes=0001&ext_ref_codes=0002 |
| Formato de respuesta JSON | La API debe devolver una lista con el total de tickets agrupados por hora. | Ver ejemplo más abajo. Solo debe enviarse la lista — sin metadatos adicionales. |
| Campos requeridos en la respuesta | time (ISO 8601), ext_ref_code (tienda), num_tickets (cantidad de tickets por hora). | time: "2023-02-08T09:00:00-03:00"; num_tickets: 25 |
| Agrupación de datos | Los tickets deben venir agrupados por hora. | Ej.: 10:00–10:59 todos en un único registro. |
| Ejemplo de llamada GET | Solicitud que KSI ejecutará para obtener los datos. | GET http://<url>?fromTime=...&toTime=...&ext_ref_codes=0001&ext_ref_codes=0002 |
| Ejemplo de respuesta JSON | Respuesta correcta según el estándar esperado. | Ver ejemplo completo más abajo. |
| Soporte técnico | Contacto para dudas o asistencia. | ksi.soporte@ksivision.com |
.
Ejemplo de Solicitud HTTP
GET http://<urlcliente>?fromTime=2023-02-08T09:00:00-03:00&toTime=2023-02-08T10:59:59-03:00&ext_ref_codes=0001&ext_ref_codes=0002
Ejemplo respuesta:
[
{
"time": "2023-02-08T09:00:00-03:00",
"ext_ref_code": "0001",
"num_tickets": 25
},
{
"time": "2023-02-08T10:00:00-03:00",
"ext_ref_code": "0001",
"num_tickets": 30
},
{
"time": "2023-02-08T09:00:00-03:00",
"ext_ref_code": "0002",
"num_tickets": 150
},
{
"time": "2023-02-08T10:00:00-03:00",
"ext_ref_code": "0002",
"num_tickets": 230
}
]
Configuración de la Integración en KSI
Sigue los pasos para activar la integración dentro de la plataforma.
1. Acceder a la configuración
Ve a:
Settings (1) → Editar (2) → “Manage sales configs” (3)
2. Crear un nuevo conector de ventas
Completa todos los campos solicitados:
- URL del endpoint
- Token de autenticación
- Parámetros requeridos
- Formato de respuesta
👉 Luego testea la conexión y guarda el conector.
3. Asociar el conector a la tienda
En la configuración de la tienda (1), ve al apartado "Configuración de ventas" (2)
Allí debes:
- Seleccionar el conector creado (3)
- Especificar el código de referencia externo correspondiente a esa tienda
4. Guardar la configuración
Una vez guardado, KSI comenzará automáticamente a extraer los datos de ventas de manera periódica.
Contacto y Soporte
Si necesitas asistencia adicional, no dudes en contactar a nuestro equipo técnico: