Un negozio in cui il catalogo viene letto in tempo reale, non copiato una volta e dimenticato.
Costruiamo negozi e, sopra di essi, lo strato che di solito manca: l’agente che risponde al cliente legge il prezzo e lo stock direttamente dal negozio, nel momento della domanda, e rifiuta di inventare un prezzo non pubblicato.
Già costruitoSe poate verifica din exterior chiar acum, fără să ne întrebi pe noi. Punctul nostru de catalog livrat unui distribuitor răspunde 200 și spune „154 rezultate”; interfața publică a magazinului lui, interogată direct, întoarce antetul `x-wp-total: 154`. Aceeași cifră, două surse independente, verificat pe 06.09.2026. A doua implementare e integrată în platforma de asistenți: serviciul `storeCatalog.service.js` plus trei unelte pe care agentul le poate chema. Rezerva care trebuie spusă: acest al doilea traseu stă pe o ramură de dezvoltare (`feat/store-catalog-global`, `481cfa0`) și nu e încă unificat în trunchi — deci e livrat pentru clienții pe care i-am conectat, nu pornit implicit pentru toți.
La maggior parte delle «integrazioni di catalogo» in realtà è un export. Qualcuno scarica i prodotti una volta, li incolla in un file e, da quel momento in poi, l’agente che parla con il cliente legge una foto vecchia del negozio. Funziona perfettamente fino al primo cambio di prezzo o al primo prodotto esaurito — e allora sbaglia con convinzione, che è peggio che tacere.
Noi leggiamo il negozio nel momento della domanda. Per i negozi WooCommerce esiste un’interfaccia pubblica — Store API — che restituisce prodotti, prezzi e disponibilità senza chiavi, senza account, senza plugin installato. L’indirizzo è `/wp-json/wc/store/v1/products`, lo richiediamo con 100 prodotti per pagina, con un tempo massimo di attesa di 20 secondi, e dall’intestazione della risposta scopriamo quante pagine ci sono, invece di indovinare. La prima pagina la prendiamo da sola, le restanti in parallelo.
La parte che separa un’integrazione corretta da una che sembra corretta è la traduzione del prezzo. Store API non restituisce «129,90»; restituisce una stringa di cifre in unità minori e, separatamente, quante cifre decimali ha la valuta. Chi divide per 100 per abitudine sbaglia in silenzio su qualunque valuta che non abbia due decimali. E, cosa più importante: un prezzo zero non significa gratis, significa non pubblicato. Da noi zero diventa «prezzo su richiesta — si conferma dai colleghi», e l’agente riceve l’istruzione esplicita di non inventare. Si vede nella risposta pubblica del punto di catalogo, proprio ora.
Sul catalogo si aggiungono gli altri pezzi, ognuno con il proprio stato reale: carrello e invio dell’ordine al sistema di gestione del ristorante o del negozio, pagamento tramite l’interfaccia MAIB per i commercianti o tramite Stripe, recupero dei carrelli abbandonati, monitoraggio dello stato dell’ordine con sincronizzazione ogni 15 minuti. Dove non abbiamo un’integrazione funzionante — e ci sono casi del genere — scriva sotto esattamente quale.
Cosa comprende
Il lavoro, per componenti
Catalogo letto in tempo reale, senza chiavi e senza plugin
Per WooCommerce usiamo Store API, l’interfaccia pubblica del negozio: `/wp-json/wc/store/v1/products`, 100 prodotti per pagina, tempo massimo di attesa 20 secondi, un identificatore client proprio nell’intestazione e accettazione esclusiva del codice 200. Il numero di pagine lo leggiamo dall’intestazione `x-wp-totalpages`, e il totale dei prodotti da `x-wp-total` — non paginiamo fino a scoprirlo. La prima pagina si prende da sola, le restanti in parallelo, con un limite di 30 pagine. Non si installa nulla nel negozio e non ci vengono dati chiavi commerciante.
Prezzo tradotto correttamente, e zero trattato come non pubblicato
Store API restituisce il prezzo come stringa in unità minori, più il numero di decimali della valuta. Dividiamo per dieci elevato a quel numero, non per 100 fisso — altrimenti qualsiasi valuta con un numero diverso di decimali risulta errata e nessuno se ne accorge. Lo zero diventa `null`, e nella risposta compare «prezzo su richiesta — si conferma con i colleghi», insieme all’istruzione esplicita data all’agente di non inventare e di chiedere conferma a un collega. Il prezzo parte in due forme contemporaneamente: testo pronto da mostrare nell’interfaccia e numero per la logica di backend.
Tre strumenti che l’agente può chiamare
Nella piattaforma degli assistenti il catalogo è esposto come tre strumenti incorporati — ricerca per parole, corrispondenza per un apparecchio o un caso d’uso, e recupero di un prodotto per identificatore. L’agente li vede con i nomi `catalog_cauta`, `catalog_potrivire` e `catalog_produs`, ciascuno con i propri parametri dichiarati. Quando la piattaforma del negozio non è quella attesa oppure manca l’indirizzo, lo strumento rifiuta esplicitamente invece di restituire una lista vuota che verrebbe interpretata come «non abbiamo il prodotto».
Le parole di collegamento non rovinano il risultato
“Filtro dell’acqua” cercato letteralmente corrisponde a tutto ciò che contiene “di”. Nel punto di catalogo consegnato e nella ricerca del widget vocale tagliamo l’elenco delle parole vuote — `e`, `o`, `di`, `da`, `a`, `con`, `su`, `in`, `per` — e, se dopo il taglio non resta nulla di utile, torniamo alle parole più lunghe di due lettere. La corrispondenza parziale ha una soglia: un prodotto entra nei risultati solo se raggiunge almeno la metà delle parole rimanenti.
Quando il negozio non ha interfaccia, leggiamo la pagina
Non tutti i negozi hanno Store API. Per gli altri abbiamo un estrattore che apre le pagine di elenco e legge le loro schede prodotto, con un budget scritto nel codice: massimo 20 pagine di elenco, 200 prodotti, 24 pagine di dettaglio, 50.000 caratteri di HTML per pagina, 5 secondi per richiesta e un limite di 45 secondi per l’intera operazione. Legge prima i dati strutturati di tipo prodotto dalla pagina, poi le schede, poi i metadati di condivisione — in quest’ordine, perché la prima fonte è quella che il negozio ha scritto intenzionalmente.
Freschezza con limiti scritti, non con la speranza
Il catalogo resta in memoria per 10 minuti per negozio, e le richieste simultanee per lo stesso negozio si fondono in una sola, così che dieci clienti che chiedono nello stesso momento non producano dieci download. Sul punto pubblico del catalogo, la risposta porta anche l’istruzione di cache per la rete di distribuzione: 5 minuti fresco, altri 10 minuti servito vecchio mentre si aggiorna in background. Il numero di risultati restituiti è limitato a 20, con valore predefinito 6.
Ordine, carrello e collegamento con il sistema gestionale
Il carrello, l’invio dell’ordine e la sua consegna al sistema gestionale del cliente sono funzioni separate, non un modulo. Esistono anche il recupero dei carrelli abbandonati, l’ordine tramite conversazione e il tracciamento dello stato dell’ordine, con due attività pianificate che girano ogni 15 minuti — una sincronizza il risultato degli ordini, l’altra completa gli stati dal sistema gestionale su una finestra di due giorni indietro e un giorno avanti.
Pagamenti: cosa è funzionante e cosa no
Funzionante e nel codice: l’interfaccia MAIB per i commercianti — token, poi richiesta di pagamento, con le credenziali di ogni negozio lette dal database e la funzione attivata esplicitamente — e Stripe, con importo convertito in unità minori e incasso salvato nei registri. Ciò che NON è funzionante, per evitare sorprese: Paynet, Netopia e mobilPay non hanno implementazione, e il codice rifiuta esplicitamente quando vengono richiesti. Il percorso Moldindconbank è uno scheletro che restituisce errore senza credenziali. Li prendiamo nel progetto come lavoro, non come integrazione esistente.
L’agente non inventa quando la rete cade
Se la query del negozio fallisce, lo strumento non restituisce una lista vuota — restituisce un messaggio che dice all’agente di non formulare una risposta sul catalogo. La differenza è importante: una lista vuota si traduce in «non abbiamo», e un «non abbiamo» detto in modo errato fa perdere un ordine con la stessa certezza di un prezzo sbagliato.
Come si presenta
Il percorso, passo dopo passo.
01
Verifica del negozio, prima di ogni promessa
Interroghiamo l’interfaccia pubblica con una sola richiesta, con un tempo massimo di attesa di 15 secondi, e leggiamo quanti prodotti ha dall’intestazione. Da questa risposta sappiamo se il percorso vivo è possibile, quanti prodotti ci sono e quanto è completa l’informazione sul prezzo. Se il negozio non risponde, lo diciamo prima dell’offerta, non durante l’implementazione.
02
Connessione del catalogo e primo passaggio tra i prezzi
Forniamo la connessione, più un passaggio attraverso i prodotti con prezzo zero o mancante — sono quasi sempre prodotti reali, non errori, e il modo in cui l’agente li tratta è una decisione del negozio, non nostra. Forniamo anche il testo esatto con cui l’agente rifiuta di indicare un prezzo non pubblicato.
03
Gli strumenti dell’agente e i loro limiti
Impostiamo la ricerca, la corrispondenza e il recupero di un prodotto, ciascuno con il numero massimo di risultati stabilito insieme. Qui si scrivono anche i sinonimi propri del negozio — come il cliente chiama un prodotto rispetto a come lo definisce il catalogo. Senza questo passaggio, la ricerca è tecnicamente corretta e praticamente inutile.
04
L’ordine, il pagamento e il collegamento con la gestione
Si costruiscono in quest’ordine, e ogni parte entra solo dopo aver verificato il reale accesso al sistema dall’altro capo. Per i pagamenti si parte solo da un fornitore per il quale abbiamo un’implementazione funzionante; il resto si tratta come un nuovo lavoro, con il rischio detto in precedenza, non come una spunta nell’offerta.
05
La consegna, con l’elenco delle mancanze
Consegniamo gli indirizzi, le configurazioni, i limiti scritti nel codice e l’elenco di ciò che non è coperto. Ad esempio: il punto pubblico del catalogo consegnato non ha un tempo massimo di attesa sulla richiesta al negozio — se il negozio risponde molto lentamente, la richiesta si prolunga. È una mancanza reale, la inseriamo nell’elenco di consegna e nel piano di riparazione, non in una nota interna.
Magazinul, agentul care răspunde, sistemul de gestiune și furnizorul de plată — patru sisteme separate, cu o singură sursă de adevăr pentru preț: magazinul, citit în momentul întrebării.
I dati
Cosa tocchiamo, dove risiedono e quanto rimangono
Le domande che pone chiunque abbia un responsabile della protezione dei dati — poste qui prima che le ponga lui.
I dati di catalogo
Denominazione, descrizione breve, prezzo attuale e prezzo di listino, disponibilità, immagine, categoria e indirizzo del prodotto — tutti letti dall’interfaccia pubblica del negozio, che li pubblica comunque a qualsiasi visitatore. Non copiamo il database del negozio e non chiediamo chiavi di commerciante. Restano al cliente; noi li leggiamo su richiesta.
Dove vengono conservati e per quanto
Il catalogo viene mantenuto nella memoria del processo per 10 minuti per negozio e scompare al riavvio — non esiste una sua copia persistente da noi. Sul punto pubblico del catalogo, la rete di distribuzione lo mantiene ancora fresco per 5 minuti e come versione vecchia per 10 minuti mentre si aggiorna. Un’esportazione congelata, quando è l’unica opzione tecnica, viene contrassegnata esplicitamente come istantanea con data, non come fonte viva.
I dati della conversazione e dell’ordine
Ciò che chiede il cliente e ciò che ordina passano attraverso la piattaforma di conversazione e, dove necessario, verso il sistema di gestione del negozio. Chi ha accesso, per quanto tempo si conservano e cosa viene eliminato si stabilisce per progetto, con il registro dei trattamenti scritto prima dell’avvio, non dopo il primo incidente.
Le credenziali di pagamento
Le credenziali del commerciante si trovano nel database della piattaforma, per negozio, e si leggono solo quando la funzione di pagamento è attivata esplicitamente per quel negozio. Non finiscono nella pagina pubblica e non passano attraverso la conversazione. La configurazione dell’account commerciante viene fatta dal titolare dell’account, non da noi.
Ciò che non tocchiamo
Non trattiamo i dati della carta. Non chiediamo accesso da amministratore al negozio per la lettura del catalogo — l’interfaccia usata è pubblica. Quando un progetto richiede davvero accesso privilegiato, lo si chiede separatamente, con finalità scritta, e non si tiene «per ogni evenienza».
Un caso
Un catalogo di 154 prodotti, letto al momento della domanda
La situazione
Un distributore di caffè e acqua a Chișinău, con negozio su WooCommerce e agenti che rispondono ai clienti in testo e al telefono. Il catalogo cambia spesso; un elenco copiato una sola volta diventa errato in pochi giorni, e un prezzo sbagliato detto al telefono non si ritira.
Cosa abbiamo costruito
Abbiamo montato un punto catalogo separato, che interroga l’interfaccia pubblica del negozio: 100 prodotti per pagina, numero di pagine letto dall’intestazione, prima pagina presa da sola e il resto in parallelo, tetto di 30 pagine. Il prezzo si traduce dalle unità minori in base al numero di decimali dichiarato dal negozio; zero diventa «prezzo su richiesta — da confermare dai colleghi», con istruzione scritta per l’agente di non inventare. La ricerca taglia le parole di collegamento e chiede che un prodotto raggiunga almeno la metà delle parole rimaste prima di comparire nei risultati. La risposta viene mantenuta per 10 minuti in memoria e 5 minuti nella rete di distribuzione, con altri 10 minuti serviti vecchi mentre si aggiorna. Gli agenti vocali lo richiamano come semplice punto web, non come integrazione speciale.
Cosa è emerso
Verificato il 06.09.2026, in due richieste indipendenti: il punto catalogo risponde «154 risultati» e elenca il primo prodotto con prezzo e disponibilità, mentre il secondo con «prezzo su richiesta — da confermare dai colleghi»; interrogata direttamente, l’interfaccia del negozio restituisce `x-wp-total: 154`. Lo stesso numero da due fonti che non si conoscono tra loro — questa è la verifica, non la nostra dichiarazione.
Cosa non dice il caso
Il punto catalogo consegnato non ha un tempo massimo di attesa sulla richiesta verso il negozio: se il negozio risponde molto lentamente, la richiesta si prolunga invece di interrompersi in modo pulito. È una mancanza reale, emersa alla rilettura del codice, ed è nell’elenco delle riparazioni — non in quello delle funzioni. Separatamente: il filtro delle parole vuote descritto sopra è attivo nel punto consegnato e nella ricerca del widget vocale; nella variante incorporata nella piattaforma non è ancora portato, quindi lì una ricerca con molte parole di collegamento dà risultati più ampi.
Domande
Cosa ci chiedono le persone prima di chiamare
Che cosa significa «catalogo vivo» e come verifico che non sia una frase fatta?
Significa che l’agente legge il negozio nel momento della domanda. Si verifica in due richieste, senza noi: il nostro punto catalogo per un distributore risponde «154 risultati», e l’interfaccia pubblica del suo negozio, interrogata direttamente, restituisce nell’intestazione `x-wp-total: 154`. Lo stesso numero, due fonti indipendenti, alla stessa data. Un catalogo copiato una volta non può farlo — si desincronizza al primo cambiamento.
Devo darvi chiavi o accesso al negozio?
Per la lettura del catalogo su WooCommerce, no. Store API è l’interfaccia pubblica del negozio: gli stessi dati che vede ogni visitatore, serviti in formato leggibile dal programma, senza chiave del commerciante e senza plugin installato. Il commento è scritto proprio nel nostro codice, così non si perde. Chiediamo accesso privilegiato solo dove la funzione lo richiede davvero — per esempio nell’invio degli ordini al sistema di gestione — e allora con uno scopo scritto.
Che cosa succede ai prodotti senza prezzo?
Sono trattati come non pubblicati, non come gratuiti. Nell’interfaccia del negozio un prezzo assente arriva come zero, e una integrazione ingenua lo mostra «0 MDL». Da noi zero diventa «prezzo su richiesta — da confermare dai colleghi», e l’agente riceve l’istruzione esplicita di non inventare una cifra e di chiedere la conferma di una persona. Si vede nella risposta pubblica: il secondo prodotto nell’elenco appare esattamente così.
Quanto è fresco il prezzo, concretamente?
Al massimo 10 minuti di anzianità a livello della piattaforma, per negozio, e le richieste simultanee per lo stesso negozio si fondono in un solo download. Sul punto pubblico di catalogo, la rete di distribuzione serve per 5 minuti la versione fresca e per altri 10 minuti la versione vecchia, mentre la aggiorna in background. I valori sono configurabili per progetto; sono scritti come variabili, non nascosti.
Il mio negozio non è su WooCommerce. Che fate?
Dipende da ciò che espone. Se ha una interfaccia propria, la leggiamo come qualsiasi altra. Se non ha nulla, abbiamo un estrattore che apre le pagine di elenco e legge le schede prodotto, con budget scritto nel codice: 20 pagine, 200 prodotti, 5 secondi per richiesta, 45 secondi di termine limite. Legge prima i dati strutturati della pagina, poi le schede, poi i metadati di condivisione. È una soluzione di riserva onesta, non equivalente: un negozio che cambia tema può rompere l’estrattore, mentre una interfaccia no.
Quali pagamenti potete integrare subito?
Funzionalmente e nel codice: l’interfaccia MAIB per commercianti — ottenimento del token, poi richiesta di pagamento, con le credenziali di ciascun negozio lette dal database e la funzione attivata esplicitamente — e Stripe, con l’importo convertito in unità minori e l’incasso salvato nei registri. Ciò che non è funzionale, detto prima del contratto: Paynet, Netopia e mobilPay non hanno implementazione, e il codice rifiuta esplicitamente quando vengono richiesti; il percorso Moldindconbank è uno scheletro che restituisce errore senza credenziali. Ognuno di essi si può costruire, ma entra come lavoro nuovo, con il suo rischio.
L’agente può inventare un prodotto che non avete?
Può darsi, se non lo impedisce — ed è di questo che ci occupiamo noi. Tre barriere: il prezzo non pubblicato arriva con l’istruzione scritta di non inventare; la piattaforma sbagliata o l’indirizzo mancante fanno sì che lo strumento rifiuti esplicitamente, non che restituisca una lista vuota; e la caduta della rete restituisce un messaggio che dice all’agente di non formulare una risposta sul catalogo. La differenza tra «lista vuota» e «non sono riuscito a leggere» è la differenza tra un ordine perso e uno rinviato con una frase.
Perché conta chi divide per 100?
Perché l’interfaccia non invia «129,90». Invia una stringa di cifre in unità minori e, separatamente, quante cifre decimali ha la valuta. Dividere per 100 è corretto per le valute con due decimali e silenziosamente sbagliato per le altre — nessuno riceve un errore, solo cifre sbagliate. Noi dividiamo per dieci elevato al numero dichiarato dal negozio. È una riga di codice, ed è esattamente il tipo di riga da cui si vede se qualcuno ha letto la documentazione o ha indovinato.
Che cosa non vi assumete?
Non prendiamo dati di carte e non configuriamo l’account commerciante al posto del titolare. Non garantiamo che un estrattore di pagine resista a un cambio di tema del negozio — per questo preferiamo l’interfaccia quando esiste. Non promettiamo aumenti delle vendite; ciò che possiamo mostrare è che la cifra detta dall’agente coincide con la cifra del negozio, alla stessa data. E non presentiamo come integrazione qualcosa che nel codice è uno scheletro: l’elenco sopra indica quali sono.
Su cosa si basano le affermazioni sopra (18 fonti)
16 di esse sono codice e file dei nostri repository. Non ne pubblichiamo il nome né la riga: insieme, in un'unica pagina, descriverebbero con troppa precisione come sono costruiti sistemi che non sono solo nostri. Le esaminiamo con te, nel repository, su richiesta — la verifica resta possibile, solo che avviene in una discussione.