Prefer to browse in English? Go to the website English
Lingua e valuta
Accedi
Casi Piani
Cerca nel sito
Lingua e valuta
API Pubblica Smartbis v1.9.0

Integra vendite, clienti, dipendenti, benefit e idoneità con il motore di fidelizzazione.

API REST v2 per integrazioni server-to-server con autenticazione Bearer Token, scope espliciti, operazioni idempotenti e controllo dell'accesso di titolari e dipendenti ai piani.

Flusso di base

Dall'autenticazione alla ricompensa automatica.

L'uso principale dell'API è registrare vendite esterne in modo che Smartbis possa elaborare cashback, punti, voucher e comunicazioni secondo le regole del conto.

01 Genera token

Ottieni le credenziali nell'area Sviluppatori del pannello. Invia la API Key dell'identità autorizzata e una Secret Key valida; il token scade in 24 ore.

02 Crea o trova cliente

Usa documento, telefono o ID per individuare e mantenere il cliente sincronizzato.

03 Registra vendita

Invia `sale_amount` per documento, telefono o `customer_id` per attivare il motore fedeltà.

04 Convalida benefici

Consulta coupon, voucher, categorie e stock quando l'operazione lo richiede.

Rapida panoramica degli endpoint principali.

Questa sezione funge da porta di accesso prima della documentazione Swagger completa.

POST /auth/token

Genera il token Bearer per autenticare le chiamate successive.

Auth
GET /customers

Elenca i clienti o filtra per documento, telefono o ID, con paginazione opzionale.

Customers
POST /customers

Crea cliente con nome, telefono, password e dati supplementari.

Customers
PATCH /customers/{customer_id}

Aggiorna i dati anagrafici supportati e permette di attivare o disattivare il cliente tramite il campo `active`.

Customers
GET /customers/{customer_id}/referrals

Elenca solo i clienti segnalati direttamente dal cliente indicato, rispettando le autorizzazioni di visualizzazione. La richiesta non genera crediti; eventuali ricompense seguono il processo esistente e compaiono nell'estratto conto delle transazioni.

Referrals
GET /partners

Elenca i partner propri e permette di consultare i dettagli di ciascuna registrazione.

Partners
POST /partners

Registra un partner rispettando le regole e i limiti del piano.

Partners
PATCH /partners/{partner_id}

Aggiorna, attiva o disattiva un partner proprio.

Partners
POST /sales

L'amministratore registra nell'operazione principale. Per registrare in un negozio specifico, usa la API Key di un operatore autorizzato in quel negozio.

Sales
GET /customers/{customer_id}/transactions

Consulta l'estratto conto paginato, il saldo corrente e, quando applicabile, la composizione del saldo per partner.

Transactions
POST /transactions/{transaction_id}/refund

Storna integralmente l'importo generato dalla transazione eleggibile, una sola volta. Consulta refundable nell'estratto; l'operatore storna solo le proprie vendite autorizzate.

Transactions
GET /coupons

Elenco di coupon/ricompense disponibili per l'operazione.

Coupons
POST /coupons

Registra una ricompensa utilizzando le regole e i limiti esistenti dell'operazione.

Coupons
PATCH /coupons/{coupon_id}

Aggiorna, attiva o disattiva una ricompensa esistente.

Coupons
PATCH /coupons/{coupon_id}/stock

Aggiorna stock di una ricompensa specifica.

Coupons
GET /vouchers

Elenco voucher con paginazione opzionale.

Vouchers
POST /vouchers/{voucher_code}/validate

Convalida voucher tramite il codice fornito.

Vouchers
POST /vouchers/manual-redemptions

Esegue il riscatto manuale esistente, verificando il saldo e registrando il voucher e la movimentazione in modo atomico.

Vouchers
GET /plans

Elenca i piani per i partecipanti configurati nel club.

Plans
GET /subscriptions

Elenca le sottoscrizioni e consente di filtrare accessi attivi, morosi, scaduti o annullati.

Subscriptions
GET /customers/{customer_id}/dependents

Interroga i dipendenti collegati al titolare e la loro idoneità ereditata.

Dependents
POST /customers/{customer_id}/dependents

Registra un dipendente rispettando azienda, titolare e limite del piano.

Dependents
PATCH /dependents/{dependent_id}

Aggiorna i dati supportati del dipendente; la sua idoneità rimane ereditata dal titolare.

Dependents
PATCH /categories/{category_id}

Aggiorna, attiva o disattiva una categoria senza rimuovere i suoi vincoli esistenti.

Categories
GET /eligibility/reconciliation

Riconcilia le vite attive per piano e periodo, con paginazione.

Eligibility
POST /webhooks

Registra destinazioni HTTPS per eventi firmati di attivazione, morosità, scadenza e cancellazione di abbonamenti.

Webhooks
GET /webhooks/deliveries

Consulta lo storico delle consegne per analizzare tentativi e fallimenti degli eventi di abbonamento.

Webhooks
POST /access-links

Emette accesso firmato, breve e monouso per i fornitori collegati.

Access
PATCH /subscriptions/{customer_id}

Attiva, sospende o termina l'accesso del partecipante a un piano senza modificare gli addebiti nel gateway.

Subscriptions
Oggetti principali

Risorse dell'API organizzate per uso dell'operazione.

La pagina presenta i domini dell'API in linguaggio di prodotto, mentre la documentazione Swagger mantiene i dettagli di schema, parametri e risposte.

Clienti

Registrazione, ricerca, aggiornamento, attivazione e disattivazione per documento, telefono o ID, rispettando la visibilità dell'operatore.

Vendite

Registrazione di acquisti esterni per generare cashback, punti o voucher.

Buoni

Registrazione, aggiornamento, attivazione, disattivazione e controllo dell'inventario delle ricompense.

Buoni

Consultazione, convalida e riscatto manuale tramite il processo ufficiale, con verifica del saldo.

Categorie

Creazione, aggiornamento, attivazione e disattivazione delle categorie dell'operazione.

Partner e segnalazioni

Mantiene partner propri e consulta segnalazioni dirette senza creare una rete multilivello o modificare le ricompense.

Piani e sottoscrizioni

Interroga i piani e sincronizza lo stato di accesso dei partecipanti con sistemi e fornitori esterni.

Dipendenti e idoneità

Mantiene i legami familiari e riconcilia titolari e dipendenti attivi senza trasportare dati clinici.

Webhooks e accesso federato

Invia gli eventi di abbonamento supportati con firma e ritentativi. Per i fornitori collegati, emette accesso temporaneo monouso.

Autenticazione

La API Key identifica chi registra l'operazione. L'amministratore registra le vendite nell'operazione principale; per un negozio specifico, utilizza la API Key di un operatore autorizzato in quel negozio.

Scegli il percorso della tua integrazione.

Gli esempi seguenti organizzano risorse esistenti. Consulta l’OpenAPI per i campi, i permessi e le risposte di ciascuna fase.

ERP e post-vendita

Localizza o registra il cliente, registra la vendita con POST /sales e consulta GET /customers/{customer_id}/transactions. Se è necessario stornare, usa il transaction_id di una movimentazione con refundable: true; l’integrazione non sceglie un valore parziale.

Operazione con più negozi

Genera un token per l’operatore autorizzato nel negozio di ciascuna operazione. La API Key amministrativa registra nell’operazione principale; POST /sales non riceve store_id per distribuire le vendite. Collegamenti ambigui restituiscono 409 per correggere il contesto.

Club e fornitore esterno

Consulta piani e abbonamenti, mantieni titolari e dipendenti e riconcilia l’idoneità. Registra il collegamento del beneficiario con il fornitore prima di emettere accesso temporaneo. Aggiornare l’accesso su Smartbis non crea addebiti né annulla abbonamenti nel gateway.

Gestisci autenticazione, ritentativi ed eventi sin dall’inizio.

Conserva le credenziali nel backend e rispetta gli scope restituiti dall’autenticazione. La documentazione interattiva contiene i contratti per implementare e validare ciascun flusso.

Token e permessi

Rinnova il token di 24 ore quando necessario e gestisci le risposte 401. L’autorizzazione segue la API Key dell’utente: usare la Secret Key amministrativa con la API Key di un operatore non amplia i suoi permessi.

Risinvio senza duplicati

Le scritture richiedono Idempotency-Key. Reinvia la stessa richiesta con la stessa chiave per ottenere la risposta memorizzata entro la finestra di 24 ore. Un’altra richiesta con la stessa chiave restituisce 409; un’operazione in corso può anch’essa restituire 409 e indicare un nuovo tentativo.

Eventi di abbonamento

Il catalogo attuale include subscription.activated, subscription.past_due, subscription.expired e subscription.cancelled. Usa GET /webhooks/deliveries per monitorare le consegne; il catalogo non rappresenta eventi di tutte le modifiche della piattaforma.

Abbonamento e ritentativi

Valida la firma HMAC sull’intero corpo grezzo e il timestamp, con una tolleranza di cinque minuti. Il meccanismo di consegna prevede fino a otto tentativi; risposte HTTP 2xx concludono la consegna. Consulta la documentazione per implementare la validazione e gestire i fallimenti.

Accesso a uso singolo

I link per i fornitori collegati usano token con validità da 60 a 900 secondi. La sostituzione tramite POST /access-links/consume consuma il token una sola volta; richiedi un nuovo accesso quando scade o è già stato utilizzato.

Hai bisogno di collegare un sistema proprier?

Usa la documentazione interattiva per testare gli endpoint, convalidare i payload e implementare il flusso adeguato per la tua integrazione.

Apri Swagger