API partner di Slevomat.cz

L'API viene utilizzata per trasferire informazioni sui voucher tra Zlavomat e il sistema del partner commerciale. Permette al partner di verificare la validità dei voucher nel proprio sistema e di riscattarli. Il partner non è tenuto a utilizzare l'interfaccia partner per questo scopo.

Possibili esempi di utilizzo:

• Il cliente acquista un buono, la cui erogazione è subordinata all'inserimento del codice sul sito web del partner al momento dell'ordine. Grazie all'API, la validità del buono viene immediatamente verificata. Il suo valore viene quindi detratto dal carrello del partner e il buono viene automaticamente utilizzato su Zlavomot.
• Allo stesso modo, la validità dei voucher può essere verificata anche nel sistema di prenotazione del partner oppure il cliente può caricare un credito acquistato di un certo valore direttamente sul sito web del partner.

L'API Partner richiede un token univoco per ciascun partner , che viene inviato con ogni richiesta. Se desideri utilizzare l'API Partner, contatta il tuo/nostro commerciante.

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 la richiesta per verificare la validità del voucher potrebbe apparire così:

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

Formato di risposta

La risposta del server è sempre in formato JSON con la corrispondente intestazione Content-type. 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, l'elemento errore contiene il codice di errore ( code ) e la sua descrizione ( message ). Oltre all'indicazione nel campo 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).

Verifica della validità del voucher

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

Sono disponibili tre codici voucher di prova:

• 1234–5677–77–111 (pagato, non utilizzato),
• 2234–5688–88–222 (pagato, usato),
• 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 un voucher di esempio e dati sull'azione).

Formato dei dati di risposta

{
 "token": <autentizační token>,
 "code": <kód voucheru>,
 "voucherData": <data voucheru>
}

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

{
 "id": <ID voucheru>,
 "orderId": <ID objednávky>,
 "title": <název voucheru>,
 "ordered": <datum a čas objednávky; datum a čas>,
 "paidDate": <datum zaplacení objednávky; datum>
 "validFrom": <začátek platnosti voucheru; datum>,
 "validTo": <konec platnosti voucheru; datum>,
 "key": <kód voucheru>,
 "code": <kód voucheru>,
 "product": <ID akce>,
 "productName": <název akce>,
 "variant": <ID varianty akce>,
 "variantName": <název varianty akce>,
 "imageUrl": <URL obrázku>,
 "smallImageUrl": <URL náhledu>,
 "productUrl": <URL akce>
}

Gli elementi varianti o variantName contengono l'ID o il nome della variante ordinata dell'azione, se l'azione specificata contiene varianti. In caso contrario, entrambi gli attributi sono NULL .

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 specificato non è presente 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 in base al quale è stato emesso il voucher 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 voucher è stato annullato,
• codice 1108 (codice di stato HTTP 401): l'azione è già stata fatturata al partner; non è possibile applicare altri voucher,
• codice 1109 (codice di stato HTTP 401): la validità dei voucher per questo evento 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": <název voucheru>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Riscatto del buono

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

Verrà effettuato un tentativo di riscattare il buono del codice fornito.

È possibile utilizzare il numero del voucher di prova per scopi di test. In tal caso, il voucher non verrà utilizzato, ma il sistema restituirà una risposta come se fosse stato effettivamente utilizzato.

Formato dei dati di risposta

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

Stati di errore

• codice 1201 (codice di stato HTTP 400): il token di autenticazione o il codice voucher non è stato inserito,
• codice 1202 (codice di stato HTTP 403): il token specificato non è presente 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 in base al quale è stato emesso il voucher 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 voucher è stato annullato,
• codice 1208 (codice di stato HTTP 401): l'azione è già stata fatturata al partner; non è possibile applicare altri voucher,
• codice 1209 (codice di stato HTTP 401): la validità dei voucher per questo evento 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": <název voucheru>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Nota: per utilizzare l'API Partner per leggere il valore o i prodotti nel carrello, valuta la possibilità di includere più attributi del parametro voucherData. Questo è particolarmente importante quando hai diverse campagne in corso con valori diversi per i prodotti offerti. Consigliamo di utilizzare principalmente gli attributi prodotto o variante.