/ Developers
Contents
CommerceBetaVersion 2026-10XML

WMS FFW API

FFW / Smart Shop compatible XML web services that a warehouse management system calls to fulfil Nucleo Commerce orders and returns.

The WMS FFW facade lets a warehouse or 3PL management system (WMS) fulfil the orders of a Nucleo Commerce merchant with the FFW / Smart Shop web services: same paths, same query parameters, same XML envelopes (doc_ordini, doc_giacenze, doc_resi, doc_gestione_etichette_corrieri, doc_recupero_documenti). A WMS that already speaks FFW only changes the base URL and the credentials.

The warehouse is always the caller. Nucleo never calls the WMS: the WMS polls for orders and returns and pushes stock, shipments and return outcomes.

Authentication. HTTP Basic on every call, with the username and password of one warehouse connection. The credentials alone identify the merchant and the warehouse; there is no store identifier in the path.

Integration flow

  1. Download orders – GET /api/admin/ws/ws_orders?last_upd=… every 1–5 minutes, with state codes 17 (to fulfil), 2 (cancelled) and 31 (shipped). There is no explicit acknowledgement: an order returned with state 17 is taken over by the warehouse, as in FFW.
  2. Follow changes – the same call returns again an order the merchant changed (address, notes, cancelled lines) with state 17 and fresh data, and an order cancelled after you downloaded it with state 2: stop picking it.
  3. Stock – POST /api/aggiorna-giacenze-impegni with absolute levels, at most 500 items per call.
  4. Shipment – POST /api/admin/spedizioni/notify-spedizione with carrier, tracking and parcels (Nucleo extension, not part of the original FFW services). Nucleo creates the fulfilment on the sales channel and the order comes back in ws_orders with state 31. When the merchant has Nucleo generate courier labels instead, use get-etichette-corriere → (del-etichette-corriere) → ws-close-bordero; these are switched off by default.
  5. Returns – GET /api/admin/resi/list?last_upd=… for expected returns, then POST /api/admin/resi/notify-reso with the items actually received.
  6. Documents – GET /api/admin/documenti/get-order-docs for invoices and receipts of an order, as base64 PDF.

Conventions

  • XML out: <?xml version="1.0" encoding="iso-8859-1"?>, HTTP header Content-Type: text/xml; charset=iso-8859-1, pretty-printed. Characters outside ISO-8859-1 are written as numeric entities (&#321; for Ł); free text is in CDATA.
  • XML in: every POST accepts the XML either as the form field xml (application/x-www-form-urlencoded or multipart) or as the raw request body, in ISO-8859-1 or UTF-8. Documents containing <!DOCTYPE> or entity declarations, or another encoding, are rejected with the endpoint's KO envelope.
  • Paths are exactly FFW's, case-sensitive. The leading double slash written in the FFW spec (//api/admin/spedizioni/ws-close-bordero) is accepted on every path.
  • Dates are Italian local time (Europe/Rome), in FFW's per-service formats: ws_orders data_dal/data_al dd/mm/yyyy HH:MM:SS; ws_orders last_upd and ord_DataUltimaModifica YYYYMMDDHHMMSS; resi/list data_dal/data_al yyyy-mm-dd; resi/list last_upd dd/mm/yyyy hh:mm:ss; ord_data, reso_data dd/mm/yyyy; ord_datetime, reso_datetime, resi_data_ultima_modifica, data_spedizione yyyy-mm-dd HH:MM:SS. URL-encode spaces and slashes in query strings.
  • Amounts: dot decimal, two digits (147.54). Line prices are net of VAT, importo_totale_riga is gross.
  • Item code: barcode and IDArtCod are the variant barcode (EAN).
  • Keys: ord_ID and reso_ID are numeric ids assigned by Nucleo, progressive per merchant (a merchant migrating from FFW continues after the last FFW id). ord_num_doc is the channel order name (#1042).
  • Codes (documenti_stati_ID, resi_stati_ID, resi_causali_ID, nazioni_ID) are the FFW defaults listed per operation; the merchant can remap them per connection.
  • Errors keep FFW's envelopes, different per service, and validation errors are answered with HTTP 200 and a KO envelope, as in FFW. Always read ack/ACK/result, not only the HTTP status.

Errors common to every service

HTTPMessage in the endpoint envelopeWhen
401Unauthorizedmissing or wrong credentials (no WWW-Authenticate header is sent)
403Forbiddencaller IP not in the connection allowlist (only when the merchant set one)
429Too many requestsrate limit exceeded
200service paused / service not activeconnection paused by the merchant, or still a draft: KO, nothing read or written, retry later
500Internal error (ref <uuid>)unexpected error; quote the ref to support

Limits and monitoring

  • 600 calls per minute per connection (all services together; the merchant can change it). No Retry-After or X-RateLimit-* headers are sent: on 429 back off for at least 60 seconds.
  • 30 failed authentications within 5 minutes from one IP block that IP for the rest of the window, valid credentials included.
  • Every call is logged in full (request and response) before Nucleo answers, so support can find any call by time, service or ord_ID.
  • If the WMS stays silent for more than 30 minutes while orders are waiting, Nucleo flags the connection as Error and alerts the merchant; the next successful call clears it.

Credentials

The merchant creates a warehouse connection of type FFW in Commerce › Orders › Channels and logistics. Nucleo shows the endpoint, username and password once; the merchant shares them with you over a separate channel. Rotate credentials on the same page invalidates the old ones immediately. A new connection starts as a draft and answers service not active until the merchant activates it.

Authentication

  • basicAuthHTTP basic

    Username and password of the warehouse connection, issued once by the merchant in Commerce › Orders › Channels and logistics. Send them preemptively on every call.

Base URL
https://{host}Production. Use the endpoint shown when the credentials were issued.
Who calls it
Warehouses
Endpoints
10
OpenAPI 3.1 specification
wms-ffw.yaml
{host} — Commerce API host. If the merchant sets a dedicated host on the connection, the connection answers only on that host; paths do not change. (examples use api-commerce.nucleoplatform.com; full URL https://api-commerce.nucleoplatform.com)

Orders

Download orders (implicit acknowledgement) and order documents.

get/api/admin/ws/ws_orders

Download orders

Orders allocated to this warehouse, in FFW details=medium format. At least one of last_upd, data_dal, data_al is required.

States (documenti_stati_ID, FFW defaults): 17 confirmed, to fulfil (Nucleo states ready, exported, label created); 2 cancelled; 31 shipped (shipped, delivered). Without a filter all three are returned. documenti_tipo_ID 13 (web order) is the only type served here; any other type returns an empty <ordini/>.

Implicit acknowledgement: an order returned with state 17 is taken over by the warehouse (moves to Exported). Until then Nucleo keeps subtracting it from your stock before publishing availability.

Incremental reading with last_upd (> filter on the last change): use as next last_upd either the last ord_DataUltimaModifica received or the time of your previous call. Nucleo stamps every change a few seconds in the future and returns only changes already in the past, so no change ever falls before a last_upd you already used. last_upd cannot be older than one month.

Date range (data_dal/data_al, on the order date): at most one month; without data_dal it is one month before data_al; without data_al it is now. Both filters can be combined.

  • At most 500 orders per call (merchant-configurable), ordered by last change then ord_ID; the limit never splits a second, so a page can be slightly larger. If you receive a full page, call again at once with last_upd = the last ord_DataUltimaModifica.
  • An order the merchant changes after you read it (address, notes, cancelled lines) comes back with state 17 and the new data: update it in the WMS by ord_ID.
  • Cancelled before you read it: never returned. Cancelled after: returned with state 2; Nucleo considers the cancellation done once you have read it with state 2.
  • Only orders allocated to this warehouse's locations, and for split orders only your lines.
  • Re-reading the same window returns the same orders without further effects.
  • The tag list of details=medium follows the FFW naming; details is accepted and ignored (always medium).

Errors: validation errors answer HTTP 200 with <result><ack>KO</ack><error_message>.

Rate limit: shared 600 calls/minute per connection.

GET https://api-commerce.nucleoplatform.com/api/admin/ws/ws_orders
Authentication: HTTP Basic
Rate limit: 600 requests per 1m, per key

Query parameters

  • last_updstring

    Orders changed strictly after this instant, YYYYMMDDHHMMSS, Italian time, not older than one month.

    pattern ^\d{14}$
    Example: 20261005100000
  • data_dalstring

    Order date from, dd/mm/yyyy HH:MM:SS, Italian time.

    Example: 01/10/2026 00:00:00
  • data_alstring

    Order date to, dd/mm/yyyy HH:MM:SS, Italian time. At most one month after data_dal.

    Example: 05/10/2026 23:59:59
  • documenti_stati_IDstring

    A single state code (17, 2 or 31). For several, use documenti_stati_ID[].

    One of17231
    Example: 17
  • documenti_stati_ID[]array of string

    Several state codes, repeated (documenti_stati_ID[]=17&documenti_stati_ID[]=2).

    One of17231
  • documenti_tipo_IDstring

    Document type. 13 = web order (also the default). Other types return an empty list. documenti_tipo_ID[] is accepted too.

    Example: 13
  • detailsstring

    Accepted for compatibility; the answer is always medium.

    One ofmedium
    Example: medium

Responses

  • 200Orders (<ordini>), possibly empty (<ordini/>), or a KO envelope for validation errors and for a paused or draft connection.

    One of the following shapes:

    Orders
    • ordinearray of Order
      Attributes of each item
      • ord_IDinteger

        Nucleo order id; key for every later call.

      • ord_num_docstring

        Channel order name.

        Example: #1042
      • ord_datastring

        Order date dd/mm/yyyy.

      • ord_datetimestring

        Order date yyyy-mm-dd HH:MM:SS.

      • ord_DataUltimaModificastring

        Last change YYYYMMDDHHMMSS; reusable as last_upd.

      • documenti_tipo_IDstring
        Example: 13
      • documenti_stati_IDstring
        One of17231
      • stato_descrstring

        State label (CDATA).

      • order_b2binteger
        One of01
      • IDMagazzinostring

        Warehouse code of the location the order is allocated to.

      • valutastring

        ISO 4217 currency.

        Example: EUR
      • cambiostring

        Exchange rate to EUR.

      • clienteCustomer
        Child attributes
        • nomestring
        • cognomestring
        • emailstring
        • telefonostring
      • spedizioneBillingAddress & object
        Child attributes
        • nomestring
        • cognomestring
        • aziendastring
        • indirizzostring
        • indirizzo2string
        • capstring
        • cittastring
        • provinciastring
        • nazione_isostring

          ISO 3166-1 alpha-2.

        • nazioni_IDstring

          FFW country code; empty when the merchant has not mapped that country.

        • telefonostring
      • fatturazioneBillingAddress
        Child attributes
        • nomestring
        • cognomestring
        • aziendastring
        • indirizzostring
        • indirizzo2string
        • capstring
        • cittastring
        • provinciastring
        • nazione_isostring

          ISO 3166-1 alpha-2.

        • nazioni_IDstring

          FFW country code; empty when the merchant has not mapped that country.

      • metodo_spedizionestring

        Shipping method title (CDATA).

      • corrierestring

        Carrier chosen by the merchant's carrier rules.

      • servizio_corrierestring
      • notestring

        Notes for the warehouse (CDATA).

      • articoliobject
        Child attributes
        • articoloarray of OrderLine
          Attributes of each item
          • barcodestring

            EAN.

          • skustring
          • descrizionestring
          • qtainteger

            Quantity allocated to this warehouse and still active.

          • art_prezzo_listinostring

            List price net of VAT.

          • art_prezzo_internetstring

            Same as the list price.

          • art_prezzo_finale_scontatostring

            Final unit price net of VAT.

          • iva_aliquotastring

            VAT rate.

          • documenti_dettaglio_totale_ivastring

            VAT amount of the line.

          • importo_totale_rigastring

            Gross line total.

      • ord_totale_mercestring
      • ord_scontistring
      • ord_spese_spedizionestring
      • ord_totale_ivastring
      • ord_totalestring
      • ord_totale_merce_eurostring
      • ord_sconti_eurostring
      • ord_spese_spedizione_eurostring
      • ord_totale_iva_eurostring
      • ord_totale_eurostring
    ResultErrorMessage
    • ack"KO"
    • error_messagestring

      Message in CDATA.

  • 500Unexpected error, with a reference to quote to support.
    • ack"KO"
    • error_messagestring

      Message in CDATA.

  • 4XXAuthentication, IP allowlist or rate limit (401, 403, 429), in the <result>/<error_message> envelope.
    • ack"KO"
    • error_messagestring

      Message in CDATA.

Request
curl -X GET 'https://api-commerce.nucleoplatform.com/api/admin/ws/ws_orders?last_upd=20261005100000&data_dal=01%2F10%2F2026%2000%3A00%3A00&data_al=05%2F10%2F2026%2023%3A59%3A59&documenti_stati_ID=17&documenti_stati_ID%5B%5D=17&documenti_stati_ID%5B%5D=2&documenti_tipo_ID=13&details=medium' \
  -u "$NUCLEO_USERNAME:$NUCLEO_PASSWORD" \
  -H 'Accept: application/xml'
Response
<?xml version="1.0" encoding="iso-8859-1"?>
<ordini>
  <ordine>
    <ord_ID>51042</ord_ID>
    <ord_num_doc>#1042</ord_num_doc>
    <ord_data>05/10/2026</ord_data>
    <ord_datetime>2026-10-05 10:12:30</ord_datetime>
    <ord_DataUltimaModifica>20261005101534</ord_DataUltimaModifica>
    <documenti_tipo_ID>13</documenti_tipo_ID>
    <documenti_stati_ID>17</documenti_stati_ID>
    <stato_descr><![CDATA[Confermato]]></stato_descr>
    <order_b2b>0</order_b2b>
    <IDMagazzino>10</IDMagazzino>
    <valuta>EUR</valuta>
    <cambio>1.00000000</cambio>
    <cliente>
      <nome><![CDATA[Giulia]]></nome>
      <cognome><![CDATA[Bianchi]]></cognome>
      <email>giulia.bianchi@example.com</email>
      <telefono>+39 333 0000000</telefono>
    </cliente>
    <spedizione>
      <nome><![CDATA[Giulia]]></nome>
      <cognome><![CDATA[Bianchi]]></cognome>
      <azienda><![CDATA[Acme Apparel Srl]]></azienda>
      <indirizzo><![CDATA[Via Roma 1]]></indirizzo>
      <indirizzo2><![CDATA[Scala B]]></indirizzo2>
      <cap>20121</cap>
      <citta><![CDATA[Milano]]></citta>
      <provincia>MI</provincia>
      <nazione_iso>IT</nazione_iso>
      <nazioni_ID>1</nazioni_ID>
      <telefono>+39 333 0000000</telefono>
    </spedizione>
    <fatturazione>
      <nome><![CDATA[Giulia]]></nome>
      <cognome><![CDATA[Bianchi]]></cognome>
      <azienda><![CDATA[]]></azienda>
      <indirizzo><![CDATA[Via Roma 1]]></indirizzo>
      <indirizzo2><![CDATA[]]></indirizzo2>
      <cap>20121</cap>
      <citta><![CDATA[Milano]]></citta>
      <provincia>MI</provincia>
      <nazione_iso>IT</nazione_iso>
      <nazioni_ID>1</nazioni_ID>
    </fatturazione>
    <metodo_spedizione><![CDATA[Standard]]></metodo_spedizione>
    <corriere>BRT</corriere>
    <servizio_corriere></servizio_corriere>
    <note><![CDATA[Leave with the concierge]]></note>
    <articoli>
      <articolo>
        <barcode>8000000000017</barcode>
        <sku>TEE-BLK-M</sku>
        <descrizione><![CDATA[T-shirt Black M]]></descrizione>
        <qta>1</qta>
        <art_prezzo_listino>24.59</art_prezzo_listino>
        <art_prezzo_internet>24.59</art_prezzo_internet>
        <art_prezzo_finale_scontato>24.59</art_prezzo_finale_scontato>
        <iva_aliquota>22.00</iva_aliquota>
        <documenti_dettaglio_totale_iva>5.41</documenti_dettaglio_totale_iva>
        <importo_totale_riga>30.00</importo_totale_riga>
      </articolo>
    </articoli>
    <ord_totale_merce>30.00</ord_totale_merce>
    <ord_sconti>0.00</ord_sconti>
    <ord_spese_spedizione>5.00</ord_spese_spedizione>
    <ord_totale_iva>6.31</ord_totale_iva>
    <ord_totale>35.00</ord_totale>
    <ord_totale_merce_euro>30.00</ord_totale_merce_euro>
    <ord_sconti_euro>0.00</ord_sconti_euro>
    <ord_spese_spedizione_euro>5.00</ord_spese_spedizione_euro>
    <ord_totale_iva_euro>6.31</ord_totale_iva_euro>
    <ord_totale_euro>35.00</ord_totale_euro>
  </ordine>
</ordini>
get/api/admin/documenti/get-order-docs

Download order documents

Fiscal documents of an order (invoice, receipt, credit note) as base64 PDF. Alias: GET /api/documenti/admin/get-order-docs.

  • type FFW codes in <type> (defaults): 3 invoice, 5 credit note, 31 receipt, 32 receipt variation.
  • No documents, unknown order or invalid id: <ACK>ERROR</ACK> with an empty <documents/>, HTTP 200.
  • Every error of this service (including authentication) uses the same envelope without a message: rely on the HTTP status.

Rate limit: shared 600 calls/minute per connection.

GET https://api-commerce.nucleoplatform.com/api/admin/documenti/get-order-docs
Authentication: HTTP Basic
Rate limit: 600 requests per 1m, per key

Query parameters

  • documenti_testa_IDstringrequired

    The order's ord_ID.

    pattern ^\d+$
    Example: 51042
  • typestring

    sell (sale documents), return (return documents), empty = all.

    One ofsellreturn
    Example: sell

Responses

  • 200Documents, or ERROR with no documents.
    • ACKstring
      One ofOKERROR
    • documentsobject
      Child attributes
      • documentarray of object
        Attributes of each item
        • idstring
        • typestring

          FFW document type code.

        • numberstring
        • refstring
        • contentstring

          PDF in CDATA.

  • 500Unexpected error. Same envelope as "no documents"; check the HTTP status.
    • ACKstring
      One ofOKERROR
    • documentsobject
      Child attributes
      • documentarray of object
        Attributes of each item
        • idstring
        • typestring

          FFW document type code.

        • numberstring
        • refstring
        • contentstring

          PDF in CDATA.

  • 4XXAuthentication, IP allowlist or rate limit (401, 403, 429). Same envelope as "no documents"; check the HTTP status.
    • ACKstring
      One ofOKERROR
    • documentsobject
      Child attributes
      • documentarray of object
        Attributes of each item
        • idstring
        • typestring

          FFW document type code.

        • numberstring
        • refstring
        • contentstring

          PDF in CDATA.

Request
curl -X GET 'https://api-commerce.nucleoplatform.com/api/admin/documenti/get-order-docs?documenti_testa_ID=51042&type=sell' \
  -u "$NUCLEO_USERNAME:$NUCLEO_PASSWORD" \
  -H 'Accept: application/xml'
Response
<?xml version="1.0" encoding="iso-8859-1"?>
<response>
  <ACK>OK</ACK>
  <documents>
    <document>
      <id>5</id>
      <type>31</type>
      <number>1</number>
      <ref>R0002</ref>
      <content><![CDATA[JVBERi0xLjQKJcfsj6IK...]]></content>
    </document>
  </documents>
</response>
get/api/documenti/admin/get-order-docs

Download order documents (alias)

Alias of GET /api/admin/documenti/get-order-docs, same parameters, behaviour and responses.

Rate limit: shared 600 calls/minute per connection.

GET https://api-commerce.nucleoplatform.com/api/documenti/admin/get-order-docs
Authentication: HTTP Basic
Rate limit: 600 requests per 1m, per key

Query parameters

  • documenti_testa_IDstringrequired

    The order's ord_ID.

    pattern ^\d+$
    Example: 51042
  • typestring

    sell (sale documents), return (return documents), empty = all.

    One ofsellreturn
    Example: sell

Responses

  • 200Documents, or ERROR with no documents.
    • ACKstring
      One ofOKERROR
    • documentsobject
      Child attributes
      • documentarray of object
        Attributes of each item
        • idstring
        • typestring

          FFW document type code.

        • numberstring
        • refstring
        • contentstring

          PDF in CDATA.

  • 500Unexpected error. Same envelope as "no documents"; check the HTTP status.
    • ACKstring
      One ofOKERROR
    • documentsobject
      Child attributes
      • documentarray of object
        Attributes of each item
        • idstring
        • typestring

          FFW document type code.

        • numberstring
        • refstring
        • contentstring

          PDF in CDATA.

  • 4XXAuthentication, IP allowlist or rate limit (401, 403, 429). Same envelope as "no documents"; check the HTTP status.
    • ACKstring
      One ofOKERROR
    • documentsobject
      Child attributes
      • documentarray of object
        Attributes of each item
        • idstring
        • typestring

          FFW document type code.

        • numberstring
        • refstring
        • contentstring

          PDF in CDATA.

Request
curl -X GET 'https://api-commerce.nucleoplatform.com/api/documenti/admin/get-order-docs?documenti_testa_ID=51042&type=sell' \
  -u "$NUCLEO_USERNAME:$NUCLEO_PASSWORD" \
  -H 'Accept: application/xml'
Response
<?xml version="1.0" encoding="iso-8859-1"?>
<response>
  <ACK>OK</ACK>
  <documents>
    <document>
      <id>5</id>
      <type>31</type>
      <number>1</number>
      <ref>R0002</ref>
      <content><![CDATA[JVBERi0xLjQKJcfsj6IK...]]></content>
    </document>
  </documents>
</response>

Stock

Push stock levels.

post/api/aggiorna-giacenze-impegni

Push stock levels

Absolute stock per item and warehouse code, already net of the warehouse's commitments (orders already downloaded).

  • Root <giacenze>, one <articolo> per item and warehouse: IDArtCod (EAN) and giacenza (integer) required, IDMagazzino optional (defaults to the code configured on the connection, 1 unless the merchant changed it).
  • The same EAN on several warehouse codes mapped to the same Nucleo location is summed.
  • Nucleo subtracts the paid orders you have not downloaded yet, then publishes availability to the sales channels.
  • At most 500 <articolo> per call (merchant-configurable): above the limit the call is KO and nothing is processed. Send batches of 500.
  • A malformed item makes the whole call KO (nothing processed).
  • An unknown EAN is skipped and the merchant is alerted; the rest is processed and the answer is OK. A warehouse code not mapped to a Nucleo location is stored but not published, and the merchant is alerted.
  • Items not sent are not zeroed: send giacenza 0 to zero an item.
  • Optional query ?full=1 marks a full snapshot: Nucleo republishes every item received, even unchanged ones.
  • OK means the levels are stored; publication to the channels follows asynchronously.

Official input is the form field xml; the raw body is accepted too.

Idempotent: repeating the call re-applies the same values.

Rate limit: shared 600 calls/minute per connection.

POST https://api-commerce.nucleoplatform.com/api/aggiorna-giacenze-impegni
Authentication: HTTP Basic
Rate limit: 600 requests per 1m, per key

Query parameters

  • fullstring

    Any non-empty value marks a full snapshot and forces republication of all items received.

    Example: 1

Request bodyapplication/x-www-form-urlencoded, multipart/form-data, application/xml

  • xmlstringrequired

    The <giacenze> document.

Responses

  • 200OK, or KO with the reason (nothing processed). Also KO when the connection is paused or a draft.
    • ackstring
      One ofOKKO
    • errorstring
  • 500Unexpected error, with a reference to quote to support.
    • ackstring
      One ofOKKO
    • errorstring
  • 4XXAuthentication, IP allowlist or rate limit (401, 403, 429), in the <giacenze> envelope.
    • ackstring
      One ofOKKO
    • errorstring
Request
curl -X POST 'https://api-commerce.nucleoplatform.com/api/aggiorna-giacenze-impegni?full=1' \
  -u "$NUCLEO_USERNAME:$NUCLEO_PASSWORD" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/xml' \
  --data-urlencode 'xml=<giacenze><articolo><IDArtCod>8000000000017</IDArtCod><giacenza>10</giacenza><IDMagazzino>10</IDMagazzino></articolo></giacenze>'
Response
<?xml version="1.0" encoding="iso-8859-1"?>
<giacenze>
  <ack>OK</ack>
</giacenze>

Shipping

Shipment notification, and the optional Nucleo-generated courier labels and bordereau.

post/api/admin/spedizioni/notify-spedizione

Report shipment with carrier and tracking

Nucleo extension (not part of the original FFW services, beta): tells Nucleo that orders left the warehouse, with carrier, tracking and parcels, so Nucleo can create the fulfilment on the sales channel and the customer receives the tracking. One or more <spedizione>.

  • ord_ID required; the order must be allocated to this warehouse and already downloaded (state 17), otherwise Invalid order status: <status>.
  • data_spedizione yyyy-mm-dd HH:MM:SS Italian time; missing or unreadable = now.
  • corriere, servizio: default to the order's carrier and service. tracking_url empty = Nucleo builds the link from the carrier when it can.
  • colli/collo: one tracking per parcel, weight in grams.
  • articoli/articolo: shipped items; when missing, everything allocated to this warehouse is shipped. Items not declared stay open for the merchant's customer service.
  • The order moves to Shipped and comes back in ws_orders with state 31. If it was being cancelled, the shipment is recorded and the merchant is alerted.
  • All or nothing: an unknown order rejects the whole call.

JSON alternative: with Content-Type: application/json (or a body starting with {), the call takes the fields of the T-Data Orders/Shipped contract (OmsOrderNumber = order name or ord_ID, EventDateTime, CourierCode, CourierWaybill, TrackingUrl, ShipmentTotalWeightGr, ShipmentTotalVolumeCm3) and answers in T-Data JSON. Authentication and rate-limit errors keep the XML envelope.

Idempotent: the same notification repeated with the same first tracking creates no second shipment and no second email.

Rate limit: shared 600 calls/minute per connection.

POST https://api-commerce.nucleoplatform.com/api/admin/spedizioni/notify-spedizione
Authentication: HTTP Basic
Rate limit: 600 requests per 1m, per key

Request bodyapplication/xml, application/x-www-form-urlencoded, application/json

  • spedizionearray of object
    Attributes of each item
    • ord_IDintegerrequired
    • data_spedizionestring

      yyyy-mm-dd HH:MM:SS Italian time.

    • corrierestring
    • serviziostring
    • tracking_urlstring
    • colliobject
      Child attributes
      • colloarray of object
        Attributes of each item
        • trackingstring
        • peso_grinteger
    • articoliobject
      Child attributes
      • articoloarray of object
        Attributes of each item
        • barcodestring
        • qtainteger

Responses

  • 200OK or KO (XML), or T-Data JSON success for a JSON request.
    • ackstring
      One ofOKKO
    • messagestring
  • 400JSON request only, invalid body or unknown order.
    • ErrorCode"Exception"
    • Messagestring
  • 500Unexpected error, with a reference to quote to support.
    • ackstring
      One ofOKKO
    • messagestring
  • 4XXAuthentication, IP allowlist or rate limit (401, 403, 429), in the <result>/<message> envelope.
    • ackstring
      One ofOKKO
    • messagestring
Request
curl -X POST https://api-commerce.nucleoplatform.com/api/admin/spedizioni/notify-spedizione \
  -u "$NUCLEO_USERNAME:$NUCLEO_PASSWORD" \
  -H 'Content-Type: application/xml' \
  -H 'Accept: application/xml' \
  --data-binary @- <<'EOF'
<spedizioni>
  <spedizione>
    <ord_ID>51042</ord_ID>
    <data_spedizione>2026-10-05 16:30:00</data_spedizione>
    <corriere>BRT</corriere>
    <servizio>STANDARD</servizio>
    <tracking_url></tracking_url>
    <colli>
      <collo><tracking>BRT0000000000001</tracking><peso_gr>1200</peso_gr></collo>
      <collo><tracking>BRT0000000000002</tracking><peso_gr>800</peso_gr></collo>
    </colli>
    <articoli>
      <articolo><barcode>8000000000017</barcode><qta>1</qta></articolo>
    </articoli>
  </spedizione>
</spedizioni>
EOF
Response
<?xml version="1.0" encoding="iso-8859-1"?>
<result>
  <ack>OK</ack>
  <message></message>
</result>
post/api/admin/spedizioni/get-etichette-corriere

Get courier labels generated by Nucleo

Optional, off by default. Only when the merchant has Nucleo generate courier labels; otherwise HTTP 404 <etichette><result>courier labels are managed by the warehouse</result></etichette>.

For each <order> (id = ord_ID, colli = number of parcels, default 1) Nucleo creates the shipment with the order's carrier and returns one PDF label per parcel, base64 in CDATA. The order must have been downloaded (state 17); it moves to Label created. Per-order problems are reported in that order's <error> (Order not found, Invalid order status: <status>, or the carrier's message) while <result> stays OK.

Official input is the form field xml; the raw body is accepted too.

Idempotent: while a shipment with labels is active for the order, the same labels are returned and no new shipment is created. Use del-etichette-corriere to start over.

Rate limit: shared 600 calls/minute per connection.

POST https://api-commerce.nucleoplatform.com/api/admin/spedizioni/get-etichette-corriere
Authentication: HTTP Basic
Rate limit: 600 requests per 1m, per key

Request bodyapplication/x-www-form-urlencoded, application/xml

  • xmlstringrequired

    The <spedizioni> document.

Responses

  • 200Labels per order, or xml parameter malformed.

    One of the following shapes:

    Labels
    • result"OK"
    • orderarray of object
      Attributes of each item
      • idstring
      • errorstring

        Empty on success.

      • shipperstring

        Carrier display name.

      • typestring
        One ofPDF
      • labelsobject
        Child attributes
        • labelarray of string
    LabelsError
    • resultstring
  • 404Courier labels are managed by the warehouse for this connection (default).
    • resultstring
  • 500Unexpected error, with a reference to quote to support.
    • resultstring
  • 4XXAuthentication, IP allowlist or rate limit (401, 403, 429), in the <etichette> envelope.
    • resultstring
Request
curl -X POST https://api-commerce.nucleoplatform.com/api/admin/spedizioni/get-etichette-corriere \
  -u "$NUCLEO_USERNAME:$NUCLEO_PASSWORD" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/xml' \
  --data-urlencode 'xml=<spedizioni><order><id>51042</id><colli>2</colli></order></spedizioni>'
Response
<?xml version="1.0" encoding="iso-8859-1"?>
<etichette>
  <result>OK</result>
  <order>
    <id>51042</id>
    <error></error>
    <shipper>BRT</shipper>
    <type>PDF</type>
    <labels>
      <label><![CDATA[JVBERi0xLjQKJcfsj6IK...]]></label>
      <label><![CDATA[JVBERi0xLjQKJcfsj6IK...]]></label>
    </labels>
  </order>
  <order>
    <id>59999</id>
    <error>Order not found</error>
    <shipper></shipper>
    <type></type>
    <labels></labels>
  </order>
</etichette>
post/api/admin/spedizioni/del-etichette-corriere

Void courier labels generated by Nucleo

Optional, off by default (see get-etichette-corriere). For each <order> (id = ord_ID) voids the active shipment at the carrier and puts the order back to Exported, ready for new labels. Per-order problems are reported in <error> (Order not found when there is no active shipment, or the carrier's message).

Idempotent: a second call finds no active shipment and answers Order not found for that order.

Rate limit: shared 600 calls/minute per connection.

POST https://api-commerce.nucleoplatform.com/api/admin/spedizioni/del-etichette-corriere
Authentication: HTTP Basic
Rate limit: 600 requests per 1m, per key

Request bodyapplication/x-www-form-urlencoded, application/xml

  • xmlstringrequired

    The <spedizioni> document.

Responses

  • 200Outcome per order, or xml parameter malformed.

    One of the following shapes:

    LabelsVoided
    • result"OK"
    • orderarray of object
      Attributes of each item
      • idstring
      • errorstring
    LabelsError
    • resultstring
  • 404Courier labels are managed by the warehouse for this connection (default).
    • resultstring
  • 500Unexpected error, with a reference to quote to support.
    • resultstring
  • 4XXAuthentication, IP allowlist or rate limit (401, 403, 429), in the <etichette> envelope.
    • resultstring
Request
curl -X POST https://api-commerce.nucleoplatform.com/api/admin/spedizioni/del-etichette-corriere \
  -u "$NUCLEO_USERNAME:$NUCLEO_PASSWORD" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/xml' \
  --data-urlencode 'xml=<spedizioni><order><id>51042</id><colli>2</colli></order></spedizioni>'
Response
<?xml version="1.0" encoding="iso-8859-1"?>
<etichette>
  <result>OK</result>
  <order>
    <id>51042</id>
    <error></error>
  </order>
  <order>
    <id>59999</id>
    <error>Order not found</error>
  </order>
</etichette>
post/api/admin/spedizioni/ws-close-bordero

Close the bordereau of the day

Optional, off by default (see get-etichette-corriere); otherwise HTTP 404 <result><ack>KO</ack><error>courier labels are managed by the warehouse</error></result>.

Confirms to the carriers every shipment of this connection with labels created and not yet confirmed (one manifest per carrier). Each order moves to Shipped, Nucleo creates the fulfilment on the sales channel and the order comes back in ws_orders with state 31. No body is needed. The FFW spelling //api/admin/spedizioni/ws-close-bordero is accepted.

With nothing to confirm the answer is KO No shipping to be confirmed (HTTP 200), which also makes a repeated call harmless.

Rate limit: shared 600 calls/minute per connection.

POST https://api-commerce.nucleoplatform.com/api/admin/spedizioni/ws-close-bordero
Authentication: HTTP Basic
Rate limit: 600 requests per 1m, per key

Responses

  • 200OK, or KO when there is nothing to confirm.
    • ackstring
      One ofOKKO
    • errorstring
  • 404Courier labels are managed by the warehouse for this connection (default).
    • ackstring
      One ofOKKO
    • errorstring
  • 500Unexpected error, with a reference to quote to support.
    • ackstring
      One ofOKKO
    • errorstring
  • 4XXAuthentication, IP allowlist or rate limit (401, 403, 429).
    • ackstring
      One ofOKKO
    • errorstring
Request
curl -X POST https://api-commerce.nucleoplatform.com/api/admin/spedizioni/ws-close-bordero \
  -u "$NUCLEO_USERNAME:$NUCLEO_PASSWORD" \
  -H 'Accept: application/xml'
Response
<?xml version="1.0" encoding="iso-8859-1"?>
<result>
  <ack>OK</ack>
  <error></error>
</result>

Returns

Download expected returns and report what was received.

get/api/admin/resi/list

Download returns

Returns of orders fulfilled by this warehouse, or routed to one of its locations. Returns created by the warehouse itself (parcels that arrived unannounced) are not listed. At least one of data_dal, data_al, last_upd, resi_ID is required.

States (resi_stati_ID, FFW defaults): 1 in progress (RESO IN CORSO), 2 confirmed (RESO CONFERMATO), 3 anomalous (RESO ANOMALO), 4 cancelled (RESO ANNULLATO).

Reasons (resi_causali_ID, FFW defaults): 1 wrong size · 2 not as pictured · 3 fit · 4 defective · 5 wrong item · 6 other · 7 arrived late · 8 changed mind · 9 claim · 10 return to sender · 11 manual return. The description (stato_descr) is in Italian, as in FFW.

  • last_upd is a >= filter on the last change: a return can come back twice, update it by reso_ID.
  • Date range on the creation date, at most one month; without data_dal it is one month before data_al.
  • resi_stati_ID or resi_causali_ID require data_dal or limit.
  • At most 1000 returns without limit. Default order: creation date descending (ASC for ascending); orderBy=resi_id sorts by reso_ID ascending.
  • scontotot reproduces the FFW sample: the VAT of the returned lines, negative.
  • Always XML (type=csv is not supported). Reading has no side effect.

Errors: validation errors answer HTTP 200 with <result><ack>KO</ack><error_message>.

Rate limit: shared 600 calls/minute per connection.

GET https://api-commerce.nucleoplatform.com/api/admin/resi/list
Authentication: HTTP Basic
Rate limit: 600 requests per 1m, per key

Query parameters

  • data_dalstring (date)

    Creation date from, yyyy-mm-dd.

    Example: 2026-10-01
  • data_alstring (date)

    Creation date to, yyyy-mm-dd. Defaults to today.

    Example: 2026-10-07
  • last_updstring

    Returns changed from this instant (>=), dd/mm/yyyy hh:mm:ss, Italian time, not older than one month.

    Example: 07/10/2026 09:00:00
  • resi_IDinteger

    One return by id.

    Example: 7014
  • resi_stati_IDstring

    State filter. Requires data_dal or limit.

    One of1234
    Example: 1
  • resi_causali_IDstring

    Reason filter. Requires data_dal or limit.

    One of1234567891011
    Example: 1
  • magazzini_ID_webstring

    Only returns routed to the location with this warehouse code.

    Example: 10
  • limitinteger

    Maximum number of returns. Default 1000.

    min 0
    Example: 50
  • orderBystring

    resi_id sorts by reso_ID ascending; otherwise by creation date.

    One ofresi_id
    Example: resi_id
  • ASCstring

    When present (any value), the creation-date order is ascending.

Responses

  • 200Returns (<resi>), possibly empty (<resi/>), or a KO envelope.

    One of the following shapes:

    Returns
    • resoarray of Return
      Attributes of each item
      • reso_IDinteger
      • reso_datastring

        dd/mm/yyyy.

      • reso_datetimestring

        yyyy-mm-dd HH:MM:SS.

      • resi_data_ultima_modificastring

        yyyy-mm-dd HH:MM:SS.

      • ord_IDinteger
      • ord_num_docstring
      • nazioni_IDstring
      • resi_stati_IDstring
        One of1234
      • stato_descrstring
      • resi_causali_IDstring
      • reso_descrstring

        Customer reason text (CDATA).

      • reso_prezzototstring
      • reso_prezzototale_eurostring
      • scontototstring

        VAT of the returned lines with negative sign.

      • articoliobject
        Child attributes
        • articoloarray of object
          Attributes of each item
          • barcodestring
          • qtainteger
          • art_prezzo_listinostring
          • art_prezzo_internetstring
          • art_prezzo_finale_scontatostring
          • documenti_dettaglio_totale_ivastring
          • iva_aliquotastring
          • importo_totale_rigastring
    ResultErrorMessage
    • ack"KO"
    • error_messagestring

      Message in CDATA.

  • 500Unexpected error, with a reference to quote to support.
    • ack"KO"
    • error_messagestring

      Message in CDATA.

  • 4XXAuthentication, IP allowlist or rate limit (401, 403, 429), in the <result>/<error_message> envelope.
    • ack"KO"
    • error_messagestring

      Message in CDATA.

Request
curl -X GET 'https://api-commerce.nucleoplatform.com/api/admin/resi/list?data_dal=2026-10-01&data_al=2026-10-07&last_upd=07%2F10%2F2026%2009%3A00%3A00&resi_ID=7014&resi_stati_ID=1&resi_causali_ID=1&magazzini_ID_web=10&limit=50&orderBy=resi_id' \
  -u "$NUCLEO_USERNAME:$NUCLEO_PASSWORD" \
  -H 'Accept: application/xml'
Response
<?xml version="1.0" encoding="iso-8859-1"?>
<resi>
  <reso>
    <reso_ID>7014</reso_ID>
    <reso_data>07/10/2026</reso_data>
    <reso_datetime>2026-10-07 09:41:02</reso_datetime>
    <resi_data_ultima_modifica>2026-10-07 09:41:02</resi_data_ultima_modifica>
    <ord_ID>51042</ord_ID>
    <ord_num_doc>#1042</ord_num_doc>
    <nazioni_ID>1</nazioni_ID>
    <resi_stati_ID>1</resi_stati_ID>
    <stato_descr><![CDATA[RESO IN CORSO]]></stato_descr>
    <resi_causali_ID>1</resi_causali_ID>
    <reso_descr><![CDATA[Too small]]></reso_descr>
    <reso_prezzotot>30.00</reso_prezzotot>
    <reso_prezzototale_euro>30.00</reso_prezzototale_euro>
    <scontotot>-5.41</scontotot>
    <articoli>
      <articolo>
        <barcode>8000000000017</barcode>
        <qta>1</qta>
        <art_prezzo_listino>24.59</art_prezzo_listino>
        <art_prezzo_internet>24.59</art_prezzo_internet>
        <art_prezzo_finale_scontato>24.59</art_prezzo_finale_scontato>
        <documenti_dettaglio_totale_iva>5.41</documenti_dettaglio_totale_iva>
        <iva_aliquota>22.00</iva_aliquota>
        <importo_totale_riga>30.00</importo_totale_riga>
      </articolo>
    </articoli>
  </reso>
</resi>
post/api/admin/resi/notify-reso

Report items received for returns

Items and quantities actually received for one or more returns (<reso> repeated).

  • All or nothing: the whole call is validated first; an unknown reso_ID or a malformed item rejects it and no return is updated.
  • The return is confirmed (state 2) when exactly the expected items and quantities arrived; otherwise it is anomalous (state 3) and goes to the merchant's customer service. An item not in the return makes it anomalous.
  • If the return had been cancelled (or already closed) and the parcel arrives anyway, the goods are recorded, the merchant is alerted and the answer is OK.

Official input is the raw body; the form field xml is accepted too.

Idempotent: a second call on the same return recomputes the outcome.

Rate limit: shared 600 calls/minute per connection.

POST https://api-commerce.nucleoplatform.com/api/admin/resi/notify-reso
Authentication: HTTP Basic
Rate limit: 600 requests per 1m, per key

Request bodyapplication/xml, application/x-www-form-urlencoded

  • resoarray of object
    Attributes of each item
    • reso_IDintegerrequired
    • articoliobject
      Child attributes
      • articoloarray of object
        Attributes of each item
        • barcodestringrequired
        • qtaintegerrequired
          min 0
        • notestring

Responses

  • 200OK, or KO with the reason (nothing applied). Also KO when the connection is paused or a draft.
    • ackstring
      One ofOKKO
    • messagestring
  • 500Unexpected error, with a reference to quote to support.
    • ackstring
      One ofOKKO
    • messagestring
  • 4XXAuthentication, IP allowlist or rate limit (401, 403, 429), in the <result>/<message> envelope.
    • ackstring
      One ofOKKO
    • messagestring
Request
curl -X POST https://api-commerce.nucleoplatform.com/api/admin/resi/notify-reso \
  -u "$NUCLEO_USERNAME:$NUCLEO_PASSWORD" \
  -H 'Content-Type: application/xml' \
  -H 'Accept: application/xml' \
  --data-binary @- <<'EOF'
<resi>
  <reso>
    <reso_ID>7014</reso_ID>
    <articoli>
      <articolo><barcode>8000000000017</barcode><qta>1</qta><note>intact</note></articolo>
    </articoli>
  </reso>
</resi>
EOF
Response
<?xml version="1.0" encoding="iso-8859-1"?>
<result>
  <ack>OK</ack>
  <message></message>
</result>