Rozetka Seller API: scaricare gli ordini quando non ci sono webhook
Rozetka non invia webhook e filtra gli ordini solo per data. Ecco come deve essere un ciclo di importazione affidabile, di conseguenza — e le tre cose che ne rompono silenziosamente uno ingenuo.
La maggior parte delle integrazioni parte chiedendo dove Rozetka invierà il suo webhook. La risposta è: da nessuna parte. La Seller API di Rozetka è un’API a richiesta, non a eventi: finché non chiedi se ci sono nuovi ordini, non lo saprai.
Questo cambia l’intera architettura. Invece di un endpoint che aspetta, serve un ciclo che gira a intervalli, ricorda dove si era fermato l’ultima volta e non crea duplicati quando la stessa esecuzione avviene due volte. Di seguito trovi il contratto così come si comporta davvero e i tre punti in cui un’implementazione ingenua perde ordini in silenzio.
Il contratto: cosa sapere prima della prima richiesta
I valori qui sotto provengono dalla documentazione ufficiale della Seller API. Il connettore di Obriym CRM è costruito su questo contratto; stato — beta.
- Base
- api-seller.rozetka.com.ua — un host separato dal sito pubblico
- Autenticazione
- POST /sites con il login del venditore e la password codificata in base64. La risposta contiene un token che dura circa 24 ore.
- Lettura degli ordini
- GET /orders/search — sempre con righe d’ordine, consegna e acquirente espansi, altrimenti l’ordine arriva senza prodotti né indirizzo
- Filtro temporale
- Per DATA, non per ora. Il contratto non offre una precisione del tipo «da questo minuto».
- Righe d’ordine
- Un array di acquisti dentro l’ordine; una riga contrassegnata come eliminata è presente nella risposta e va saltata
- Stati
- Numerici e dipendenti dalla configurazione del singolo account — non un elenco universale
- Scrittura dello stato
- PUT /orders/{id} — dopo il login, con lo stesso token
- Prodotti
- GET /items/search per leggere; PUT /items/update-price-stock/{id} per prezzo e giacenza. Creare un’inserzione via API non è possibile.
- Valuta
- Grivna
Il ciclo di importazione
- 1
Login e token
Scambia login e password con un token. Mettilo in cache: fare il login a ogni richiesta aggiunge latenza e rumore inutile nel registro di audit del marketplace.
- 2
Leggi il cursore
Recupera la data salvata dell’ultima esecuzione riuscita. Alla primissima esecuzione torna indietro di un giorno, non «da sempre»: importare l’intero storico alla prima esecuzione è la via più rapida per un timeout e uno stato parziale poco chiaro.
- 3
Interroga con una sovrapposizione
Chiedi gli ordini modificati dalla data del cursore MENO un giorno. La sovrapposizione non è paranoia — deriva direttamente dal filtro solo per data (dettagli sotto).
- 4
Normalizza
Mappa la risposta nel tuo modello di ordine con una funzione pura e senza effetti collaterali: così puoi testarla su un payload salvato senza alcuna chiamata di rete.
- 5
Scrittura idempotente
Crea l’ordine con una chiave costruita sull’id dell’ordine Rozetka. Un’esecuzione ripetuta non crea un secondo ordine — trova quello esistente.
- 6
Arricchimento
A ogni passaggio, non solo alla creazione, aggiorna stato, pagamento, metodo di consegna e numero della lettera di vettura non appena Rozetka li restituisce.
- 7
Scrivi il cursore
E sposta il cursore solo dopo un passaggio riuscito. Un cursore avanzato prima dell’elaborazione perde proprio gli ordini su cui l’esecuzione è fallita.
Perché un cursore giornaliero ha bisogno di una sovrapposizione
Il filtro «modificati dalla data X» non ha una componente oraria. Significa che non puoi chiedere cosa è cambiato negli ultimi 15 minuti — solo cosa è cambiato oggi.
Da qui il problema del confine di mezzanotte. Un’esecuzione alle 23:58 vede gli ordini di oggi e scrive il cursore come «oggi». Un’esecuzione alle 00:03 chiede gli ordini modificati da «oggi» — ma oggi ora è un’altra data, e un ordine creato alle 23:59 non rientra in nessuna delle due query. Semplicemente sparisce, e il peggio è che nulla fallisce: i log sono puliti, i contatori sono verdi, e l’ordine non c’è.
La cura è economica: interroga sempre dalla data del cursore meno un giorno. Rileggi ogni volta fino a un giorno di ordini già noti — ed è proprio per questo che il passaggio precedente, l’idempotenza, è obbligatorio e non un di più. Senza, la sovrapposizione produrrebbe duplicati ogni giorno; con l’idempotenza la sovrapposizione è gratuita.
Tre cose che rompono un’implementazione ingenua
- Una riga d’ordine contrassegnata come eliminata arriva nella risposta insieme a quelle attive. Saltala, altrimenti ottieni un ordine con un prodotto che l’acquirente non ha mai comprato e un totale che non coincide con l’account.
- Gli stati numerici non sono universali: gli stessi numeri possono indicare stati diversi in account diversi. La mappatura degli stati va quindi in UN solo blocco esplicito che puoi vedere e verificare, non in costanti sparse nel codice. E una transizione di cui non sei sicuro è più sicuro non inviarla che tirare a indovinare.
- Il passaggio in consegna richiede una lettera di vettura. Impostare «spedito» senza un numero di lettera di vettura non è uno stato in cui Rozetka accetta l’ordine, quindi questa transizione non dovrebbe far parte di una sincronizzazione inversa automatica.
Prezzi e giacenza: solo ciò che è già pubblicato
L’aggiornamento di prezzo e quantità funziona per SKU: il campo articolo dell’inserzione Rozetka viene confrontato con lo SKU del prodotto nel tuo sistema. Ne derivano due cose. Primo, la disciplina sugli SKU conta più di qualsiasi codice: un prodotto senza SKU, o con uno che differisce per maiuscole o per uno spazio in più, non corrisponderà. Secondo, l’API aggiorna solo inserzioni esistenti; non può creare un prodotto, quindi pubblicare una nuova posizione resta un’azione nell’account del venditore.
La quantità va inviata solo per i prodotti di cui tieni davvero traccia della giacenza. Un prodotto su ordinazione non deve ricevere quantità zero solo perché il suo campo giacenza è vuoto — lo toglierebbe dalla vendita senza alcun motivo.
Ogni scrittura nell’account di un altro è disattivata per impostazione predefinita
Un venditore arriva con prodotti che vivono già sul marketplace. La lettura può quindi essere attivata subito, mentre qualsiasi scrittura — prezzi, giacenza, stati — attende una prova a vuoto che mostri esattamente cosa cambierebbe senza cambiare nulla. Non è paranoia: un solo invio massivo di prezzi sbagliati su un catalogo attivo costa più dell’intera integrazione.
Domande frequenti
Rozetka ha webhook per gli ordini?
No. La Seller API risponde alle richieste ma non emette eventi, quindi i nuovi ordini si possono ottenere solo con un polling periodico. Un intervallo pratico è 15 minuti: più spesso non porta nulla visto il filtro solo per data, meno spesso si nota per un manager.
Quanto dura un token della Seller API?
Circa un giorno. Fai il login in modo lazy — quando non c’è un token o non viene più accettato — e non a ogni chiamata.
Perché la password è codificata in base64?
Perché lo specifica il contratto di login. È una codifica, non una cifratura: la password va comunque conservata cifrata dal tuo lato e lo scambio deve avvenire su HTTPS.
Si può creare un prodotto su Rozetka via API?
No. L’API può leggere le inserzioni esistenti e aggiornarne prezzo e giacenza. La creazione di una nuova posizione avviene nell’account del venditore.
Come evito ordini duplicati a una nuova esecuzione?
Con una chiave di idempotenza costruita sull’id dell’ordine Rozetka, applicata alla scrittura nel database. È un prerequisito, non un’ottimizzazione: la sovrapposizione del cursore rilegge ogni giorno gli ordini già noti.
Mi serve un worker separato?
In Obriym CRM no: il polling è integrato e gira a intervalli lato CRM, quindi al venditore basta salvare il login del proprio account. Se costruisci l’integrazione da te, un worker ti serve — e il ciclo qui sopra è scritto per quello.
Preferisci non costruirlo da solo?
In Obriym CRM il ciclo di polling, l’idempotenza, l’arricchimento degli stati e la sincronizzazione inversa esistono già — ti basta salvare il login del tuo account Rozetka. Beta: la connessione è disponibile già oggi; le funzionalità del canale sono ancora in fase di rifinitura.
Provalo gratis