Envíe la API Key del administrador o de un operador autorizado y una Secret Key válida para recibir el `access_token`.
API Pública Smartbis v1.9.0
Integre ventas, clientes, dependientes, beneficios y elegibilidad con el motor de fidelización.
API REST v2 para integraciones server-to-server con autenticación Bearer Token, ámbitos explícitos, operaciones idempotentes y control del acceso de titulares y dependientes a los planes.
Flujo básico
Desde la autenticación hasta la recompensa automática.
El uso principal de la API es registrar ventas externas para que Smartbis procese cashback, puntos, vouchers y comunicaciones según las reglas de la cuenta.
Use documento, teléfono o ID para localizar y mantener al cliente sincronizado.
Envíe `sale_amount` por documento, teléfono o `customer_id` para activar el motor de fidelidad.
Consulta cupones, vouchers, categorías y stock cuando la operación lo requiera.
Referencia rápida a los principales endpoints.
Esta parte funciona como una puerta de entrada antes de la documentación Swagger completa.
POST
/auth/token
Genera el token Bearer para autenticar las próximas llamadas.
Auth
GET
/customers
Lista clientes o filtra por documento, teléfono o ID, con paginación opcional.
Customers
POST
/customers
Crea cliente con nombre, teléfono, contraseña y datos complementarios.
Customers
PATCH
/customers/{customer_id}
Actualiza los datos registrales soportados y permite activar o desactivar al cliente mediante el campo `active`.
Customers
GET
/customers/{customer_id}/referrals
Lista únicamente a los clientes referidos directamente por el cliente indicado, respetando los permisos de visualización. La consulta no genera créditos; las recompensas eventuales siguen el proceso existente y aparecen en el extracto de transacciones.
Referrals
GET
/partners
Lista socios propios y permite consultar los detalles de cada registro.
Partners
POST
/partners
Registra un socio respetando las reglas y los límites del plan.
Partners
PATCH
/partners/{partner_id}
Actualiza, activa o desactiva un socio propio.
Partners
POST
/sales
El administrador registra en la operación principal. Para registrar en una tienda específica, use la API Key de un operador autorizado en ella.
Sales
GET
/customers/{customer_id}/transactions
Consulta el extracto paginado, el saldo actual y, cuando aplique, la composición del saldo por socio.
Transactions
GET
/coupons
Lista cupones/recompensas disponibles para la operación.
Coupons
POST
/coupons
Registra una recompensa usando las reglas y los límites existentes de la operación.
Coupons
PATCH
/coupons/{coupon_id}
Actualiza, activa o desactiva una recompensa existente.
Coupons
PATCH
/coupons/{coupon_id}/stock
Actualiza inventario de una recompensa específica.
Coupons
GET
/vouchers
Lista vouchers con paginación opcional.
Vouchers
POST
/vouchers/{voucher_code}/validate
Valida voucher por el código informado.
Vouchers
POST
/vouchers/manual-redemptions
Ejecuta el canje manual existente, verificando saldo y registrando el voucher y la operación de forma atómica.
Vouchers
GET
/plans
Enumera los planes para participantes configurados en el club.
Plans
GET
/subscriptions
Lista suscripciones y permite filtrar accesos activos, morosos, vencidos o cancelados.
Subscriptions
GET
/customers/{customer_id}/dependents
Consulta dependientes vinculados al titular y su elegibilidad heredada.
Dependents
POST
/customers/{customer_id}/dependents
Registra dependiente respetando empresa, titular y límite del plan.
Dependents
PATCH
/dependents/{dependent_id}
Actualiza los datos soportados del dependiente; su elegibilidad sigue heredada del titular.
Dependents
PATCH
/categories/{category_id}
Actualiza, activa o desactiva una categoría sin eliminar sus vínculos existentes.
Categories
GET
/eligibility/reconciliation
Conciliación de vidas activas por plan y período, con paginación.
Eligibility
POST
/webhooks
Registra destinos HTTPS para eventos firmados de cambio de elegibilidad.
Webhooks
POST
/access-links
Emite acceso firmado, corto y de un solo uso para proveedores vinculados.
Access
PATCH
/subscriptions/{customer_id}
Activa, suspende o finaliza el acceso del participante a un plan sin alterar los cobros en el gateway.
Subscriptions
Objetos principales
Recursos de la API organizados por uso de la operación.
La página presenta los dominios de la API en lenguaje de producto, mientras que la documentación Swagger mantiene los detalles de esquema, parámetros y respuestas.
Registro, búsqueda, actualización, activación y desactivación por documento, teléfono o ID, respetando la visibilidad del operador.
Registro de compras externas para generar cashback, puntos o vouchers.
Registro, actualización, activación, desactivación y control de inventario de las recompensas.
Consulta, validación y canje manual mediante el proceso oficial, con verificación de saldo.
Creación, actualización, activación y desactivación de las categorías de la operación.
Mantiene socios propios y consulta indicaciones directas sin crear una red multinivel ni alterar recompensas.
Consulta planes y sincroniza el estado de acceso de los participantes con sistemas y proveedores externos.
Mantiene vínculos familiares y concilia titulares y dependientes activos sin transferir datos clínicos.
Entrega eventos firmados con reintentos y genera tokens temporales de un solo uso para proveedores externos.
La API Key identifica quién registra la operación. El administrador registra ventas en la operación principal; para una tienda específica, utilice la API Key de un operador autorizado en ella.
¿Necesitas conectar un sistema propio?
Use la documentación interactiva para probar endpoints, validar payloads e implementar el flujo adecuado para su integración.