API beni di terze parti

L'API viene utilizzata per trasferire le informazioni sugli ordini tra Discountomat e il sistema del partner commerciale. L'API richiede l'implementazione di una comunicazione bilaterale: l'API del partner viene chiamata dal sistema Discount e il partner chiama l'API Discount.

Con gli ordini esportati nell'API partner, non è più possibile manipolarli nell'interfaccia del partner, ma solo visualizzarli. La manipolazione degli ordini esportati può essere eseguita solo tramite API.

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

Accessibilità API

Puoi accedere all'API dalla scheda Impostazioni nella tua Interfaccia Partner. Per ottenere i dati, devi inserire l'URL del codice radice della parte partner dell'API per l'uso nella direzione Zlevomat → Partner, ad esempio

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

I dati di accesso verranno visualizzati solo quando si accede all'API, leggerli attentamente e conservarli con cura.

Una volta effettuato l'accesso all'API, gli ordini appena creati vengono inseriti al suo interno e il sistema inizia a esportarli nel sistema.

Esportazione iniziale dei dati

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

Nel momento in cui hai ordini esistenti (creati prima dell'accesso API) nel tuo sistema e vuoi iniziare a lavorarci tramite API, usa 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 mancare o esserci parametri non validi rispetto alle specifiche
• 403 Forbidden – autorizzazione del cliente non riuscita
• 404 Not Found – l'endpoint o i dati richiesti non sono stati trovati
• 405 Method Not Allowed – l'endpoint non supporta questo metodo di protocollo HTTP
• 422 Unprocessable Entity – errore previsto durante l'elaborazione della richiesta (vedere la sezione Condizioni di errore )
• 500 Internal Server Error – si è verificato un errore sul server della pagina
• 502 Bad Gateway – si è verificato un errore 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 server lato server

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

In caso di4xx errori, l'errore è nella richiesta in uscita e deve essere corretto prima di riprovare.

Errori5xx indicano errori del server e la richiesta può essere ritentata senza modificarla. Nel caso di503 , il chiamante deve rispettare ilRetry-After intestazione della risposta e il tentativo successivo viene ripetuto solo dopo che è trascorso il tempo specificato nell'intestazione.

Stati dell'ordine

Un ordine si trova sempre in uno dei seguenti stati:

Il cliente viene informato di eventuali cambiamenti di stato tramite e‑mail.

L'ordine non deve necessariamente passare attraverso tutti gli stati per essere consegnato con successo, è possibile passare direttamente dallo stato "Nuovo ordine pagato" a "In arrivo" / "Pronto per il ritiro" e poi a "Consegnato al cliente – in attesa di conferma del cliente". L'utilizzo di tutti gli stati, tuttavia, porta a migliori informazioni per il cliente sullo stato di avanzamento dell'elaborazione dell'ordine e lo consigliamo.

Stati di errore

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

Esempio:

{ "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 diversamente specificato, il valore tra virgolette"" è sempre una stringa obbligatoria. A meno che non sia specificato diversamente, il valore numerico è sempre un intero obbligatorio.

Comunicazione Discountomat ⇒ Partner

Questa parte dell'API è implementata sul lato partner e viene utilizzata dalle chiamate Zlevomat.

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

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

Richiedi autorizzazione

Quando l'API è abilitata, il partner ricevepartner_api_se­cret , in cui viene verificato che le richieste in arrivo provengano effettivamente da Discount.

Questo parametro viene passato nell'intestazione HTTPX-PartnerApiSecret .

Interfaccia di prova

Discountomat include funzionalità per chiamare l'API sul lato partner e visualizzare la risposta. All'URL radice specificato dal partner quando si accede all'API-test è collegato all'URL del partner, in modo che durante il test venga chiamato API ad esempio

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

per evitare di mischiare dati di prova con ordini reali.

Il test dell'API partner viene effettuato 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 lo stato dell'ordine in "Consegnato al cliente – in attesa di conferma da parte del cliente"

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

   – Modifica lo 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 accettazione

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

   – Annullamento

Sostituisci il<orderId> parte dell'URL con qualsiasi numero d'ordine, con questo numero d'ordine le richieste vengono trasferite al partner API.

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

Quando viene effettuata una chiamata di prova all'API partner, il sistema invia l'intestazioneX-PartnerApiSecret intestazione proprio come nelle operazioni live.

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

Nel caso di invio di un annullamento dell'ordine, il corpo POST della richiesta, include nel campo JSONitems (nello stesso formato inviato dall'API), che verrà convalidato dall'interfaccia di test e inviato all'API partner. L'API lo inoltrerà nello stesso formato.

Nuovo ordine

La richiesta contiene i dati di un ordine appena creato.

Gli ordini hanno sempre un nome univocozlavomatId Se l'API è un duplicatozlavomatId arriva, la richiesta dovrebbe essere ignorata (la prima richiesta convertita è stata valutata come fallita da Discountomat e quindi la ripetiamo) e rispondere anche con HTTP 204.

created è una data in formato ISO 8601, quindiYYYY-MM-DD'T'HH:mm:ss­+zz:zz .

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

L'facoltativointernalId indica l'ID interno immesso quando la variante di un'azione viene creata nell'interfaccia del partner. Serve a identificare il prodotto nel sistema del partner.

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

InshippingAddress (indirizzo di consegna) l'azienda è facoltativa (company ). In caso di consegna ashippingAddress contiene l'indirizzo del cliente, in caso di consegna personale, l'indirizzo del punto vendita presso il quale il cliente ritira la merce.

La chiavedelivery .type può assumere i 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 stimata di consegna) sono dati nel formatoYYYY-MM-DD .

La chiaveweight contiene il peso dell'ordine in chilogrammi. Nel caso in cui non si conosca 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, invia le date di spedizione dei dati in blocco per gli ordini selezionati, il sistema informa l'API del partner di questo aggiornamento.

I dati inviati contengono il campo ID dell'ordine e la nuova data prevista di spedizione.

POST /update-shipping-dates

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

Cancellazioni

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

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

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

La nota di annullamento (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 l'ordine come "Consegnato al cliente", chiederemo conferma al cliente di averlo effettivamente ricevuto. Quando l'ordine viene contrassegnato come ricevuto, verrà chiamato questo endpoint.

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

{}

Rifiuto di accettazione

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

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

Cambia lo stato dell'ordine in "Pronto per il ritiro"

Questo endpoint verrà chiamato se lo stato dell'endpoint precedente è stato impostato su "Pronto per la raccolta personale" conautoMarkRea­dyForPickuptrue e nella pagina Sconti l'ordine è stato automaticamente commutato in "Pronto per il ritiro personale"

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

{}

Cambia lo stato dell'ordine in "Consegnato al cliente – in attesa di conferma del cliente"

Questo endpoint verrà chiamato se lo stato precedente "In arrivo", "Pronto per il ritiro personale" o "Pronto per il ritiro personale" è stato impostato conautoMarkDeli­veredtrue e nella pagina Sconti 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 ⇒ Zľavomat

Questa parte dell'API è implementata sul lato Discountomat e la chiama sistema partner.

L'URL radice dell'API è

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

Libreria PHP

Per l'implementazione di questo lato dell'API è possibile utilizzare la libreria PHP preparata. La libreria richiede attualmente PHP versione 5.4 o superiore e presuppone l'utilizzo dello strumento Composer.

Le istruzioni per l'utilizzo della libreria e il codice sorgente si trovano su GitHub .

Richieste di autorizzazione

Quando l'API è abilitata, il partner ricevepartner_token Eapi_secret , che vengono utilizzati per autenticare la chiamata API di 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

È possibile richiamare tutte le azioni su di essa come sull'altra interfaccia.

L'interfaccia di test controlla l'autorizzazione delle richieste (correttezza del token partner e segreto API) e la validità dei corpi delle richieste in arrivo (JSON). In questi aspetti, si comporta in modo identico all'API crisp.

Tuttavia, l'interfaccia di test non funziona con gli ordini effettivi. Pertanto, non convalida se un ordine passa tra gli stati corretti e se contiene articoli con ID forniti. Una volta che l'autorizzazione e la convalida superano i moduli della richiesta, l'interfaccia di test risponde sempre con un codice di successo 200 o 204.

Creazione di una cancellazione

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

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

La nota di annullamento (note ) è facoltativo.

POST /ordine/$slevomatId/annulla

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

Cambia lo stato dell'ordine in "In lavorazione"

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

{}

Cambia lo stato dell'ordine in "In arrivo"

Quando viene effettuato un ordine, ilautoMarkDelivered Il parametro serve a stabilire se, trascorso il periodo di spedizione impostato ("Tempo dalla spedizione alla consegna"), lo stato debba passare automaticamente allo stato "Consegnato al cliente – in attesa di conferma da parte del cliente".

La risposta contiene la data di consegna stimata aggiornata.

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

{ "autoMarkDeli­vered": true }

Risposta 200

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

Cambia lo stato dell'ordine in "Pronto per il ritiro personale"

Quando l'ordine passa attraverso ilautoMarkReady­ForPickup parametro per specificare se il tempo trascorso dalla spedizione alla consegna per il tipo di punto di ritiro specificato debba essere automaticamente commutato sullo stato "Pronto per la consegna". per il ritiro personale.

Al momento dell'ordine, ilautoMarkDelivered Il parametro determina se, dopo il numero di giorni impostato per il ritiro per un dato tipo di punto di ritiro, lo stato del punto di ritiro debba passare automaticamente da "Pronto per il ritiro personale" a "Consegnato al cliente – in attesa di conferma da parte del cliente".

La combinazione dei parametriautoMarkReady­ForPickup falso eautoMarkDelivered true non è consentito. In questo caso viene restituito il codice di errore 9.

La risposta contiene una data di consegna stimata aggiornata.

POST /ordine/$slevomatId/segna-che-si-prepara-per-il-ritiro

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

Risposta 200

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

Cambia lo stato dell'ordine in "Pronto per il ritiro"

Quando viene effettuato un ordine, ilautoMarkDelivered Il parametro viene utilizzato per determinare se, dopo un numero stabilito di giorni per il ritiro per un dato tipo di ritiro, il punto di ritiro debba essere automaticamente impostato sullo stato "Consegnato al cliente – in attesa di conferma del cliente".

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

{ "autoMarkDeli­vered": true }

Cambia lo stato dell'ordine in "Consegnato al cliente – in attesa di conferma del cliente"

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

{}

Cambia indirizzo di consegna

L'indirizzo di consegna può essere modificato solo al momento della consegna a un indirizzo (ad esempio, non è possibile modificare il luogo di ritiro).

Tutte le chiavi trannecompany sono obbligatori.

Valori validi per ilstate la chiave ècz (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" }