API partner di Slevomat.cz

L'API viene utilizzata per trasferire informazioni sui voucher tra Slevomat e il sistema del partner commerciale. Consente al partner di verificare la validità dei voucher nel proprio sistema e di riscattarli. Il partner non ha bisogno di utilizzare la Partner Interface per questo scopo.

Possibili esempi di utilizzo:

• Un cliente acquista un buono in cui il servizio è condizionato all'inserimento di un codice sul sito web del partner al momento della creazione dell'ordine. Grazie all'API, la validità del buono viene immediatamente verificata dopo questo inserimento. Il valore del buono viene quindi detratto dal carrello del partner e il buono viene automaticamente riscattato su Slevomat.
• Allo stesso modo, è anche possibile verificare la validità dei voucher nel sistema di prenotazione del partner o caricare un credito acquistato di un certo valore direttamente sul sito web del partner.

La Partner API richiede un token univoco per ogni partner e viene inviato come parte di ogni richiesta. Per utilizzare la Partner API, contatta il tuo/nostro rappresentante di vendita.

Formato della richiesta

Il punto di accesso API si trova in /api.

Il formato della richiesta è

<URL přístupového bodu>/<akce>[<pa­rametry>]

Tutte le richieste sono richieste HTTP GET standard, ovvero una richiesta per verificare la validità di un buono potrebbe apparire così:

https://www.slevomat.cz/api/vouchercheck?code=1234-5677-77-111&token=123456789012345.

Formato di risposta

La risposta del server è sempre in formato JSON con l'intestazione Content-type corrispondente. La struttura di base della risposta è la seguente.

{
 "result": true,
 "data": {
 ...
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Il valore dell'elemento risultato è true (in caso di successo) o false (in caso di errore). In caso di errore, la voce di errore contiene il codice di errore (code ) e la sua descrizione (message ). Oltre all'indicazione nel campo di errore, il sistema restituisce il codice di stato HTTP corrispondente (400, 401, 403, 404) in caso di errore.

L'elemento dati contiene i dati restituiti dall'azione chiamata e il suo contenuto è individuale.

Tutti i dati sono nel formato AAAA-MM-GGTHH:MM:SSZ (ISO8601; ad esempio 2011–01–01T10:10:10+02:00).

Validazione del voucher

• azione: voucherCheck
• parametri: token (obbligatorio; token partner univoco), codice (obbligatorio; codice voucher)

Ci sono tre codici voucher di prova:

• 1234–5677–77–111 (pagato, non utilizzato),
• 2234–5688–88–222 (pagato, usato),
• 3234–5699–99–333 (non pagato, inutilizzato).

Se l'applicazione utilizza uno di questi codici, il server restituirà la risposta corrispondente (nel caso di un voucher pagato e non utilizzato, restituirà anche un voucher di esempio e dati sull'evento).

Formato dei dati di risposta

{
 "token": <auth token>,
 "code": <voucher code>,
 "voucherData": <voucher data>
}

Il parametro voucherData contiene la definizione del voucher nel seguente formato.

{
 "id": <Voucher ID>,
 "orderId": <Order ID>,
 "title": <voucher title>,
 "ordered": <order date and time; datetime>,
 "paidDate": <order paid date; date>
 "validFrom": <voucher validity start; date>,
 "validTo": <voucher validity end; date>,
 "key": <voucher code>,
 "code": <voucher code,
 "product": <promotion ID>,
 "productName": <promotion title>,
 "variant": <variant ID>,
 "variantName": <variant title>,
 "imageUrl": <URL image>,
 "smallImageUrl": <URL image>,
 "productUrl": <URL image>,
 "reservationTime": <Reservation time if voucher is reserved; datetime>
}

Stati di errore

• Codice 1101 (codice di stato HTTP 400): il token di autenticazione o il codice voucher non è stato inserito,
• Codice 1102 (codice di stato HTTP 403): il token non è nel database,
• codice 1103 (codice di stato HTTP 404): il voucher con il codice indicato non esiste,
• codice 1104 (codice di stato HTTP 401): l'ordine su cui è stato emesso il buono non è stato pagato,
• codice 1105 (codice di stato HTTP 401): il buono è già stato utilizzato,
• codice 1106 (codice di stato HTTP 401): il buono è stato rimborsato,
• codice 1107 (codice di stato HTTP 401): l'ordine o il buono è stato annullato,
• codice 1108 (codice di stato HTTP 401): l'evento è già stato fatturato al partner; non è possibile richiedere ulteriori voucher,
• codice 1109 (codice di stato HTTP 401): i voucher per questo evento non sono ancora iniziati ad essere validi,
• codice 1111 (codice di stato HTTP 500): errore interno del server,
• codice 1112 (codice di stato HTTP 403): il buono deve essere riscattato solo tramite prenotazione

Richiesta di esempio

https://www.slevomat.cz/api/vouchercheck?code=1234-5677-77-111&token=123456789012345

Esempio di risposta

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <název voucheru>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Riscattare un buono

• Azione: voucherApply
• parametri: token (obbligatorio; token partner univoco), codice (obbligatorio; codice voucher)

Tenta di riscattare il buono del codice fornito.

Il numero del voucher di prova può essere utilizzato per scopi di test. In questo caso, il voucher non verrà riscattato, ma il sistema restituirà una risposta come se fosse stato riscattato.

Formato dei dati di risposta

Il formato della risposta è esattamente lo stesso del controllo di validità del voucher.

Condizioni di errore

• Codice 1201 (codice di stato HTTP 400): non è stato inserito alcun token di autenticazione o codice voucher,
• Codice 1202 (codice di stato HTTP 403): il token non è nel database,
• codice 1203 (codice di stato HTTP 404): il voucher con il codice indicato non esiste,
• codice 1204 (codice di stato HTTP 401): l'ordine su cui è stato emesso il buono non è stato pagato,
• codice 1205 (codice di stato HTTP 401): il buono è già stato utilizzato,
• codice 1206 (codice di stato HTTP 401): il buono è stato rimborsato,
• codice 1207 (codice di stato HTTP 401): l'ordine o il buono è stato annullato,
• codice 1208 (codice di stato HTTP 401): l'evento è già stato fatturato al partner; non è possibile richiedere ulteriori voucher,
• codice 1209 (codice di stato HTTP 401): i buoni per questo evento non sono ancora scaduti,
• codice 1211 (codice di stato HTTP 500): errore interno del server
• codice 1212 (codice di stato HTTP 403): il buono deve essere riscattato solo tramite prenotazione

Richiesta di esempio

https://www.slevomat.cz/api/voucherapply?code=1234-5677-77-111&token=123456789012345

Esempio di risposta

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <název voucheru>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Nota: per usare la Partner API per dedurre il valore o i prodotti nel tuo carrello, prendi in considerazione l'inclusione di più attributi del parametro voucherData. Ciò è particolarmente importante quando hai più promozioni in corso con diversi valori di prodotti offerti. In particolare, ti consigliamo di usare attributi di prodotto o variante.