API di terze parti

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

Gli ordini esportati nell'API partner non possono più essere manipolati nell'interfaccia partner Slevomat, ma solo visualizzati. La manipolazione degli ordini esportati può avvenire solo tramite l'API.

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

Accesso API

Puoi accedere alle credenziali API dalla scheda Impostazioni nell'interfaccia partner. Per ottenere i dati devi fornire l'URL radice della parte partner dell'API per l'uso nella direzione Slevomat → Partner, ad esempio

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

I dati di accesso verranno visualizzati solo una volta quando si accede all'API, pertanto si prega di salvarli con cura.

Una volta effettuato l'accesso all'API, il sistema inizierà a esportare gli ordini appena creati.

Esportazione iniziale dei dati

Per trasferire gli ordini esistenti al momento dell'accesso all'API, è possibile utilizzare un'esportazione una tantum in CSV nell'interfaccia partner.

Se nel tuo sistema sono presenti ordini esistenti (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, 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 – endpoint o dati richiesti non trovati
• 405 Method Not Allowed – l'endpoint non supporta questo metodo 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 lato server
• 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 lato server

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

In caso di4xx errori, la richiesta in uscita è errata e deve essere corretta 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 di risposta e riprova solo dopo che è trascorso il tempo specificato nell'intestazione.

Stati degli ordini

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 una consegna riuscita, da "Nuovo ordine pagato" è possibile passare direttamente a "Merci spedite" / "Pronte per il ritiro personale" 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'ordine ed è consigliato.

Stati di errore

Nel caso dei codici HTTP 4×x, la risposta contiene sempre la chiavestatus (vedere il codice qui sotto) e il campomessages con descrizioni testuali degli errori.

Esempio:

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

Tipi di dati

I tipi di dati di ogni chiave 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 Slevomat ⇒ Partner

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

L'URL radice dell'API richiesto è fornito dal partner e deve essere nel formato

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

Richiedi autorizzazione

Quando l'API è abilitata, il partner ricevepartner_api_se­cret , il che dimostra che le richieste in arrivo provengono effettivamente da Slevomat.

Questo parametro viene passato nell'intestazione HTTPX-PartnerApiSecret .

Interfaccia di prova

Slevomat include funzionalità per chiamare l'API sul lato partner e visualizzare la risposta. L'URL radice specificato dal partner quando l'API è resa disponibile viene aggiunto a-test , in modo che durante il test l'API venga chiamata 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.sle­vomat.cz/test-zbozi-partner-api/v1/new-order

   – Nuovo Ordine

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/update-shipping-dates 

   – Aggiornamento in blocco delle date di spedizione previste

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/mark-delivered 

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

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/ready-for-pickup 

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

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/confirm-delivery 

   – Conferma di consegna

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/reject-delivery 

   – Rifiuto di accettazione

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/cancel 

   – Annullamento

Sostituisci il<orderId> parte dell'URL con qualsiasi numero d'ordine, 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 .

Quando si effettua una chiamata di prova all'API del partner, il sistema invia ilX-PartnerApiSecret intestazione come avviene durante il funzionamento in tempo reale.

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, è necessario includere ilitems campo nel corpo POST della richiesta in JSON (nello stesso formato inviato dall'API), che l'interfaccia di test convaliderà e inoltrerà all'API partner nello stesso formato.

Nuovo ordine

La richiesta contiene i dati dell'ordine appena creato.

Gli ordini hanno sempre un nome univocoslevomatId Se l'API riceve un duplicatoslevomatId , la richiesta dovrebbe essere ignorata dall'API partner (la prima richiesta è stata valutata come non riuscita da Slevomat e quindi ripetuta) e anche la risposta dovrebbe essereHTTP 204 .

created è la data nel formato ISO 8601, cioèYYYY-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 per la variante di azione quando viene creata nell'interfaccia partner. Viene utilizzato per identificare il prodotto nel sistema del partner.

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

InshippingAddress (indirizzo di consegna) l'azienda (company ) è facoltativo. Nel caso di consegna ashippingAddress contiene l'indirizzo del cliente, in caso di ritiro personale l'indirizzo della struttura presso la quale il cliente ritirerà la merce.

La chiavedelivery .type può assumere il valoreaddress (consegna all'indirizzo) opickup (collezione personale).delivery .name contiene il nome del trasporto o il nome dello stabilimento.

delivery .expec­tedShippingDa­te (data di spedizione stimata) edelivery .expec­tedDeliveryDa­te (data di consegna stimata) sono dati nel formatoYYYY-MM-DD .

La 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": "721896899157", "created": "2021–08–25T15:14:24+02:00", "items": [ { "slevomatId": "960", "productId": "22", "variantId": "105", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "7577400222", "productId": "1752", "variantId": "9855", "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": "Petr Novák", "company": null, "street": "Strašnická 8", "city": "Praha", "postalCode": "100 00", "phone": "+420777888999" }, "delivery": { "type": "address", "name": "PPL", "expectedShip­pingDate": "2021–08–27", "expectedDeli­veryDate": "2021–08–30", "price": 100.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

POST /ordine/$slevomatId

{ "slevomatId": "124146766678", "created": "2021–09–01T12:49:37+02:00", "items": [ { "slevomatId": "863", "productId": "64", "variantId": "14", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "2364201450", "productId": "7057", "variantId": "5802", "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–02", "expectedDeli­veryDate": "2021–09–02", "price": 0.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

Aggiornamento di massa delle date di spedizione previste

Se il gestore delle offerte, su richiesta del partner, sposta le date di spedizione degli 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 di spedizione prevista.

POST /update-shipping-dates

{ "expectedShip­pingDate": "2021–08–25", "slevomatIds": [ "123456", "45454544" ] }

Cancellazione

Le cancellazioni possono essere create sia sul lato Slevomat che sul sistema partner. Questo endpoint gestisce la creazione della cancellazione sul lato Slevomat e il suo trasferimento al sistema del partner.

Crea un annullamento di 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 solo parzialmente singoli articoli (ad esempio 1 di 2).

Una 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 l'ordine come "Consegnato al cliente", chiederemo al cliente di confermare 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 personale"

Questo endpoint verrà chiamato se lo stato precedente "Pronto per la raccolta personale" è stato impostato conautoMarkRea­dyForPickuptrue e l'ordine è stato automaticamente impostato su "Pronto per il ritiro personale" sul lato Slevomat.

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 viene chiamato se lo stato precedente "In arrivo", "Pronto per il ritiro personale" o "Pronto per il ritiro personale" è stato impostato conautoMarkDeli­veredtrue e l'ordine è stato automaticamente commutato sullo stato "Consegnato al cliente – in attesa di conferma del cliente" sul lato Slevomat.

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

{}

Partner di comunicazione ⇒ Slevomat

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

L'URL radice dell'API è

 https://www.slevomat.cz/zbozi-api/v1

Libreria PHP

Per implementare questo lato dell'API, puoi usare la libreria PHP preparata. La libreria richiede attualmente PHP 5.4 o superiore e richiede l'uso di Composer.

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

Richiedi autorizzazione

Quando l'API è abilitata, il partner ricevepartner_token Eapi_secret , che vengono utilizzati per autenticarsi quando si chiama l'API Slevomat.

Questi parametri vengono passati nelX-PartnerToken EX-ApiSecret intestazioni.

Interfaccia di prova

L'URL radice dell'interfaccia di prova è

https://www.slevomat.cz/zbozi-api/v1-test

Su di esso è possibile eseguire tutte le azioni come sull'interfaccia live.

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). In questi aspetti, si comporta in modo identico all'API live.

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 gli ID specificati. Una volta superata l'autorizzazione e la convalida del modulo della richiesta, l'interfaccia di test corrisponde sempre a un codice di successo di 200 o 204.

Creazione di una cancellazione

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

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

Una nota di cancellazione (note ) è facoltativo.

POST /ordine/$slevomatId/annulla

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

Cambia lo stato dell'ordine in "In attesa"

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

{}

Cambia lo stato dell'ordine in "Merci spedite"

Per un ordine, ilautoMarkDelivered Il parametro può essere utilizzato per specificare se deve passare automaticamente allo stato "Consegnato al cliente – in attesa di conferma del cliente" dopo un tempo di spedizione impostato ("Tempo dalla spedizione alla consegna").

La risposta contiene una 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"

Puoi usare il parametroautoMarkReady­ForPickup per specificare se l'ordine debba essere automaticamente impostato sullo stato "Pronto per il ritiro personale" una volta trascorso il tempo che intercorre tra la spedizione e la consegna per un determinato tipo di punto di ritiro.

Per un ordine, ilautoMarkDelivered Il parametro può essere utilizzato per specificare se deve passare automaticamente dallo stato "Pronto per il ritiro personale" allo stato "Consegnato al cliente – in attesa di conferma del cliente" dopo un numero stabilito di giorni per il ritiro presso un determinato tipo di punto di ritiro.

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

La risposta contiene una data di consegna prevista aggiornata.

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

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

Risposta 200

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

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

ILautoMarkDelivered Il parametro può essere utilizzato per specificare se l'ordine debba essere automaticamente impostato sullo stato "Consegnato al cliente – in attesa di conferma del cliente" dopo un numero di giorni stabilito per il ritiro presso un determinato tipo di punto di ritiro.

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 per la consegna a un indirizzo (ad esempio, il luogo del ritiro personale non può essere modificato).

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

Registro delle modifiche