Subscription *

La chiamata di Subscription permette, indicando i parametri della card e dell'utente di creare o aggiornare un abbonamento e il relativo stato.
La chiamata permette di:

Creare un abbonamento e associare la relativa Card all'utente indicato;
Aggiornare lo stato dell'abbonamento;
Creare o aggiornare l'Utente indicato;

Richiede in ingresso:

Codice Prodotto;
Stato dell'abbonamento

{ "ATTIVO", "RINNOVATO", "SOSPESO", "ANNULLATO", "DISDETTO" }

Parametri relativi all'Utente;
Parametri relativi a Card e Vendita;

Restituisce:

Codice della Card appena rilasciata, data di attivazione e scadenza;
Email dell'Utente a cui è associata la Card;
Stato dell'abbonamento
(Opzionale) Lista di licenze Software rilasciate, o info sullo stato del rilascio (in caso di software multipli o errore);
Oppure, se non va a buon fine, la descrizione dell'errore riscontrato;

Softwares:

Nel caso in cui siano associati 1 o più Softwares alla Card rilasciata, verrà gestita con la seguente logica il rilascio delle licenze software designate:

Software singolo per gruppo software: rilascio immediato della licenza;
Software multiplo per gruppo software: notifica che ci indica di effettuare chiamata di selezione software per la Card;

Utente:

Poiché il campo email è obbligatorio, la creazione o l'aggiornamento dell'Utente ai fini dell'allineamento con la base dati del socio verrà gestita esclusivamente tramite la seguente logica:

Utente trovato: l'utente esistente viene associato alla Card, ne vengono eventualmente aggiornati i dati (nome, congnome, numero di telefono).
Utente non trovato: viene creato un nuovo utente con tutti i dati specificati e successivamente viene associato alla Card.

Chiave	Valore
Indirizzo Test	https://test-apiv2.smiletech.it/APIv2/CardReleaseds/Subscription
Indirizzo Prod	https://apiv2.smiletech.it/APIv2/CardReleaseds/Subscription
Metodo	POST
Success Response	200 (Success)
Error Response	400 (Bad Request) 401 (Unauthorized) 500(Internal Server Error)

Di seguito la struttura dell'Header contenente:

Header

{ 
    "authorization": "Bearer -indicare-qui-Token-fornito-" 
}

Di seguito la struttura del body contenente i valori da inserire all'interno della richiesta:

Request body

{
    "subscriptionState": "[string]{stato abbonamento} OBBLIGATORIO",
    "shopCode": "[string]{codice univoco negozio} OBBLIGATORIO",
    "documentCode": "[string]{codice univoco documento} OBBLIGATORIO",
    "idSubscription": "[string]{identificativo univoco abbonamento (Vendor)} OBBLIGATORIO",
    "idExternalSubscription": "[string]{identificativo univoco esterno abbonamento (Vendor)} OBBLIGATORIO",
    "codeProduct": "[string]{codice prodotto smiletech} OBBLIGATORIO",
    "dateExpired": "[dateTime]{data di scadenza abbonamento} OBBLIGATORIO",
    "articleType": "[string]{tipologia articolo}",
    "articleBrand": "[string]{marca articolo}",
    "articleModel": "[string]{modello articolo}",
    "articleEAN": "[string]{EAN articolo}",
    "articleIMEI": "[string]{IMEI articolo}",
    "user": {
        "name": "[string]{nome dell'Utente} OBBLIGATORIO",
        "surname": "[string]{cognome dell'Utente} OBBLIGATORIO",
        "email": "[string]{email univoca e identificativa dell'Utente} OBBLIGATORIO",
        "phoneNumber": "[string]{numero di telefono dell'Utente} OBBLIGATORIO",
    }
}

Di seguito la struttura della response contenente i valori di ritorno dal sistema:

Response body

{
    "cardCode": "[string]{codice univoco Card, necessario per usufruire del servizio e dei prodotti associati}",
    "email": "[string]{email del cliente a cui è associata la Card}",
    "dateActived": "[dateTime]{data/momento di attivazione e validità della Card}",
    "dateExpired": "[dateTime]{data/momento di scadenza della Card}"
    "subscriptionState": "[string]{stato abbonamento}",
    "softwares": [
        {
            "name": "[string]{nome del software}",
            "code": "[string]{codice identificativo del prodotto}",
            "license": "[string]{licenza di utilizzo, destinata al cliente finale}",
            "downloadLink": "[string]{link di download del Software}",
            "group": "[string]{nome del gruppo software di appartenenza}",
            "resultCode": [int]{codice stato operazione di rilascio (200, 400, 500 etc.)},
            "resultMessage": "[string]{messaggio esplicativo del risultato dell’operazione di rilascio}"
        }
    ]
}

Un esempio di chiamata con dati verosimili:

https://test-apiv2.smiletech.it/APIv2/CardReleaseds/Subscription

Header

{ 
    "authorization": "Bearer NTNv7j0TuYARvmNMmWXo6fKvM4o6nv/aUi9ryX38ZH+L1bkrnD1ObOQ8Jdav"
}

Request body

{
    "subscriptionState": "ATTIVO",
    "shopCode": "1050",
    "documentCode": "DX122342341Y",
    "idSubscription": "50000005",
    "codeProduct": "SIRTIEPREMTV",
    "dateExpired": "2025-11-17T12:00:00.000",
    "articleType": "SMART TV",
    "articleBrand": "SAMSUNG",
    "articleModel": "SM-43-09889",
    "articleEAN": "01234567890128",
    "articleIMEI": "35-161508-323751-9",
    "user": {
        "name": "Mario",
        "surname": "Rossi",
        "email": "marco@mail.it",
        "phoneNumber": "333133313"
    }
}

In caso di Successo il sistema ritorna il seguente modello JSON:

Response body

{
    "cardCode": "006D25ADB1454157",
    "email": "marco@mail.it",
    "dateActived": "2023-10-26T19:33:06Z",
    "dateExpired": "2024-10-26T19:33:06Z",
    "subscriptionState": "ATTIVO",
    "softwares": [
        {
            "name": "Kaspersky Internet Security",
            "code": "KIS",
            "license": "AAAA1-BB2BB-3CCCC-D4DDD",
            "downloadLink": "oaservice.it/internetsecurity.exe",
            "group": "Antivirus",
            "resultCode": 200,
            "resultMessage": "Licenza rilasciata."
        }
    ]
}

In caso di Errore il sistema ritorna il seguente modello JSON:

Response

Status: 400 Bad Request

        {
            "error": "Campi obbligartori (CodeProduct) non valorizzati."
        }
        

Errori Riscontrabili

Di seguito la lista che indica gli errori che possono essere riscontrati:

Codice	Descrizione
400 (BadRequest)	I dati in ingresso non sono corretti o non sono correttamente formattati. Viene restituita la descrizione dell’errore nel dettaglio.
401 (Unauthorized)	Il codice Token fornito non è valido. L’autenticazione non è andata a buon fine.
500 (Internal Server Error)	Il server ha riscontrato un errore inaspettato, generalmente esula dal tipo di request e si verifica per problemi assoggettabili al sistema.

26 gennaio 2026