API partner di Slevomat.cz

L'API viene utilizzata per trasferire informazioni sui voucher tra Zľavomat e il sistema del partner commerciale. Permette al partner di verificare la validità dei voucher e riscattare i voucher all'interno del proprio sistema. Pertanto, il partner non ha bisogno di utilizzare l'Interfaccia Partner per questo scopo.

Esempi di possibili utilizzi:

• Un cliente acquista un voucher per il quale è necessario inserire il codice sul sito web del partner per fornire il servizio al momento dell'ordine. Grazie all'API, la validità del voucher viene verificata immediatamente dopo l'inserimento del codice. Il suo valore viene poi detratto nel carrello del partner e contemporaneamente il voucher viene automaticamente riscattato in Zľavomat.
• La validità dei voucher può essere verificata anche nel sistema di prenotazione del partner nello stesso modo, oppure il credito acquistato di un certo valore può essere accreditato direttamente sull'account del cliente sul sito web del partner.

L'API Partner richiede un token che è unico per ogni partner e viene inviato con ogni richiesta. Se desideri utilizzare l'API Partner, contatta il tuo/nostro rappresentante commerciale.

Formato della richiesta

L'endpoint dell'API si trova su /api.

Il formato della richiesta è

<API endpoint URL>/<action>[<parameters>]

Tutte le richieste sono richieste HTTP GET standard, cioè, una richiesta per verificare la validità di un voucher può apparire così:

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

Formato della risposta

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

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

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

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

Tutte le date sono nel formato YYYY-MM-DDTHH:MM:SSZ (ISO8601; ad esempio, 2011⁠–⁠01⁠–⁠01T10:10:10+0­2:00).

Verifica validità voucher

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

Ci sono tre codici voucher di test:

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

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 dati di esempio del voucher e dell'azione).

Formato dati della risposta

{
 "token": <authentication 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 name>,
 "ordered": <order date and time; date and time>,
 "paidDate": <order payment date; date>
 "validFrom": <voucher validity start; date>,
 "validTo": <voucher validity end; date>,
 "key": <voucher code>,
 "code": <voucher code>,
 "product": <action ID>,
 "productName": <action name>,
 "variant": <action variant ID>,
 "variantName": <action variant name>,
 "imageUrl": <image URL>,
 "smallImageUrl": <thumbnail URL>,
 "productUrl": <action URL>
}

Gli elementi variant e variantName contengono l'ID e il nome della variante dell'azione ordinata, se l'azione in questione contiene varianti. In caso contrario, entrambi gli attributi hanno valore NULL.

Stati di errore

• codice 1101 (codice di stato HTTP 400): token di autenticazione o codice voucher non fornito,
• codice 1102 (codice di stato HTTP 403): il token fornito non è nel database,
• codice 1103 (codice di stato HTTP 404): voucher con il codice fornito non esiste,
• codice 1104 (codice di stato HTTP 401): l'ordine sulla base del quale è stato emesso il voucher non è stato pagato,
• codice 1105 (codice di stato HTTP 401): il voucher è già stato riscattato,
• codice 1106 (codice di stato HTTP 401): il voucher è stato rimborsato,
• codice 1107 (codice di stato HTTP 401): l'ordine o il voucher è stato annullato,
• codice 1108 (codice di stato HTTP 401): l'azione è già stata liquidata con il partner; non è possibile riscattare altri voucher,
• codice 1109 (codice di stato HTTP 401): la validità dei voucher per questa azione non è ancora iniziata.
• codice 1111 (codice di stato HTTP 500): errore interno del server

Esempio di richiesta

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

Esempio di risposta

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <voucher name>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Riscatto voucher

• azione: voucherApply
• parametri: token (obbligatorio; token partner unico), code (obbligatorio; codice voucher)

Tenta di riscattare il voucher con il codice fornito.

Per scopi di test, è possibile utilizzare il numero di voucher di test. In tal caso, il voucher non verrà effettivamente riscattato, ma il sistema restituirà una risposta come se lo fosse stato.

Formato dati della risposta

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

Stati di errore

• codice 1201 (codice di stato HTTP 400): token di autenticazione o codice voucher non fornito,
• codice 1202 (codice di stato HTTP 403): il token fornito non è nel database,
• codice 1203 (codice di stato HTTP 404): voucher con il codice fornito non esiste,
• codice 1204 (codice di stato HTTP 401): l'ordine sulla base del quale è stato emesso il voucher non è stato pagato,
• codice 1205 (codice di stato HTTP 401): il voucher è già stato riscattato,
• codice 1206 (codice di stato HTTP 401): il voucher è stato rimborsato,
• codice 1207 (codice di stato HTTP 401): l'ordine o il voucher è stato annullato,
• codice 1208 (codice di stato HTTP 401): l'azione è già stata liquidata con il partner; non è possibile riscattare altri voucher,
• codice 1209 (codice di stato HTTP 401): la validità dei voucher per questa azione non è ancora iniziata.
• codice 1211 (codice di stato HTTP 500): errore interno del server

Esempio di richiesta

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

Esempio di risposta

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <voucher name>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Nota: Per utilizzare l'API Partner per detrarre valore o prodotti nel carrello, considera di includere più attributi del parametro voucherData. Questo è particolarmente importante quando hai diverse azioni in corso con valori diversi dei prodotti offerti. Si consiglia di utilizzare in particolare gli attributi product o variant.