Send the administrator's or an authorized operator's API Key and a valid Secret Key to receive the `access_token`.
Smartbis Public API v1.9.0
Integrate sales, customers, dependents, benefits and eligibility with the loyalty engine.
REST API v2 for server-to-server integrations with Bearer Token authentication, explicit scopes, idempotent writes and control of primary and dependent access to plans.
Basic flow
From authentication to automatic reward.
The main use of the API is to register external sales so that Smartbis can process cashback, points, vouchers, and communications according to the account rules.
Use document, phone, or ID to locate and keep the customer synchronized.
Send `sale_amount` by document, phone, or `customer_id` to trigger the loyalty engine.
Check coupons, vouchers, categories, and stock when the operation requires it.
Quick reference of the main endpoints.
This section works as an entry point before the complete Swagger documentation.
POST
/auth/token
Generates the Bearer token to authenticate subsequent calls.
Auth
GET
/customers
List customers or filter by document, phone, or ID, with optional pagination.
Customers
POST
/customers
Create customer with name, phone, password, and additional data.
Customers
PATCH
/customers/{customer_id}
Updates the supported registration data and allows activating or deactivating the customer via the `active` field.
Customers
GET
/customers/{customer_id}/referrals
Lists only the customers directly referred by the specified customer, respecting view permissions. The query does not generate credits; any rewards follow the existing process and appear in the transaction statement.
Referrals
GET
/partners
Lists own partners and allows querying the details of each record.
Partners
POST
/partners
Registers a partner in accordance with the plan rules and limits.
Partners
PATCH
/partners/{partner_id}
Updates, activates, or deactivates an owned partner.
Partners
POST
/sales
The administrator registers on the main operation. To register in a specific store, use an authorized operator's API Key for that store.
Sales
GET
/customers/{customer_id}/transactions
Retrieves the paginated statement, the current balance and, when applicable, the balance composition by partner.
Transactions
GET
/coupons
Lists available coupons/rewards for the operation.
Coupons
POST
/coupons
Registers a reward using the operation's existing rules and limits.
Coupons
PATCH
/coupons/{coupon_id}
Updates, activates, or deactivates an existing reward.
Coupons
PATCH
/coupons/{coupon_id}/stock
Update stock of a specific reward.
Coupons
GET
/vouchers
Lists vouchers with optional pagination.
Vouchers
POST
/vouchers/{voucher_code}/validate
Validate voucher by the provided code.
Vouchers
POST
/vouchers/manual-redemptions
Executes an existing manual redemption, checking balance and recording the voucher and the transaction atomically.
Vouchers
GET
/plans
Lists the plans for participants configured in the club.
Plans
GET
/subscriptions
Lists subscriptions and allows filtering for active, delinquent, expired or canceled accesses.
Subscriptions
GET
/customers/{customer_id}/dependents
Retrieves dependents linked to the primary and their inherited eligibility.
Dependents
POST
/customers/{customer_id}/dependents
Registers a dependent respecting company, primary and plan limit.
Dependents
PATCH
/dependents/{dependent_id}
Updates the supported dependent data; eligibility remains inherited from the primary holder.
Dependents
PATCH
/categories/{category_id}
Updates, activates, or deactivates a category without removing its existing links.
Categories
GET
/eligibility/reconciliation
Reconciles active lives by plan and period, with pagination.
Eligibility
POST
/webhooks
Registers HTTPS destinations for signed eligibility change events.
Webhooks
POST
/access-links
Issues a signed, short-lived, single-use access link for linked vendors.
Access
PATCH
/subscriptions/{customer_id}
Activates, suspends or terminates a participant’s access to a plan without changing billing at the gateway.
Subscriptions
Main objects
API resources organized by operation usage.
This page presents the API domains in product language, while the Swagger documentation maintains schema, parameter, and response details.
Registration, search, update, activation and deactivation by document, phone, or ID, respecting operator visibility.
Register external purchases to generate cashback, points, or vouchers.
Registration, update, activation, deactivation and stock control of rewards.
Query, validation and manual redemption through the official process, with balance verification.
Creation, update, activation and deactivation of the operation's categories.
Maintains owned partners and queries direct referrals without creating a multi-level network or altering rewards.
Queries plans and synchronizes participants’ access status with external systems and providers.
Maintains family links and reconciles active primaries and dependents without transferring clinical data.
Delivers signed events with retries and generates temporary single-use tokens for external vendors.
The API Key identifies who registers the operation. The administrator records sales on the main operation; for a specific store, use an authorized operator's API Key for that store.
Need to connect your own system?
Use the interactive documentation to test endpoints, validate payloads, and implement the appropriate flow for your integration.