Create a JTL app

Balta Labs connects to JTL Fulfillment Network (JTL FFN) through an app that you register at JTL yourself. JTL calls it an OAuth client. The app gives you a client ID and a client secret. You enter both in Balta Labs and then allow access at JTL, as described in Connect JTL to the hub.

JTL describes these steps under Getting started in its Merchant API documentation. JTL’s screens can change. If a label differs from this guide, follow JTL’s current wording.

Before you begin

• A JTL Customer Center account. You create the app there.
• A JTL account with the Merchant role in JTL FFN. You sign in with this account when you connect. JTL only lets merchant users use the API that Balta Labs needs.
• One sign-in to the FFN portal with that account. Use fulfillment.jtl-software.com for production or fulfillment-sandbox.jtl-software.com for the sandbox. JTL creates the API user at the first sign-in. Until then, JTL answers not found, and Balta Labs reports that the JTL account is not ready yet.
• The Connections permission in your Balta Labs workspace. You need it to open the connection dialog and copy the callback URL.

Copy the callback URL from Balta Labs

After you allow access, JTL sends you back to Balta Labs through the app’s callback URL. It must be exactly the address that Balta Labs shows.

1. In Balta Labs, open Settings → Connections, select Add account, and choose JTL FFN. You can also select Add provider under Fulfillment & notifications. The Connect JTL Fulfillment Network dialog opens.
2. Under Before you continue, find the callback URL and select Copy. It looks like https://api.example.com/connections/oauth/jtl_ffn/callback. Always use the address from your dialog, not this example.
3. Keep the dialog open while you create the app. It also lists the scopes to tick and links to this guide.

Do not type the address by hand. A different character, http instead of https, an extra slash at the end, or a space causes a callback mismatch. If the dialog says JTL connections are not available on this server yet, Balta Labs cannot offer a callback URL. Contact Balta Labs support.

Create the app at JTL

1. Open kundencenter.jtl-software.de/oauth and sign in. The dialog’s Open the JTL Customer Center link leads to the same page. The page is not linked from the Customer Center menu, so open this address directly.
2. Create a new OAuth client.
3. If JTL asks for a name, use one you will recognize later, such as Balta Labs.
4. Tick the scopes ffn.merchant.read and ffn.merchant.write. JTL may offer scopes through a template; choose one that includes both. Fulfiller scopes alone are not enough.
5. Paste the callback URL from Balta Labs as the app’s redirect URI. JTL may also call this field callback URI.
6. Save the client.
7. Copy the client ID and the client secret that JTL shows for the client.

Scope	JTL’s description	What Balta Labs uses it for
ffn.merchant.read	Full read access to the merchant API	Reading your account, warehouses, shipping methods, products, stock, and shipment updates
ffn.merchant.write	Full write access to the merchant API	Creating shipments, products, and inbound deliveries, only for workflows you set to active

Production and sandbox

JTL runs a production system and a separate sandbox for testing. According to JTL, one OAuth client works for both, and the callback URL is the same. What differs is the account you sign in with and the portal where it must have signed in once.

	Production	Sandbox
FFN portal for the first sign-in	fulfillment.jtl-software.com	fulfillment-sandbox.jtl-software.com
JTL account	Your live merchant account	A sandbox account
Option under Environment in the dialog	Production	Sandbox
Data	Real shipments and stock	Test data, separate from production

Each option in the dialog also shows its portal address. A connection stays in the environment it was created in. To move from the sandbox to production, add a new connection with Production selected. You can also keep a separate JTL app for testing.

Enter the client ID and secret securely

• Enter the client ID and client secret only in the Client ID and Client secret fields of the Connect JTL Fulfillment Network dialog. Balta Labs stores the secret encrypted and never shows it again.
• Never send the client secret by email, chat, or support ticket, and do not paste it into shared documents. Support only needs the client ID.
• When you reconnect an account, you can leave both fields blank to keep the stored app credentials.
• If the secret may have been exposed, replace it at JTL. If JTL does not let you renew it, create a new app. Then reconnect the account with the new values.

Next, connect JTL to the hub.