Crea un'app JTL

Nota: le etichette in grassetto corrispondono all’interfaccia in italiano. Se l’app è impostata in inglese, compaiono in inglese.

Balta Labs si collega a JTL Fulfillment Network (JTL FFN) tramite un’app registrata da te presso JTL. JTL la chiama client OAuth. L’app ti fornisce un client ID e un client secret. Inserisci entrambi in Balta Labs e poi consenti l’accesso su JTL, come descritto in Collega JTL all’hub.

JTL descrive questi passaggi nella sezione Getting started della sua documentazione della Merchant API. Le schermate di JTL possono cambiare. Se un’etichetta è diversa da quella di questa guida, segui la dicitura attuale di JTL.

Prima di iniziare

• Un account del JTL Customer Center. È lì che crei l’app.
• Un account JTL con il ruolo Merchant in JTL FFN. Accedi con questo account al momento della connessione. JTL consente di usare l’API necessaria a Balta Labs solo agli utenti con ruolo Merchant.
• Un primo accesso al portale FFN con quell’account. Usa fulfillment.jtl-software.com per la produzione o fulfillment-sandbox.jtl-software.com per la sandbox. JTL crea l’utente API al primo accesso. Fino ad allora JTL risponde not found e Balta Labs segnala che l’account JTL non è ancora pronto.
• Il permesso Connessioni nel tuo workspace Balta Labs. Ti serve per aprire la finestra di connessione e copiare l’URL di callback.

Copia l’URL di callback da Balta Labs

Dopo che hai consentito l’accesso, JTL ti riporta a Balta Labs tramite l’URL di callback dell’app. Questo URL deve corrispondere esattamente all’indirizzo mostrato da Balta Labs.

1. In Balta Labs, apri Impostazioni → Connessioni, seleziona Add account e scegli JTL FFN. Puoi anche selezionare Aggiungi fornitore sotto Fornitori logistici. Si apre la finestra di dialogo Collega JTL Fulfillment Network.
2. Nella sezione Prima di continuare, trova l’URL di callback e seleziona Copia. Ha un formato simile a https://api.example.com/connections/oauth/jtl_ffn/callback. Usa sempre l’indirizzo della tua finestra, non questo esempio.
3. Lascia aperta la finestra mentre crei l’app. La finestra elenca anche gli scope da selezionare e rimanda a questa guida.

Non digitare l’indirizzo a mano. Un carattere diverso, http al posto di https, una barra in più alla fine o uno spazio causano una mancata corrispondenza dell’URL di callback. Se la finestra indica Le connessioni JTL non sono ancora disponibili su questo server, Balta Labs non può fornire un URL di callback. Contatta il supporto Balta Labs.

Crea l’app su JTL

1. Apri kundencenter.jtl-software.de/oauth e accedi. Il link Apri il JTL Customer Center della finestra porta alla stessa pagina. La pagina non è raggiungibile dal menu del Customer Center, quindi apri direttamente questo indirizzo.
2. Crea un nuovo client OAuth.
3. Se JTL chiede un nome, usane uno che riconoscerai in seguito, per esempio Balta Labs.
4. Seleziona gli scope ffn.merchant.read e ffn.merchant.write. JTL può proporre gli scope tramite un modello: scegline uno che li includa entrambi. Gli scope per fulfiller da soli non bastano.
5. Incolla l’URL di callback di Balta Labs come redirect URI dell’app. JTL può chiamare questo campo anche callback URI.
6. Salva il client.
7. Copia il client ID e il client secret che JTL mostra per il client.

Scope	Descrizione di JTL	A cosa serve in Balta Labs
ffn.merchant.read	Accesso completo in lettura alla Merchant API	Lettura di account, magazzini, metodi di spedizione, prodotti, scorte e aggiornamenti delle spedizioni
ffn.merchant.write	Accesso completo in scrittura alla Merchant API	Creazione di spedizioni, prodotti e ricevimenti merce, solo per i flussi di lavoro attivi

Produzione e sandbox

JTL gestisce un sistema di produzione e una sandbox separata per i test. Secondo JTL, un solo client OAuth funziona per entrambi e l’URL di callback è lo stesso. Cambiano l’account con cui accedi e il portale in cui quell’account deve aver effettuato almeno un accesso.

	Produzione	Sandbox
Portale FFN per il primo accesso	fulfillment.jtl-software.com	fulfillment-sandbox.jtl-software.com
Account JTL	Il tuo account commerciante reale	Un account sandbox
Opzione in Ambiente nella finestra	Produzione	Sandbox
Dati	Spedizioni e scorte reali	Dati di test, separati dalla produzione

Ogni opzione della finestra mostra anche l’indirizzo del relativo portale. Una connessione resta nell’ambiente in cui è stata creata. Per passare dalla sandbox alla produzione, aggiungi una nuova connessione selezionando Produzione. Puoi anche mantenere un’app JTL separata per i test.

Inserisci client ID e secret in sicurezza

• Inserisci client ID e client secret solo nei campi Client ID e Client secret della finestra Collega JTL Fulfillment Network. Balta Labs salva il secret cifrato e non lo mostra mai più.
• Non inviare mai il client secret via email, chat o ticket di supporto e non incollarlo in documenti condivisi. Al supporto basta il client ID.
• Quando ricolleghi un account, puoi lasciare vuoti entrambi i campi per mantenere le credenziali dell’app salvate.
• Se il secret potrebbe essere stato esposto, sostituiscilo su JTL. Se JTL non ti permette di rinnovarlo, crea una nuova app. Poi ricollega l’account con i nuovi valori.

Come passo successivo, collega JTL all’hub.