Sincronizzare regole e clienti B2B con l’ERP tramite API

Per sincronizzare i prezzi B2B da un ERP a Shopify, usi la Public API di BSS B2B Solution: generi una chiave API con il piano Platinum, poi il Suo sviluppatore o partner di integrazione crea, aggiorna ed elimina le regole Custom Pricing, Price List e Volume Pricing dal sistema di riferimento, e richiama l’endpoint di upload così che le regole attive arrivino al tema live. Il Suo team smette di riscrivere i prezzi in una schermata dell’admin.

Questa guida è per distributori e produttori i cui prezzi, classi di prezzo o gruppi di clienti sono già in un ERP, un PIM o una pipeline di dati. Spiega chi ne trae beneficio, cosa copre l’API e cosa non copre, uno schema di integrazione in cinque passaggi, un esempio concreto e i limiti da considerare, incluso il fatto che non esiste un endpoint per gli ordini. È scritta per chi decide se costruire l’integrazione, e rimanda alla documentazione per sviluppatori per i payload esatti.

A chi è rivolto

La Public API fa per Lei se la maggior parte di queste affermazioni descrive il Suo negozio:

• I prezzi sono mantenuti in un ERP, un PIM o un foglio di calcolo principale, e il negozio Shopify è una seconda copia.
• Ha più classi di prezzo o gruppi di clienti, e una modifica di prezzo tocca centinaia o migliaia di varianti.
• I prezzi cambiano ogni settimana o ogni giorno, quindi un aggiornamento manuale resta indietro tra un’esecuzione e l’altra.
• Ha uno sviluppatore, un’agenzia o un partner di integrazione in grado di scrivere un job pianificato.
• Esporta già i dati dei prezzi in CSV e vuole che gli stessi dati fluiscano senza che nessuno apra l’app.

Se il Suo listino cambia poche volte l’anno, un import CSV è più semplice. Veda importare prezzi all’ingrosso da CSV.

Perché conta

Due copie di un listino prezzi si disallineano. Qualcuno aggiorna l’ERP il lunedì, dimentica il negozio, e martedì un acquirente vede il prezzo del trimestre precedente. L’acquirente ordina al prezzo sbagliato e Lei assorbe la differenza o annulla l’ordine, oppure perde fiducia nel portale e chiama l’ufficio vendite. Più il catalogo è grande e più classi di prezzo gestisce, più spesso succede.

Una pipeline di dati elimina la causa invece del sintomo. L’ERP resta il sistema di riferimento, un job pianificato scrive le modifiche in BSS B2B Solution e la vetrina segue. I negozi reali vogliono questa flessibilità. Alpha Coffee, una torrefazione, segnala che con l’accesso API può mantenere Shopify come livello centrale del commercio ed estendere il collegamento a piattaforme ERP, CRM o finanziarie, e DermaplanePro riferisce una riduzione del lavoro manuale grazie alle connessioni pubbliche con sistemi esterni. Veda i casi Alpha Coffee e DermaplanePro.

Come configurarla con BSS B2B Solution

Questa sezione descrive l’integrazione dal lato del negoziante. Il Suo sviluppatore ha bisogno della guida alla Public API per endpoint e payload.

Passaggio 1: verifichi il piano

La Public API fa parte del piano Platinum. Un negozio può avere una sola chiave API alla volta, e il piano sblocca anche le Price List, che molte integrazioni con ERP usano per i prezzi specifici per cliente. Verifichi il piano prima di definire l’ambito di qualsiasi lavoro di integrazione.

Passaggio 2: generi la chiave API

Nell’app apra Integrations, trovi la scheda Public API e scelga Get API key. La chiave viene mostrata una sola volta, quindi la copi o la scarichi in quel momento e la conservi in un gestore di password o in una variabile d’ambiente del server. Se viene compromessa, la elimini nella stessa scheda: così si interrompe ogni client che la usa, poi ne genera una nuova.

Passaggio 3: autentichi la prima richiesta

Gli endpoint della versione 1 accettano il dominio `myshopify.com` del negozio e la chiave, sia come `accessKey` nel corpo della richiesta sia nell’header `x-bss-b2b-api-key`. L’endpoint volume pricing della versione 2 usa l’header `x-api-key`. Il token Bearer non è supportato e restituisce 401, quindi non costruisca il client attorno all’header `Authorization`.

Passaggio 4: scriva le regole dai dati dell’ERP

Associ ogni classe di prezzo dell’ERP a un target della regola, per esempio un tag cliente, e richiami il gruppo di endpoint del modulo che usa. L’API gestisce le regole Custom Pricing, Price List e Volume Pricing, le regole dei codici sconto, i record del modulo di registrazione e le regole sui limiti d’ordine, con operazioni di creazione, aggiornamento, eliminazione e operazioni in blocco dove l’endpoint lo consente. Gli endpoint di cliente e prodotto sono ricerche in sola lettura che aiutano a costruire i payload delle regole, per esempio trovare clienti per tag o elencare prodotti e collezioni. Le richieste vengono elaborate una per volta, quindi il client deve metterle in coda.

Passaggio 5: carichi una volta, poi verifichi

Dopo un blocco di modifiche, richiami l’endpoint di upload del modulo così che tutte le regole attive vengano scritte nel tema attivo. Gli endpoint di upload consentono una richiesta per modulo ogni cinque minuti, quindi carichi una volta alla fine di un’esecuzione di sincronizzazione, non dopo ogni riga. Una richiesta oltre il limite restituisce `429`, e vengono caricate solo le regole attive. Se le regole superano la capacità dei metafield, l’API salva ciò che entra e restituisce un report `partial_success` con HTTP 200, quindi legga il corpo della risposta e non solo il codice di stato. Poi verifichi il risultato nella scheda Logs and usage sotto Advanced Settings > Public API, che elenca le richieste recenti con orario, metodo, percorso e stato, e mostra la richiesta e la risposta complete quando qualcosa fallisce. L’API può anche restituire il prezzo che un determinato cliente ottiene per determinati prodotti, utile per confrontare l’app con l’ERP.

Esempio: un distributore con tre classi di prezzo

Questo esempio usa numeri illustrativi, non risultati di un negozio reale. Un distributore tiene tre classi di prezzo nel proprio ERP: Retail Partner, Trade e Key Account. In BSS B2B Solution ogni classe è una regola Price List che punta a un tag cliente. Un job notturno esporta le righe di prezzo modificate, le raggruppa per classe e richiama l’endpoint di salvataggio in blocco per ogni Price List. Quando tutte e tre finiscono, il job richiama una volta l’endpoint di upload della Price List.

Un lunedì l’ERP mostra 3.200 prezzi modificati. Invece di farle reinserire a un analista, il job parte alle 02:00, carica una volta e controlla nella scheda Logs and usage eventuali richieste fallite. Al mattino un acquirente Trade che accede vede i prezzi del lunedì nelle pagine di prodotto e di collezione. Una richiesta fallita lascia una voce nel log con il suo stato e il corpo, e il job la ripete dopo una breve attesa.

Funziona bene con

L’API è un canale di input per il motore dei prezzi. Le altre pagine descrivono cosa succede a quelle regole una volta create:

• CSV invece del codice: importare prezzi all’ingrosso da CSV copre la finestra di import per cataloghi più piccoli.
• Price list per gruppo di acquirenti: Price List B2B per gruppo di acquirenti mostra il tipo di regola che scrive la maggior parte delle sincronizzazioni con l’ERP.
• Quantity break: prezzi a scaglioni e quantity break spiega le regole Volume Pricing che l’API può gestire.
• Ordine delle regole: quale regola B2B prevale spiega la priorità, così una regola sincronizzata non entra in conflitto con una creata a mano.

L’hub dei prezzi all’ingrosso raccoglie le guide sui prezzi. Voci utili del glossario sono price list, prezzo all’ingrosso e tag cliente.

Limiti ed errori comuni

• Non esiste un endpoint per gli ordini. L’API gestisce le regole di prezzo e di sconto, i record di registrazione e le regole sui limiti d’ordine, oltre alle ricerche in sola lettura di clienti, prodotti e collezioni. La sincronizzazione degli ordini resta nel connettore ERP per Shopify, e questa API serve per prezzi e gruppi di clienti.
• Una chiave per negozio. Eliminare la chiave interrompe ogni client che la usa, quindi la ruoti con un piano e aggiorni subito l’integrazione.
• L’upload ha un limite di frequenza. Gli endpoint di upload consentono una richiesta per modulo ogni cinque minuti. L’endpoint volume pricing della versione 2 consente 60 richieste ogni 60 secondi per ogni negozio.
• I dati dei prezzi hanno dei limiti. Le regole sono salvate nei metafield di Shopify con al massimo 10 chiavi e 2.000.000 di caratteri per chiave. Il contenuto oltre i limiti viene saltato e segnalato come `partial_success`, quindi elimini le regole inattive o divida un set di regole molto grande prima di caricare di nuovo.
• I nuovi tentativi richiedono una pausa. Le richieste vengono elaborate una per volta, e dopo un errore del server la guida indica di attendere fino a tre minuti prima di riprovare.
• L’API non sostituisce la progettazione delle regole. Targeting, priorità ed esclusioni seguono le stesse regole delle regole create a mano, quindi provi prima una regola nell’admin.
• L’API alimenta una vetrina su tema. I prezzi appaiono tramite l’app embed di BSS B2B Solution nel Suo tema Shopify, quindi verifichi che l’embed sia attivo dopo ogni modifica al tema.

Checklist di configurazione

• Verifichi che il negozio sia sul piano Platinum.
• Decida il sistema di riferimento per ogni classe di prezzo e a quale tag cliente corrisponde ogni classe.
• Generi la chiave API e la conservi in un gestore di password o in una variabile d’ambiente.
• Costruisca il client con `accessKey` o con l’header `x-bss-b2b-api-key`, e metta le richieste in coda.
• Provi una regola dall’inizio alla fine in un negozio di sviluppo, poi la controlli nell’admin.
• Preveda una chiamata di upload per modulo alla fine di ogni esecuzione di sincronizzazione.
• Aggiunga avvisi per `429` ed errori del server, e legga la scheda Logs and usage dopo le prime esecuzioni.
• Tenga la sincronizzazione degli ordini in un connettore separato.

Piani e requisiti

La Public API richiede il piano Platinum di BSS B2B Solution, una chiave per negozio e l’app embed sul Suo tema. Gli altri piani e la prova gratuita di 14 giorni sui piani a pagamento sono nella pagina prezzi BSS B2B. I payload esatti sono nella guida alla Public API, nella guida all’API di upload e nella guida all’API Custom Pricing. Installi BSS B2B Solution dallo Shopify App Store e chieda al Suo sviluppatore di iniziare con una sola Price List.