API beni di terze parti

L'API viene utilizzata per trasferire informazioni sugli ordini tra Discount Machine e il sistema del partner commerciale. L'API richiede l'implementazione di una comunicazione bidirezionale: il sistema Discount Machine chiama l'API del partner e il partner chiama l'API Discount Machine.

Gli ordini esportati verso l'API partner non possono più essere manipolati nell'interfaccia partner di Zlavomat, ma solo visualizzati. Gli ordini esportati ora possono essere manipolati solo tramite l'API.

Tutte le richieste devono essere effettuate tramite HTTPS e tutti i dati sono in formato JSON.

Accessibilità API

Puoi accedere all'API nella scheda Impostazioni dell'interfaccia partner. Per recuperare i dati, devi inserire l'URL radice della parte partner dell'API da utilizzare nella direzione Zlavomat → Partner, ad esempio

https://example.com/slevomat-zbozi-api

I dati di accesso verranno visualizzati solo quando si accede all'API, quindi conservali in un luogo sicuro.

Una volta resa disponibile l'API, il sistema inizierà a esportare gli ordini appena creati verso di essa.

Esportazione iniziale dei dati

Per trasferire gli ordini esistenti nel momento in cui l'API è resa disponibile, è possibile utilizzare un'esportazione una tantum in CSV nell'interfaccia partner.

Se nel tuo sistema sono già presenti ordini (creati prima che l'API fosse resa disponibile) e desideri iniziare a lavorarci tramite l'API, utilizza la funzione "Inizia a lavorare con gli ordini contrassegnati tramite API" nel menu "Azioni in blocco con gli ordini".

Descrizione delle risposte HTTP comuni

• 200 OK – la richiesta è stata elaborata con successo
• 204 No Content – la richiesta è stata elaborata con successo, la risposta non ha contenuto
• 400 Bad Request – la richiesta non è valida – potrebbero esserci parametri mancanti o non validi rispetto alle specifiche
• 403 Forbidden – autorizzazione del cliente non riuscita
• 404 Not Found – endpoint o dati richiesti non trovati
• 405 Method Not Allowed – l'endpoint non supporta questo metodo del protocollo HTTP
• 422 Unprocessable Entity – errore previsto durante l’elaborazione della richiesta (vedere la sezione Stati di errore )
• 500 Internal Server Error – si è verificato un errore sul lato server
• 502 Bad Gateway – si è verificato un errore sul lato server
• 503 Service Unavailable – il server è in modalità di manutenzione (potrebbe essere in corso la distribuzione di una nuova versione o un periodo di inattività pianificato)
• 504 Gateway Timeout – si è verificato un errore sul lato server

Le risposte HTTP 5×x non devono utilizzare il formato JSON.

In caso di errori4xx C'è un errore nella richiesta in uscita. È necessario correggerlo prima di riprovare.

Errori5xx indicano errori del server e la richiesta può essere ripetuta senza modificarla. Nel caso di503 il chiamante deve rispettare l'intestazione della rispostaRetry-After e ripetere il tentativo successivo solo dopo che è trascorso il tempo specificato nell'intestazione.

Stati degli ordini

L'ordine si trova sempre in uno dei seguenti stati:

Ogni variazione di stato viene comunicata al cliente tramite e‑mail.

Un ordine non deve necessariamente superare tutti gli stati per essere consegnato correttamente; dallo stato "Nuovo ordine pagato", è possibile passare direttamente a "In arrivo" / "Pronto per il ritiro personale" e poi a "Consegnato al cliente – in attesa di conferma da parte del cliente". Tuttavia, utilizzare tutti gli stati consente di ottenere maggiori informazioni sul progresso dell'ordine e lo consigliamo vivamente.

Stati di errore

Nel caso di codici HTTP 4×x, la risposta contiene sempre una chiavestatus (vedi l'elenco dei codici sotto) e campomessages con descrizioni testuali degli errori.

Campione:

{ "status": 3, "messages": [ "Order #1234 was not found." ] }

Tipi di dati

I tipi di dati delle singole chiavi nelle richieste e nelle risposte sono sempre descritti per endpoint specifici. Salvo diversa indicazione, il valore tra virgolette"" è sempre una stringa obbligatoria. Salvo diversa indicazione, il valore numerico è sempre un intero obbligatorio.

Macchina per sconti sulla comunicazione ⇒ Partner

Questa parte dell'API viene implementata sul lato del partner e Zlavovamat la chiama.

L'URL radice dell'API richiesto verrà condiviso dal partner e dovrebbe essere nel formato

https://www.example.com/slevomat-zbozi-api/v1

Autorizzazione delle richieste

Quando l'API è attivata, il partner ricevepartner_api_se­cret , il che dimostra che le richieste in arrivo provengono davvero da Zlavomat.

Questo parametro viene passato nell'intestazione HTTPX-PartnerApiSecret .

Interfaccia di prova

Il sistema di sconti include funzionalità per richiamare l'API lato partner e visualizzare la risposta. L'URL radice specificato dal partner al momento della messa a disposizione dell'API è allegato a-test , quindi come parte del test, l'API viene chiamata, ad esempio,

https://example.com/slevomat-zbozi-api-test

per evitare di mischiare dati di prova con ordini reali.

I test API dei partner vengono eseguiti tramite richieste POST ai seguenti indirizzi:

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/new-order

   – Nuovo ordine

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/update-shipping-dates

   – Aggiornamento in blocco delle date di spedizione previste

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/mark-delivered

   – Modifica dello stato dell'ordine in "Consegnato al cliente – in attesa di conferma del cliente"

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/ready-for-pickup

   – Modifica dello stato dell'ordine in "Pronto per il ritiro personale"

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/confirm-delivery 

   – Conferma di consegna

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/reject-delivery

   – Rifiuto di accettare

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/cancel

   – Annulla

Parte dell'URL<orderId> sostituisci con un numero d'ordine qualsiasi, le richieste all'API del partner vengono effettuate con questo numero d'ordine.

Le richieste a questa interfaccia di test devono essere autorizzate con le intestazioniX-PartnerToken EX-ApiSecret .

Durante il test di una chiamata API partner, il sistema invia un'intestazioneX-PartnerApiSecret proprio come nelle operazioni dal vivo.

I dati inviati con un nuovo ordine sono di natura di prova e generati in modo casuale.

In caso di invio di un annullamento dell'ordine, è necessario includere il campo JSON nel corpo della richiesta POST.items (nello stesso formato inviato dall'API), che l'interfaccia di test convalida e inoltra all'API partner nello stesso formato.

Nuovo ordine

La richiesta contiene i dati dell'ordine appena creato.

Gli ordini sono sempre unicizlavomatId Se arriva un duplicato nell'APIzlavomatId , l'API partner dovrebbe ignorare la richiesta (la prima richiesta effettuata da Zľavomat è stata valutata come non riuscita e pertanto la stiamo ripetendo) e rispondere anche con HTTP 204.

created è una data nel formato ISO 8601, vale a direYYYY-MM-DD'T'HH:mm:ss­+zz:zz .

productId contiene l'ID dell'azione, variantId ID della variante acquistata.

OpzionaleinternalId Indica l'ID interno inserito per la variante di azione al momento della creazione nell'interfaccia del partner. Viene utilizzato per identificare il prodotto nel sistema del partner.

InbillingAddress (indirizzo di fatturazione) solo il nome (è obbligatorio)name ) del cliente.

InshippingAddress (indirizzo di consegna) è una società facoltativa (company ). In caso di consegna all'indirizzoshippingAddress contiene l'indirizzo del cliente, in caso di ritiro personale, l'indirizzo del punto vendita presso il quale il cliente ritirerà la merce.

Chiavedelivery .type può assumere valoriaddress (consegna all'indirizzo) opickup (collezione personale).delivery .name contiene il nome del trasporto o il nome dell'operazione.

delivery .expec­tedShippingDa­te (data prevista di spedizione) edelivery .expec­tedDeliveryDa­te (data di consegna stimata) è il dato nel formatoYYYY-MM-DD .

Chiaveweight contiene il peso dell'ordine in chilogrammi. Se non conosciamo il peso di tutti gli articoli nell'ordine, assume il valorenull .

POST /ordine/$slevomatId

{ "slevomatId": "480058070336", "created": "2021–09–06T16:39:02+02:00", "items": [ { "slevomatId": "7767", "productId": "25", "variantId": "194", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "4764573102", "productId": "3065", "variantId": "385", "internalId": null, "name": "Ručník modrý", "amount": 10, "unitPrice": 100.0 } ], "billingAddress": { "name": "Petr Novák", "company": null, "street": null, "city": null, "postalCode": null, "country": null }, "shippingAddress": { "name": "Petr Novák", "company": null, "street": "Strašnická 8", "city": "Praha", "postalCode": "100 00", "phone": "+420777888999" }, "delivery": { "type": "address", "name": "PPL", "expectedShip­pingDate": "2021–09–08", "expectedDeli­veryDate": "2021–09–11", "price": 100.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

POST /ordine/$slevomatId

{ "slevomatId": "286238184713", "created": "2021–09–06T16:39:02+02:00", "items": [ { "slevomatId": "3461", "productId": "9", "variantId": "136", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "2320086446", "productId": "2855", "variantId": "7027", "internalId": null, "name": "Ručník modrý", "amount": 10, "unitPrice": 100.0 } ], "billingAddress": { "name": "Petr Novák", "company": "Novák a syn", "street": "Vodičkova 32", "city": "Praha 1", "postalCode": "110 00", "country": "Česko" }, "shippingAddress": { "name": "Provozovna Jahodová", "company": null, "street": "Jahodová 33", "city": "Praha 10", "postalCode": "100 00", "phone": "+420222888999", "deliveryPremise": { "id": 45445, "name": "Provozovna Jahodová" } }, "delivery": { "type": "pickup", "name": "Osobní odběr na provozovně", "expectedShip­pingDate": "2021–09–07", "expectedDeli­veryDate": "2021–09–07", "price": 0.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

Aggiornamento in blocco delle date di spedizione previste

Se il gestore delle offerte, su richiesta del partner, sposta in blocco le date di spedizione degli ordini selezionati, il sistema informa l'API del partner di questo aggiornamento.

I dati inviati includono un campo con l'ID dell'ordine e una nuova data di spedizione prevista.

POST /update-shipping-dates

{ "expectedShip­pingDate": "2021–09–06", "slevomatIds": [ "123456", "45454544" ] }

Cancellare

Le cancellazioni possono essere create sia sul lato Zlavomat che sul sistema partner. Questo endpoint gestisce la creazione delle cancellazioni sul lato Zlavomat e il loro trasferimento al sistema partner.

Crea un annullamento degli articoli dell'ordine nella quantità specificata. Se l'intero ordine deve essere annullato, vengono elencati tutti gli articoli con la quantità corrispondente.

È possibile annullare anche singoli articoli parzialmente (ad esempio 1 articolo su 2).

Nota di cancellazione (note ) è facoltativo.

POST /order/$slevo­matId/cancel

{ "items": [ { "slevomatId": "1212", "amount": 1 }, { "slevomatId": "4545454", "amount": 2 } ], "note": "storno v zákonné lhůtě" }

Conferma di consegna

Dopo aver contrassegnato un ordine come "Consegnato al cliente", chiederemo al cliente di confermare l'effettiva ricezione. Quando un ordine viene contrassegnato come ricevuto, verrà richiamato questo endpoint.

POST /order/$slevo­matId/confirm-delivery

{}

Rifiuto di accettare

POST /order/$slevo­matId/reject-delivery

{ "rejectionReason": "Důvod odmítnutí zákazníkem" }

Modifica dello stato dell'ordine in "Pronto per il ritiro personale"

Questo endpoint verrà chiamato se lo stato precedente "Preparazione per la raccolta personale" è stato impostato suautoMarkRea­dyForPickuptrue e sul lato Zlavomat, l'ordine è stato automaticamente commutato allo stato "Pronto per il ritiro personale"

POST /order/$slevo­matId/delivery-ready-for-pickup

{}

Modifica dello stato dell'ordine in "Consegnato al cliente – in attesa di conferma del cliente"

Questo endpoint verrà chiamato se lo stato precedente era impostato su "In arrivo", "Preparazione per il ritiro personale" o "Pronto per il ritiro personale" conautoMarkDeli­veredtrue e sul lato Zlavomat, l'ordine è stato automaticamente impostato sullo stato "Consegnato al cliente – in attesa di conferma da parte del cliente".

POST /order/$slevo­matId/mark-delivered

{}

Partner di comunicazione ⇒ Macchina per sconti

Questa parte dell'API è implementata sul lato Zľavomat e viene chiamata dal sistema partner.

L'URL radice dell'API è

https://www.zlavomat.sk/zbozi-api/v1

Libreria PHP

Per implementare questa pagina API, è possibile utilizzare una libreria PHP già pronta. La libreria attualmente richiede PHP versione 5.4 o superiore e presuppone l'utilizzo dello strumento Composer.

Le istruzioni e il codice sorgente della libreria sono su GitHub .

Autorizzazione delle richieste

Quando l'API è attivata, il partner ricevepartner_token Eapi_secret , che viene utilizzato per la prova quando si chiama l'API Zlavomat.

Questi parametri vengono passati nelle intestazioniX-PartnerToken EX-ApiSecret .

Interfaccia di prova

L'URL radice dell'interfaccia di prova è

https://www.zlavomat.sk/zbozi-api/v1-test

Su di essa è possibile richiamare tutte le azioni come sull'altra interfaccia.

L'interfaccia di test verifica l'autorizzazione delle richieste (correttezza del token partner e del segreto API) e la validità dei corpi delle richieste in arrivo (JSON). Sotto questo aspetto, si comporta in modo identico all'API live.

Tuttavia, l'interfaccia di test non funziona con gli ordini reali. Non verifica se l'ordine sta transitando tra gli stati corretti e se contiene articoli con gli ID specificati. Una volta superate l'autorizzazione e la convalida del modulo di richiesta, l'interfaccia di test risponde sempre con un codice di successo pari a 200 o 204.

Crea una cancellazione

Crea articoli per l'annullamento dell'ordine in una quantità specificata. Se l'intero ordine deve essere annullato, vengono elencati tutti gli articoli con la quantità corrispondente.

È possibile annullare anche singoli articoli parzialmente (ad esempio 1 articolo su 2).

Nota di cancellazione (note ) è facoltativo.

POST /ordine/$slevomatId/annulla

{ "items": [ { "slevomatId": 45454, "amount": 15 } ], "note": "nepovinná poznámka" }

Modifica dello stato dell'ordine in "In elaborazione"

POST /ordine/$slevomatId/contrassegna-in-attesa

{}

Modificare lo stato dell'ordine in "In arrivo"

Al momento dell'ordine il parametro èautoMarkDelivered determinare se lo stato debba passare automaticamente a "Consegnato al cliente – in attesa di conferma del cliente" dopo il periodo di trasporto impostato ("Tempo dalla spedizione alla consegna")

La risposta include una data di consegna stimata aggiornata.

POST /order/$slevomatId/mark-en-route

{ "autoMarkDeli­vered": true }

Risposta 200

{ "expectedDeli­veryDate": "2021–08–25" }

Modifica dello stato dell'ordine in "Preparazione per il ritiro personale"

Al momento dell'ordine il parametro èautoMarkReady­ForPickup determinare se lo stato debba passare automaticamente a "Pronto per il ritiro personale" una volta trascorso il tempo dalla spedizione alla consegna per un determinato tipo di punto di ritiro.

Al momento dell'ordine il parametro èautoMarkDelivered determinare se lo stato debba passare automaticamente da "Pronto per il ritiro personale" a "Consegnato al cliente – in attesa di conferma del cliente" dopo il numero di giorni impostato per il ritiro presso un determinato tipo di punto di ritiro.

Combinazione di parametriautoMarkReady­ForPickup falso eautoMarkDelivered Il valore true non è consentito. In questo caso, viene restituito il codice di errore 9.

La risposta include una data di consegna stimata aggiornata.

POST /ordine/$slevomatId/mark-getting-ready-for-pickup

{ "autoMarkReady­ForPickup": true, "autoMarkDeli­vered": true }

Risposta 200

{ "expectedDeli­veryDate": "2021–09–06" }

Modifica dello stato dell'ordine in "Pronto per il ritiro personale"

Al momento dell'ordine il parametro èautoMarkDelivered determinare se lo stato debba passare automaticamente a "Consegnato al cliente – in attesa di conferma del cliente" dopo il numero di giorni impostato per il ritiro per un determinato tipo di punto di ritiro.

POST /order/$slevo­matId/mark-ready-for-pickup

{ "autoMarkDeli­vered": true }

Modifica dello stato dell'ordine in "Consegnato al cliente – in attesa di conferma del cliente"

POST /order/$slevo­matId/mark-delivered

{}

Cambio di indirizzo di consegna

L'indirizzo di consegna può essere modificato solo se la consegna avviene all'indirizzo indicato (non è possibile modificare il luogo di ritiro analogo).

Tutte le chiavi trannecompany sono obbligatori.

Valori validi per la chiavestate Sonocz (Repubblica Ceca) esk (Slovacchia).

POST /order/$slevo­matId/update-shipping-address

{ "name": "Karel Novák", "street": "Pod horou 34", "city": "Pardubice", "postalCode": "530 00", "state": "CZ", "phone": "+420777888999", "company": "Knihkupectví Novák" }