Gestire un negozio multi-venditore comporta molte operazioni di copia e incolla. I totali delle commissioni finiscono in un foglio di calcolo, le domande dei nuovi venditori vengono inoltrate a una chat di team e i venditori richiedono esportazioni per poter aggiornare i propri strumenti di inventario o spedizione. Ognuno di questi compiti è una persona che sposta dati manualmente. WC Vendors 2.7.3 cambia tutto questo. Aggiunge un'API del marketplace WooCommerce che consente ad altre app di leggere e aggiornare il tuo marketplace in modo sicuro: venditori, ordini dei venditori, commissioni, tassi di commissione e riepiloghi delle vendite. Aggiunge anche webhook del marketplace e un set di funzionalità che gli assistenti AI possono scoprire ed eseguire sul tuo sito.
In questo articolo spiegheremo cosa include la nuova API, chi può usarla e cosa puoi creare con essa. Poi ti guideremo passo dopo passo nell'impostazione, dalla prima credenziale al tuo primo webhook.
Cos'è l'API del marketplace WooCommerce?
È un insieme di indirizzi web sul tuo sito che altri software possono chiamare per leggere o modificare i dati del marketplace. Gli sviluppatori chiamano questi indirizzi endpoint. Ognuno di essi inizia con /wp-json/wcvendors/v1 e viene fornito nel plugin gratuito WC Vendors dalla versione 2.7.3.
Il rilascio ha tre parti che lavorano insieme.
Endpoint REST per venditori, ordini e commissioni
Gli endpoint coprono i record su cui si basa un marketplace. Le app possono elencare e leggere i fornitori, aggiornare il profilo del negozio e i dettagli di pagamento di un fornitore, e approvare, negare, attivare o disattivare i fornitori. Possono anche leggere i record delle commissioni, leggere gli ordini dei fornitori, leggere e modificare le percentuali di commissione, ed estrarre un riepilogo delle vendite per qualsiasi intervallo di date.
Webhook per eventi del marketplace
I webhook funzionano nella direzione opposta. Invece che un'app chieda al tuo sito notizie, il tuo sito informa l'app nel momento in cui accade qualcosa. WC Vendors aggiunge 11 eventi del marketplace ai webhook di WooCommerce, come una nuova richiesta di fornitore, un'approvazione di fornitore, una nuova commissione e un nuovo ordine di fornitore.
Abilità per agenti AI
WC Vendors registra anche 10 abilità del marketplace con la WordPress Abilities API. Un'abilità è un'azione nominata con un input e un output chiari che gli strumenti AI possono trovare ed eseguire. Cinque abilità leggono solo dati, come un riepilogo del marketplace. Le altre cinque apportano modifiche, come l'approvazione di un fornitore o di un prodotto in sospeso, quindi uno strumento AI ben costruito chiede prima conferma a una persona.
Questo è ciò che consente a un assistente connesso tramite il Model Context Protocol di rispondere a domande come "Quali fornitori sono in attesa di approvazione?" utilizzando i dati live del tuo marketplace.
Perché un negozio multi-fornitore ha bisogno di una propria API
WooCommerce ha già una REST API per prodotti, ordini e clienti. Tuttavia, non sa che i fornitori esistono. Non può dire a un'app quale fornitore possiede un ordine, quanta commissione è dovuta o se un venditore è ancora in attesa di approvazione.
Un'API per marketplace WooCommerce colma questa lacuna. Parla in termini di marketplace, quindi un'app chiede "commissioni dovute al fornitore 42" invece di mettere insieme la risposta da dati grezzi degli ordini.
È anche costruito per un negozio con molti venditori. Le credenziali di un fornitore raggiungono solo i record di quel fornitore. Ciò significa che puoi consentire ai fornitori di connettere i propri strumenti senza esporre ordini, clienti o guadagni di altri.
Chi può usarla e cosa può vedere ciascun utente
Ogni richiesta accede con una credenziale e ciò che viene restituito dipende da a chi appartiene quella credenziale.
- Proprietario del negozio: Qualsiasi utente che può gestire WooCommerce, come un Amministratore o un Responsabile del negozio, vede tutti i fornitori, gli ordini, le commissioni e i report. Solo il proprietario del negozio può approvare, negare, attivare o disattivare i fornitori e modificare le percentuali di commissione.
- Fornitore attivo: Vede solo i propri record. La richiesta di dati di un altro fornitore restituisce un errore.
- Fornitore in sospeso o inattivo: Non ottiene alcun accesso, nemmeno con una credenziale valida.
- Chiunque altro: Non ottiene alcun accesso.
I dettagli privati rimangono privati
I campi bancari e di pagamento appaiono solo quando un'app legge o aggiorna un singolo fornitore. Elenchi di fornitori e messaggi webhook non li includono mai, quindi una singola richiesta non può estrarre tutti i dettagli bancari dei venditori contemporaneamente.
I dettagli del cliente sugli ordini dei fornitori seguono le impostazioni che già utilizzi per la dashboard del fornitore. Li troverai in WC Vendors > Impostazioni > Capacità > Ordini, come spiegato nella nostra guida alle impostazioni delle capacità. Se nascondi l'email o il numero di telefono di un cliente ai fornitori lì, anche l'API lo nasconde, anche quando viene chiamata dal proprietario del negozio.
Limiti di frequenza integrati
Ogni utente può effettuare 100 richieste al minuto per ogni endpoint. Superare il limite restituisce un errore "troppe richieste" fino alla fine del minuto. I limiti di frequenza sono disattivati sui siti impostati in un ambiente locale o di sviluppo, quindi non li vedrai sulla maggior parte dei siti di test.
Cosa puoi costruire con esso
Ecco alcune idee che utilizzano solo ciò che è incluso in WC Vendors 2.7.3.
- Rapporti sulle commissioni per il tuo commercialista: Estrai tutte le commissioni con lo stato "dovuto" per un fornitore prima del giorno del pagamento. Se stai ancora impostando le tue tariffe, la nostra guida su come addebitare commissioni ai fornitori copre le opzioni.
- Avvisi di applicazione istantanei: Invia il webhook "Domanda di fornitore inviata" alla chat del tuo team o al CRM. Il tuo team può esaminare il richiedente e approvarlo tramite API, utilizzando lo stesso processo di approvazione del fornitore della schermata di amministrazione.
- Integrazioni di proprietà del fornitore: Un fornitore crea le proprie credenziali e collega uno strumento di inventario o un'app di spedizione. Quell'app vede gli ordini del fornitore e nessun altro.
- Rapporti settimanali sul marketplace: Richiedi un riepilogo delle vendite della scorsa settimana e ottieni ordini totali, entrate lorde, commissioni dovute, guadagni del marketplace e i tuoi primi 10 fornitori in un'unica risposta.
- Un assistente AI per l'amministrazione del marketplace: Chiedi a un assistente il riepilogo del mese scorso o l'elenco dei prodotti in attesa di approvazione. Il nostro marchio gemello StoreAgent mostra come collegare Claude e ChatGPT al tuo negozio.
Prima di questa versione, ognuna di queste cose richiedeva un plugin personalizzato o un'esportazione manuale. Con l'API del marketplace di WooCommerce, sono una manciata di richieste che qualsiasi strumento di automazione o sviluppatore può configurare.
Come configurare l'API del marketplace di WooCommerce
Non c'è un'impostazione da attivare. Una volta che WC Vendors 2.7.3 è attivo, gli endpoint sono attivi e ogni richiesta necessita di una credenziale. Segui questi passaggi per collegare la tua prima app.
Passaggio 1: Aggiorna WC Vendors e controlla le password delle applicazioni
- Aggiorna WC Vendors alla versione 2.7.3 o successiva. Se WordPress mostra un avviso "Aggiornamento WC Vendors richiesto" in seguito, fai clic su Esegui l'aggiornamento.
- Vai su Utenti > Profilo nella tua bacheca di WordPress e scorri fino a Password delle applicazioni.
- Se vedi un modulo per aggiungere una nuova password, sei pronto. Se la sezione indica che necessita di HTTPS, attiva prima HTTPS per il tuo sito.
- Se la sezione è mancante, un plugin di sicurezza o il tuo host ha disattivato le Password per le applicazioni. Puoi riattivarle o utilizzare invece una chiave API REST di WooCommerce.
Passaggio 2: Crea una credenziale per il proprietario del negozio
L'API accetta due tipi di credenziali, ed entrambe accedono tramite HTTPS.
- Password per le applicazioni: In Utenti > Profilo > Password per le applicazioni, inserisci un nome per l'app, crea la password e copiala subito. WordPress la mostra solo una volta. La guida ufficiale alle Password per le applicazioni spiega come funzionano.
- Chiave API REST di WooCommerce: Vai su WooCommerce > Impostazioni > Avanzate > REST API e aggiungi una chiave per il tuo utente. Una chiave di Lettura può solo leggere i dati. Scegli Lettura/Scrittura se l'app deve modificare qualcosa.
Se hai intenzione di utilizzare le funzionalità AI, crea una Password per le applicazioni. Le chiavi API REST di WooCommerce non funzionano per le funzionalità.
Passaggio 3: Consenti ai venditori di creare le proprie credenziali
I venditori non hanno bisogno che tu crei le credenziali per loro. Possono farlo dalla loro dashboard.
- Il venditore apre la sua dashboard venditore e va su Impostazioni, poi sulla scheda API.
- Clicca su Genera credenziale API.
- La nuova credenziale appare una volta con un pulsante Copia e l'avviso "Salvala ora. Per sicurezza, non verrà mostrata di nuovo."
- Successivamente, la scheda mostra il nome della credenziale, la data di creazione, l'ultima volta che è stata utilizzata e un pulsante Rigenera.
Ogni venditore può avere una sola credenziale alla volta. Rigenerarla richiede conferma, poi disattiva immediatamente quella vecchia, quindi qualsiasi app che la utilizza deve essere aggiornata. La scheda API appare solo quando le Password per le applicazioni sono disponibili sul tuo sito.
Passaggio 4: Effettua la tua prima richiesta
Accedi con il nome utente di WordPress e la Password per le applicazioni. Questa richiesta elenca i primi cinque venditori:
curl -u "USERNAME:APPLICATION_PASSWORD" \
"https://your-site.com/wp-json/wcvendors/v1/vendors?per_page=5"La risposta è un elenco di venditori in formato JSON. Due intestazioni di risposta, X-WP-Total e X-WP-TotalPages, indicano quanti record e pagine esistono, e puoi richiedere fino a 100 record per pagina.
Ecco una richiesta che l'app di un venditore potrebbe fare per vedere le commissioni non ancora pagate:
curl -u "VENDOR_USERNAME:APPLICATION_PASSWORD" \
"https://your-site.com/wp-json/wcvendors/v1/commissions?status=due"Passaggio 5: Aggiungi un webhook per il marketplace
- Vai su WooCommerce > Impostazioni > Avanzate > Webhook e clicca su Aggiungi webhook.
- Inserisci un nome e l'URL di consegna dove la tua app dovrebbe ricevere il messaggio.
- Apri il menu a discesa Argomento e scegli un argomento del marketplace, ad esempio, Venditore approvato o Commissione creata.
- Imposta Stato su Attivo e salva.
WooCommerce gestisce la consegna, la firma e i registri di consegna. La sua documentazione sui webhook spiega come verificare che un messaggio provenga effettivamente dal tuo negozio.
Passaggio 6: Connetti un agente AI con capacità
Le capacità richiedono WordPress 6.9 o versioni successive e una Password applicazione del proprietario del negozio. Per vedere cosa è disponibile, richiedi l'elenco delle capacità nella categoria wcvendors:
curl -u "OWNER_USERNAME:APPLICATION_PASSWORD" \
"https://your-site.com/wp-json/wp-abilities/v1/abilities?category=wcvendors"La maggior parte delle persone non la chiamerà manualmente. Uno strumento AI compatibile con MCP legge lo stesso elenco e decide quale capacità eseguire. Per un esempio pratico dei nostri marchi affiliati, vedi come Advanced Coupons ti consente di gestire i coupon con l'API Abilities di WordPress, o come Wholesale Suite esegue attività all'ingrosso da Claude o ChatGPT.
Gestisci il tuo marketplace da Claude o ChatGPT con StoreAgent
Vuoi un assistente AI che utilizzi queste capacità senza dover configurare tu stesso un server MCP? StoreAgent, il nostro plugin affiliato, fornisce al tuo negozio la propria connessione MCP per Claude e ChatGPT. Approvi la connessione con un accesso, quindi non c'è alcuna chiave API da copiare e scegli l'accesso in sola lettura o in lettura e scrittura.
Le capacità dei tuoi altri plugin appaiono nell'elenco delle capacità di StoreAgent raggruppate per plugin, e ognuna rimane disattivata finché non la attivi. StoreAgent include anche un Moderatore Prodotti WC Vendors che esamina i prodotti dei venditori in sospeso con l'AI prima che tu li approvi. MCP funziona su tutti i piani StoreAgent, incluso quello gratuito.
Vuoi connettere un assistente AI? La nostra guida passo passo, Come usare le capacità AI in WC Vendors, ti mostra come connettere Claude o ChatGPT al tuo marketplace tramite StoreAgent. Spiega anche cosa possono fare le 10 capacità, chi può eseguirle e come risolvere i problemi comuni di configurazione.
Ogni endpoint, webhook e capacità a colpo d'occhio
Endpoint
Tutti i percorsi iniziano con /wp-json/wcvendors/v1.
| Metodo | Percorso | Cosa fa | Chi può usarlo |
|---|---|---|---|
| GET | /vendors | Elenca fornitori | Proprietario del negozio, venditore (proprio record) |
| GET, PUT | /vendors/{id} | Leggi o aggiorna il profilo del negozio e i dettagli di pagamento di un venditore | Proprietario del negozio, venditore (proprio record) |
| POST | /vendors/{id}/approve, /deny | Decidi su una domanda in sospeso | Proprietario del negozio |
| POST | /vendors/{id}/activate, /deactivate | Sospendi o ripristina un venditore | Proprietario del negozio |
| GET, PUT | /vendors/{id}/commission | Leggi o imposta la commissione di un venditore | Proprietario del negozio (i venditori possono leggere la propria) |
| GET, PUT | /settings/commission | Leggi o modifica la commissione globale | Proprietario del negozio |
| GET | /commissions, /commissions/{id} | Leggi i record delle commissioni | Proprietario del negozio, venditore (record propri) |
| GET | /orders, /orders/{id} | Leggi gli ordini dei venditori | Proprietario del negozio, venditore (ordini propri) |
| GET | /reports/sales | Riepilogo delle vendite per un intervallo di date | Proprietario del negozio, venditore (vendite proprie) |
Argomenti webhook
- Venditori: Applicazione venditore inviata, Venditore approvato, Venditore rifiutato, Venditore attivato, Venditore disattivato, Venditore aggiornato ed Eliminazione venditore.
- Commissioni: Commissione creata.
- Ordini venditore: Ordine venditore creato, Ordine venditore aggiornato ed Eliminazione ordine venditore.
Abilità
- Leggi: elenca venditori, ottieni un venditore, elenca prodotti in sospeso, ottieni impostazioni commissioni e ottieni un riepilogo del marketplace.
- Scrivi: approva un venditore, rifiuta un venditore, aggiorna il profilo del negozio di un venditore, approva un prodotto e rifiuta un prodotto.
Nessuna abilità muove denaro, cambia una commissione, cambia dove viene pagato un venditore o elimina un record. Le abilità di scrittura inviano le stesse email dei pulsanti corrispondenti nell'amministrazione di WordPress e un prodotto rifiutato torna al venditore come bozza con il tuo motivo allegato.
Migliori pratiche per un'integrazione sicura del marketplace
Tratta l'API del marketplace di WooCommerce come qualsiasi altra porta del tuo negozio. Queste abitudini la mantengono sicura e affidabile.
- Concedi a ogni app il minimo accesso necessario. Se un'app legge solo i report, concedile una chiave di lettura anziché una chiave di lettura/scrittura.
- Pianifica le modifiche alle credenziali del venditore. Un venditore detiene una credenziale e rigenerarla blocca immediatamente ogni app che utilizzava quella vecchia.
- Controlla le impostazioni del cliente prima di collegare uno strumento di spedizione o contabilità. Se i dettagli del cliente tornano vuoti, rivedi Abilità > Ordini e fai clic su Salva.
- Conserva una tua copia di tutto ciò che potrebbe servirti in seguito. Gli webhook "Venditore eliminato" e "Ordine venditore eliminato" inviano solo l'ID, poiché il record non esiste più.
- Monitora lo stato di salute dei webhook. WooCommerce non reinvia una consegna fallita e disattiva un webhook dopo più di cinque consegne fallite.
- Conosci quali tipi di commissioni richiedono Pro. Senza WC Vendors Pro, l'API accetta solo commissioni percentuali. Le nuove tariffe si applicano alle nuove commissioni e i record esistenti non cambiano.
- Disattiva ciò che non usi. Aggiungere
define( 'WCV_DISABLE_ABILITIES', true );awp-config.phprimuove le abilità, edefine( 'WCV_DISABLE_REST_API', true );rimuove l'intera API.
Per una checklist più completa, leggi la nostra guida alla sicurezza del marketplace WooCommerce.
Conclusione
WC Vendors 2.7.3 offre al tuo negozio qualcosa che non ha mai avuto prima: un modo pubblico e documentato per altri software di interagire con venditori, ordini e commissioni. L'API del marketplace WooCommerce si occupa dei lavori quotidiani che prima richiedevano esportazioni e copia-incolla, dalla riconciliazione delle commissioni all'approvazione di nuovi venditori.
È stato creato tenendo conto dei rischi di un negozio multi-venditore. I venditori vedono sempre e solo i propri dati, i dettagli dei pagamenti rimangono fuori dalle liste e dalle webhook, e le informazioni sui clienti seguono le stesse regole della tua dashboard venditore. Le webhook mantengono aggiornati i tuoi altri strumenti senza polling, e le abilità consentono a un assistente AI di gestire l'amministrazione di routine mentre tu mantieni il controllo di ogni modifica.
Inizia in piccolo. Crea una credenziale, collega una webhook e vedi quanto lavoro manuale scompare. Poi costruisci da lì man mano che il tuo marketplace cresce.
Ecco cosa abbiamo trattato in questo articolo:
- Cos'è l'API del marketplace WooCommerce
- Perché un negozio multi-venditore ha bisogno della sua API
- Chi può usarla e cosa può vedere ciascun utente
- Cosa puoi costruire con essa
- Come configurare l'API del marketplace WooCommerce
- Ogni endpoint, webhook e abilità a colpo d'occhio
- Best practice per un'integrazione sicura del marketplace
Domande frequenti
Ho bisogno di WC Vendors Pro per usare l'API del marketplace WooCommerce?
No. L'API, i webhook e le funzionalità sono tutte parte del plugin gratuito WC Vendors dalla versione 2.7.3. Due cose dipendono da Pro: tipi di commissione diversi dalla percentuale e l'elenco dei prodotti in sospeso, che di solito è vuoto a meno che Pro non sia impostato per revisionare i nuovi prodotti prima che vengano pubblicati.
Un venditore può vedere gli ordini o le commissioni di un altro venditore?
No. La credenziale di un venditore restituisce solo i record di quel venditore. Se l'app di un venditore richiede l'ordine o la commissione di un altro venditore, l'API risponde come se il record non esistesse.
Cosa succede alle vecchie route wcv-api/v1?
Rimangono al loro posto e continuano a funzionare, ma sono bloccate e non riceveranno nuove funzionalità. Le nuove integrazioni dovrebbero utilizzare i percorsi wcvendors/v1 descritti in questo articolo.
Quale versione di WordPress mi serve per le funzionalità AI?
Le abilità richiedono WordPress 6.9 o versioni successive, perché è lì che è stata aggiunta l'API delle Abilità. Gli endpoint REST e le webhook funzionano anche su versioni precedenti supportate.
Posso disattivare l'API?
Sì. Aggiungi define( ‘WCV_DISABLE_REST_API’, true ); al tuo file wp-config.php per rimuovere ogni percorso, argomento webhook e abilità. Per rimuovere solo le abilità, usa invece define( ‘WCV_DISABLE_ABILITIES’, true );.
