Obtenga las credenciales en el área Desarrolladores del panel. Envíe la API Key de la identidad autorizada y una Secret Key válida; el token expira en 24 horas.
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.
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.
Genera el token Bearer para autenticar las próximas llamadas.
AuthLista clientes o filtra por documento, teléfono o ID, con paginación opcional.
CustomersCrea cliente con nombre, teléfono, contraseña y datos complementarios.
CustomersActualiza los datos registrales soportados y permite activar o desactivar al cliente mediante el campo `active`.
CustomersLista ú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.
ReferralsLista socios propios y permite consultar los detalles de cada registro.
PartnersRegistra un socio respetando las reglas y los límites del plan.
PartnersActualiza, activa o desactiva un socio propio.
PartnersEl administrador registra en la operación principal. Para registrar en una tienda específica, use la API Key de un operador autorizado en ella.
SalesConsulta el extracto paginado, el saldo actual y, cuando aplique, la composición del saldo por socio.
TransactionsRevierte íntegramente el importe generado por la transacción elegible, una única vez. Consulte refundable en el extracto; el operador solo revierte sus propias ventas autorizadas.
TransactionsLista cupones/recompensas disponibles para la operación.
CouponsRegistra una recompensa usando las reglas y los límites existentes de la operación.
CouponsActualiza, activa o desactiva una recompensa existente.
CouponsActualiza inventario de una recompensa específica.
CouponsLista vouchers con paginación opcional.
VouchersValida voucher por el código informado.
VouchersEjecuta el canje manual existente, verificando saldo y registrando el voucher y la operación de forma atómica.
VouchersEnumera los planes para participantes configurados en el club.
PlansLista suscripciones y permite filtrar accesos activos, morosos, vencidos o cancelados.
SubscriptionsConsulta dependientes vinculados al titular y su elegibilidad heredada.
DependentsRegistra dependiente respetando empresa, titular y límite del plan.
DependentsActualiza los datos soportados del dependiente; su elegibilidad sigue heredada del titular.
DependentsActualiza, activa o desactiva una categoría sin eliminar sus vínculos existentes.
CategoriesConciliación de vidas activas por plan y período, con paginación.
EligibilityRegistra destinos HTTPS para eventos firmados de activación, mora, vencimiento y cancelación de suscripciones.
WebhooksConsulta el historial de entregas para investigar intentos y fallos de los eventos de suscripción.
WebhooksEmite acceso firmado, corto y de un solo uso para proveedores vinculados.
AccessActiva, suspende o finaliza el acceso del participante a un plan sin alterar los cobros en el gateway.
SubscriptionsRecursos 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 los eventos de suscripción soportados con firma y reintentos. Para proveedores vinculados, emite acceso temporal de uso único.
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.
Elija el recorrido de su integración.
Los ejemplos a continuación organizan recursos existentes. Consulte en el OpenAPI los campos, permisos y respuestas de cada etapa.
Localice o registre al cliente, registre la venta en POST /sales y consulte GET /customers/{customer_id}/transactions. Si es necesario revertir, use el transaction_id de una transacción con refundable: true; la integración no elige un valor parcial.
Genere un token para el operador autorizado en la tienda de cada operación. La API Key administrativa registra en la operación principal; POST /sales no recibe store_id para distribuir ventas. Vínculos ambiguos devuelven 409 para corrección del contexto.
Consulte planes y suscripciones, mantenga titulares y dependientes y concilie la elegibilidad. Registre el vínculo del beneficiario con el proveedor antes de emitir acceso temporal. Actualizar el acceso en Smartbis no crea cobros ni cancela suscripciones en el gateway.
Gestione autenticación, reenvíos y eventos desde el inicio.
Mantenga las credenciales en el backend y respete los alcances devueltos por la autenticación. La documentación interactiva contiene los contratos para implementar y validar cada flujo.
Renueve el token de 24 horas cuando sea necesario y gestione respuestas 401. La autorización sigue la API Key del usuario: usar la Secret Key administrativa con la API Key de un operador no amplía sus permisos.
Las escrituras requieren Idempotency-Key. Reenvíe la misma solicitud con la misma clave para obtener la respuesta almacenada dentro de la ventana de 24 horas. Otra carga con la misma clave devuelve 409; una operación en procesamiento también puede devolver 409 e indicar reintento.
El catálogo actual incluye subscription.activated, subscription.past_due, subscription.expired y subscription.cancelled. Use GET /webhooks/deliveries para seguir entregas; el catálogo no representa eventos de todos los cambios de la plataforma.
Valide la firma HMAC sobre el cuerpo bruto y el timestamp, con tolerancia de cinco minutos. El mecanismo de entrega prevé hasta ocho intentos; las respuestas HTTP 2xx concluyen la entrega. Consulte la documentación para implementar la validación y gestionar fallos.
Los enlaces para proveedores vinculados usan tokens con validez de 60 a 900 segundos. El intercambio por POST /access-links/consume consume el token una sola vez; solicite nuevo acceso cuando expire o ya haya sido utilizado.
¿Necesitas conectar un sistema propio?
Use la documentación interactiva para probar endpoints, validar payloads e implementar el flujo adecuado para su integración.