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.
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.
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.
Usa documento, telefono o ID per individuare e mantenere il cliente sincronizzato.
Invia `sale_amount` per documento, telefono o `customer_id` per attivare il motore fedeltà.
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.
Genera il token Bearer per autenticare le chiamate successive.
AuthElenca i clienti o filtra per documento, telefono o ID, con paginazione opzionale.
CustomersCrea cliente con nome, telefono, password e dati supplementari.
CustomersAggiorna i dati anagrafici supportati e permette di attivare o disattivare il cliente tramite il campo `active`.
CustomersElenca 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.
ReferralsElenca i partner propri e permette di consultare i dettagli di ciascuna registrazione.
PartnersRegistra un partner rispettando le regole e i limiti del piano.
PartnersAggiorna, attiva o disattiva un partner proprio.
PartnersL'amministratore registra nell'operazione principale. Per registrare in un negozio specifico, usa la API Key di un operatore autorizzato in quel negozio.
SalesConsulta l'estratto conto paginato, il saldo corrente e, quando applicabile, la composizione del saldo per partner.
TransactionsStorna integralmente l'importo generato dalla transazione eleggibile, una sola volta. Consulta refundable nell'estratto; l'operatore storna solo le proprie vendite autorizzate.
TransactionsElenco di coupon/ricompense disponibili per l'operazione.
CouponsRegistra una ricompensa utilizzando le regole e i limiti esistenti dell'operazione.
CouponsAggiorna, attiva o disattiva una ricompensa esistente.
CouponsAggiorna stock di una ricompensa specifica.
CouponsElenco voucher con paginazione opzionale.
VouchersConvalida voucher tramite il codice fornito.
VouchersEsegue il riscatto manuale esistente, verificando il saldo e registrando il voucher e la movimentazione in modo atomico.
VouchersElenca i piani per i partecipanti configurati nel club.
PlansElenca le sottoscrizioni e consente di filtrare accessi attivi, morosi, scaduti o annullati.
SubscriptionsInterroga i dipendenti collegati al titolare e la loro idoneità ereditata.
DependentsRegistra un dipendente rispettando azienda, titolare e limite del piano.
DependentsAggiorna i dati supportati del dipendente; la sua idoneità rimane ereditata dal titolare.
DependentsAggiorna, attiva o disattiva una categoria senza rimuovere i suoi vincoli esistenti.
CategoriesRiconcilia le vite attive per piano e periodo, con paginazione.
EligibilityRegistra destinazioni HTTPS per eventi firmati di attivazione, morosità, scadenza e cancellazione di abbonamenti.
WebhooksConsulta lo storico delle consegne per analizzare tentativi e fallimenti degli eventi di abbonamento.
WebhooksEmette accesso firmato, breve e monouso per i fornitori collegati.
AccessAttiva, sospende o termina l'accesso del partecipante a un piano senza modificare gli addebiti nel gateway.
SubscriptionsRisorse 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.
Registrazione, ricerca, aggiornamento, attivazione e disattivazione per documento, telefono o ID, rispettando la visibilità dell'operatore.
Registrazione di acquisti esterni per generare cashback, punti o voucher.
Registrazione, aggiornamento, attivazione, disattivazione e controllo dell'inventario delle ricompense.
Consultazione, convalida e riscatto manuale tramite il processo ufficiale, con verifica del saldo.
Creazione, aggiornamento, attivazione e disattivazione delle categorie dell'operazione.
Mantiene partner propri e consulta segnalazioni dirette senza creare una rete multilivello o modificare le ricompense.
Interroga i piani e sincronizza lo stato di accesso dei partecipanti con sistemi e fornitori esterni.
Mantiene i legami familiari e riconcilia titolari e dipendenti attivi senza trasportare dati clinici.
Invia gli eventi di abbonamento supportati con firma e ritentativi. Per i fornitori collegati, emette accesso temporaneo monouso.
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.
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.
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.
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.
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.
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.
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.
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.
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.