Prefer to browse in English? Go to the website English
Idioma y moneda
Iniciar sesión
Casos Planes
Buscar en el sitio
Idioma y moneda
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.

01 Generar token

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.

02 Crear o localizar cliente

Use documento, teléfono o ID para localizar y mantener al cliente sincronizado.

03 Registrar venta

Envíe `sale_amount` por documento, teléfono o `customer_id` para activar el motor de fidelidad.

04 Validar beneficios

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
POST /transactions/{transaction_id}/refund

Revierte í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.

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 activación, mora, vencimiento y cancelación de suscripciones.

Webhooks
GET /webhooks/deliveries

Consulta el historial de entregas para investigar intentos y fallos de los eventos de suscripción.

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.

Clientes

Registro, búsqueda, actualización, activación y desactivación por documento, teléfono o ID, respetando la visibilidad del operador.

ventas

Registro de compras externas para generar cashback, puntos o vouchers.

Cupones

Registro, actualización, activación, desactivación y control de inventario de las recompensas.

Cupones

Consulta, validación y canje manual mediante el proceso oficial, con verificación de saldo.

Categorías

Creación, actualización, activación y desactivación de las categorías de la operación.

Socios e indicaciones

Mantiene socios propios y consulta indicaciones directas sin crear una red multinivel ni alterar recompensas.

Planes y suscripciones

Consulta planes y sincroniza el estado de acceso de los participantes con sistemas y proveedores externos.

Dependientes y elegibilidad

Mantiene vínculos familiares y concilia titulares y dependientes activos sin transferir datos clínicos.

Webhooks y acceso federado

Entrega los eventos de suscripción soportados con firma y reintentos. Para proveedores vinculados, emite acceso temporal de uso único.

Autenticación

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.

ERP y posventa

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.

Operación con varias tiendas

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.

Club y proveedor externo

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.

Token y permisos

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.

Reenvío sin duplicidad

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.

Eventos de suscripción

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.

Suscripción y reintentos

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.

Acceso de uso único

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.

Abrir Swagger