API partner di Slevomat.cz

L'API viene utilizzata per trasferire le informazioni sui voucher tra Discountomat e il sistema del commerciante. Consente al partner di verificare la validità dei voucher nel proprio sistema e di riscattarli. Il partner non ha bisogno di utilizzare l'interfaccia partner per questo scopo.

Possibili esempi di utilizzo:

• Un cliente acquista un buono, dove la condizione per il servizio è di inserire un codice sul sito web del partner quando si crea l'ordine. Grazie all'API, il buono viene immediatamente verificato per la validità dopo questo inserimento. Il suo valore viene quindi detratto nel carrello del partner e allo stesso tempo il buono viene automaticamente riscattato in Discountomat.
• 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 a favore del cliente 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 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 una richiesta per verificare la validità di un buono 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 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": <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>
}

I campi variant e variantName contengono l'ID o il nome della variante ordinata dell'evento, se l'evento contiene varianti. In caso contrario, entrambi gli attributi sono NULL .

Condizioni 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 scaduti.
• codice 1111 (codice di stato HTTP 500): errore interno del server

Richiesta di esempio

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
 }
}

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 della validità del voucher.

Condizioni 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 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 voucher per questo evento non sono ancora scaduti.
• codice 1211 (codice di stato HTTP 500): errore interno del server

Richiesta di esempio

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 usare la Partner API per dedurre il valore o i prodotti nel tuo carrello, prendi in considerazione l'inclusione di più attributi nel parametro voucherData. Questo è importante, specialmente se vuoi usare il parametro voucher. Questo è importante quando hai più promozioni in corso con diversi valori di prodotto. In particolare, ti consigliamo di usare attributi di prodotto o variante.