Connect a warehouse

Hand orders to your warehouse system and get back shipments, stock and returns, with a T-Data or FFW compatible interface.

How it works

Nucleo Commerce hands orders to your warehouse management system (WMS) and receives back acknowledgements, shipments, stock levels and return outcomes. Nucleo offers two compatible interfaces, so a WMS that already integrates one of these protocols only changes the base URL and the credentials:

Interface	Protocol	Format	Reference
T-Data	T-Data "Integration MoR/WMS" `/V1`	JSON	WMS T-Data
FFW	FFW / Smart Shop web services	XML (ISO-8859-1)	WMS FFW

In both cases the warehouse is always the caller: Nucleo never calls the WMS. The WMS polls for new orders and returns, and pushes everything else.

Before you start

The merchant does these steps in Nucleo; you need their output.

In Nucleo, go to Commerce > Orders > Channels and logistics and add a warehouse connection of type T-Data or FFW.
Copy the credentials shown on screen. They are shown once: endpoint, username and password, plus an API key for T-Data. Share them with the warehouse over a channel separate from the documentation.
Link the warehouse location(s) to the connection and set the warehouse codes the WMS uses (IdWarehouse for T-Data, IDMagazzino for FFW).
Check that every destination the warehouse serves has a carrier rule: an order without a carrier stays on hold and never reaches the WMS.
Optionally restrict the connection to the warehouse's static outbound IPs (IP allowlist).
Set the connection status to Active. A new connection is a draft and answers service not active until then.

Base URL: https://api-commerce.nucleoplatform.com (or the endpoint shown with the credentials). Paths are exactly those of the protocol.

Credentials on every call: send them preemptively. A 401 carries no WWW-Authenticate challenge.

Rotating credentials: Rotate credentials on the connection page invalidates the old ones immediately.

Warehouse connections are part of Nucleo Orders. If the menu is not visible, ask Nucleo to enable Orders for the company.

T-Data flow

Authenticate with X-Api-Key: <key> (recommended), Authorization: Bearer <key>, or HTTP Basic.

Poll new orders: GET /V1/Orders/New every 1 to 5 minutes. You get the paid, released orders allocated to your warehouse, only your lines, at most 500 per call, oldest first.
Acknowledge each order: POST /V1/Orders/Acknowledge (object or array).
- Success: true with your WmsOrderNumber: the order is yours and leaves Orders/New.
- Success: false with an ErrorcCode: the merchant fixes the order and releases it again; it comes back in Orders/New.
- Until you acknowledge, the order is returned at every call. A lost response is never a lost order.
Keep stock flowing: PUT /V1/Stock/Update whenever stock changes, with absolute levels per item and classification. Your levels must already exclude the orders you acknowledged; Nucleo subtracts the ones you have not acknowledged yet. Items you do not send are not zeroed.
Report the pick: POST /V1/Orders/Processed with picked quantities, lots, serials and parcels. A short pick marks the missing quantity as unfulfillable and alerts the merchant.
Report the shipment: POST /V1/Orders/Shipped with CourierCode and CourierWaybill. Nucleo creates the fulfilment on the sales channel and the customer gets the tracking.
Cannot fulfil: POST /V1/Orders/Canceled on an acknowledged order the warehouse cannot ship. The merchant cancels and refunds it.
Poll expected returns: GET /V1/Returns/New, then POST /V1/Returns/Acknowledge.
Report the inspection: POST /V1/Return/Update with ExternalReference1 = the OmsReturnNumber, quantities and Classification per line. All expected items Sellable = compliant, refund follows; anything else goes to customer service. A parcel nobody announced still goes through Return/Update: Nucleo opens an unannounced return.
Expected return that will not arrive: POST /V1/Returns/Canceled.

Optional services are off by default and answer 404 until the merchant enables them: courier labels generated by Nucleo (/V1/Labels/Get, /V1/Labels/Add), order documents (/V1/Documents/Get), WMS item registry (/V1/Catalogue).

Cancellations seen from the warehouse

Cancelled on the sales channel before you download it: you never see it.
Cancelled after download but before acknowledgement: it disappears from Orders/New. If you acknowledge it anyway, the merchant is alerted and contacts you.
Cancelled after acknowledgement: the T-Data contract has no cancel call towards the WMS. The merchant contacts you through the procedure you agreed. If you ship it meanwhile, Nucleo records the shipment and alerts the merchant.

FFW flow

Authenticate with HTTP Basic.

Poll orders: GET /api/admin/ws/ws_orders?documenti_stati_ID[]=17&documenti_stati_ID[]=2&documenti_stati_ID[]=31&last_upd=YYYYMMDDHHMMSS every 1 to 5 minutes. As next last_upd, use either the last ord_DataUltimaModifica you received or the time of your previous call: both are safe. If you receive a full page (500 orders), call again at once.
Take over: there is no acknowledgement call. An order returned with state 17 is taken over by the warehouse, as in FFW.
Follow changes: the same call returns again
- with state 17 an order the merchant changed (address, notes, cancelled lines): update it by ord_ID;
- with state 2 an order cancelled after you downloaded it: stop picking it;
- with state 31 an order you reported as shipped.
Keep stock flowing: POST /api/aggiorna-giacenze-impegni with absolute levels per EAN and warehouse code, at most 500 <articolo> per call (above the limit nothing is processed). Add ?full=1 for a complete snapshot. Items you do not send are not zeroed.
Report the shipment: POST /api/admin/spedizioni/notify-spedizione with carrier, tracking per parcel and shipped items (Nucleo extension; XML, or JSON with the T-Data Orders/Shipped fields). Nucleo creates the fulfilment on the sales channel.
Poll returns: GET /api/admin/resi/list?last_upd=dd/mm/yyyy hh:mm:ss. The filter is >=, so a return can come back twice: update it by reso_ID.
Report what arrived: POST /api/admin/resi/notify-reso with items and quantities received. Exactly as expected = confirmed (state 2); otherwise anomalous (state 3) and handled by customer service.
Documents (when needed): GET /api/admin/documenti/get-order-docs?documenti_testa_ID=<ord_ID>&type=sell returns base64 PDFs.

When the merchant has Nucleo generate courier labels (off by default), replace step 5 with: POST get-etichette-corriere (one PDF label per parcel) → optionally POST del-etichette-corriere to void → POST ws-close-bordero at the end of the day, which confirms the shipments and marks the orders shipped.

Cancellations seen from the warehouse

Cancelled before you download it: you never see it, with any state.
Cancelled after download: it comes back with state 2. Nucleo considers the cancellation done once you have read it.

Rules for both interfaces

Topic	Rule
Polling cadence	Every 1 to 5 minutes for orders and returns. If the WMS stays silent for more than 30 minutes while orders are waiting, the connection turns to Error and the merchant is alerted; the next successful call clears it.
Rate limit	600 calls per minute per connection, all endpoints together. 30 failed logins in 5 minutes block the caller IP for the rest of the window. No `Retry-After` header: back off at least 60 seconds on `429`.
Retries	Every write can be retried after a timeout: repeated acknowledgements, shipments with the same tracking, stock levels and return outcomes have no double effect.
All or nothing	Calls carrying several items are validated first; one invalid item rejects the whole call.
Item code	The variant barcode (EAN), unless the merchant agreed another code with you.
Holds	Orders on hold (payment pending, hold tag, fraud risk, manual hold, no carrier rule, item without code) never reach the warehouse.
Paused connection	The merchant can pause the connection. Calls then answer `service paused` and nothing is read or written: retry later.
Support	Every call is logged in full. Report the time, the endpoint, the order or return number and, if present, the `ref` of an `Internal error (ref …)` response.

Go-live checklist

Run the scenarios in order against a test merchant with test orders before switching production. Use a WMS test environment if you have one; otherwise make sure test orders are never picked or shipped physically.

T-Data

#	Scenario	Warehouse does	Expected in Nucleo
1	Credentials	`GET /V1/Orders/New` without, then with credentials	`401` without; `200` with an empty or full `Content`
2	New orders	Read `Orders/New` after the merchant creates 4 test orders (domestic standard, foreign with company and notes, express, multi-line with quantity 2)	All 4 returned with the documented fields; status Exported
3	Re-read	Read again without acknowledging	Same 4 orders, no duplicates
4	Acknowledge	`Acknowledge` 3 orders with `Success: true` and `WmsOrderNumber`	Status Acknowledged, WMS number visible; only the 4th remains in `Orders/New`
5	Reject	`Acknowledge` the 4th with `Success: false` and a code	Rejected by warehouse, merchant alerted; after the fix it reappears and you acknowledge it
6	Full pick	`Orders/Processed` with all quantities and 2 parcels	Processed, parcels with weight and size
7	Shipment	`Orders/Shipped` with courier, waybill, return waybill; send it twice	Shipped, fulfilment with tracking on the sales channel; no second shipment
8	Short pick	On the multi-line order, `Processed` with 1 of 2, then `Shipped`	1 fulfilled, 1 unfulfillable, merchant alerted; channel fulfilment of 1 item
9	Cannot fulfil	`Orders/Canceled` on an acknowledged order	Cancelled by warehouse, merchant alerted
10	Channel cancellations	Merchant cancels one order before your read, one between read and acknowledge, one after acknowledge	First never seen; second leaves `Orders/New`; third follows the agreed manual procedure
11	Stock, delta	`Stock/Update` with a few items, `Sellable` and `Unsellable`	Levels stored per classification; published availability net of unacknowledged orders
12	Stock, edge cases	Full snapshot; unknown EAN; older `EventDateTime`; `StockLevel: 0`	Snapshot applied; unknown EAN skipped with an alert; old value ignored; item at zero
13	Expected return	`Returns/New`, then `Returns/Acknowledge`	Return listed with items; then Awaited at warehouse
14	Compliant return	`Return/Update` with the expected quantities, `Sellable`	Compliant, refund forwarded
15	Non-compliant return	`Return/Update` with an `Unsellable` line and a `ReturnCode`, or a different quantity	Not compliant, customer service alerted, code stored
16	Unannounced return	`Return/Update` with an unknown `ExternalReference1`, sent twice	One unannounced return, merchant alerted
17	Cancelled return	`Returns/Canceled` on an expected return; then a `Return/Update` on it	Cancelled; goods recorded and merchant alerted
18	Robustness	Malformed JSON; an Acknowledge array with one unknown order; lowercase path; `Stock/Update` via `POST`	`400` with a message and nothing applied; path and method accepted
19	Optional services	`Labels/Get`, `Documents/Get`, `Catalogue`	`404` with message, unless the merchant enabled them
20	Volume	Read and acknowledge at least 50 consecutive orders	No order lost or duplicated

FFW

#	Scenario	Warehouse does	Expected in Nucleo
1	Credentials	`ws_orders` without, then with credentials and `last_upd` one hour ago	`401` with the `KO` envelope; then `<ordini/>` or orders
2	New orders	`ws_orders` with state 17 and `last_upd`, after the merchant creates 4 test orders (domestic, EU, with company and notes, multi-line)	All 4 with state 17; taken over in Nucleo
3	Incremental read	Call again with `last_upd` = last `ord_DataUltimaModifica`, then with the time of the previous call	Nothing repeated or lost; a new order appears exactly once
4	Filters and errors	`data_dal`/`data_al`; a range over one month; no date; `documenti_tipo_ID=3`	Results and `KO` messages as documented; empty list for type 3
5	Change after read	Merchant changes the address of a downloaded order; you re-read	Order back with state 17 and the new address; WMS updates it by `ord_ID`
6	Cancel after read	Merchant cancels a downloaded order; you read states 17 and 2	Order back with state 2; then Cancelled in Nucleo
7	Cancel before read	Merchant cancels a new order before your read	Never returned
8	Shipment	`notify-spedizione` with 2 parcels and tracking; send it twice	Shipped, channel fulfilment with tracking, order back with state 31; no second shipment
9	Partial shipment	`notify-spedizione` with only one of two items	Only that item fulfilled; the rest stays open for customer service
10	Stock	Same EAN on two warehouse codes; an unknown EAN; an item at 0	`OK`; quantities summed; unknown EAN skipped with an alert; availability published net of unread orders
11	Stock limits	More than 500 items; malformed XML; `?full=1`	`KO` with nothing processed; `KO`; `OK` with full republication
12	Read returns	Merchant creates 2 returns; `resi/list` with `data_dal`, then `last_upd`, then `resi_stati_ID=1&limit=10`	Returns with state 1, reason and items
13	Compliant return	`notify-reso` with the expected items	Confirmed; state 2 in `resi/list`
14	Anomalous return	`notify-reso` with a different quantity or an unexpected item	Anomalous, customer service alerted; state 3
15	All or nothing	`notify-reso` with one valid and one unknown return	`KO`, nothing updated
16	Cancelled return	Merchant cancels a return; you send `notify-reso` anyway	`OK`, goods recorded, merchant alerted; state 4
17	Documents	Documents call with `type=sell`	`ACK OK` with a readable PDF, or `ERROR` without documents
18	Labels and bordereau	`get-etichette-corriere`, `ws-close-bordero` (also as `//api/…`)	`404` with their envelopes, unless the merchant enabled Nucleo labels
19	Encoding	Order with accented and non-Latin names (`Łukasz`, `Kraków`)	Accented letters readable in ISO-8859-1, others as numeric entities
20	Volume	At least 50 consecutive orders and a 500-item stock call	No order lost or duplicated

Ready for production when every scenario passes, the code tables you use (state, reason, country, carrier, rejection and return codes) are loaded on the connection by the merchant and re-tested, and the production connection has new credentials of its own.