API Adapter

Upsert Sales Order

Version ≥ 3.6

La chiamata consente di creare o aggiornare uno o più ordini con relative righe d'ordine.

Il sales channel associato all'ordine viene identificato tramite il campo channel presente nell'oggetto ordine cercando quello corrispondente con il campo Channel Name del sales channel.

L'inserimento prenota le quantità dei prodotti associati all'ordine solo per la prima importazione secondo la logica di assegnamento selezionata nel canale associato, i successivi aggiornamenti non modificano le prenotazioni sui magazzini, dovrà essere modificato a mano.

Il flusso importa anche i rimborsi associati all'ordine creando le entità corrispondenti.

Permessi Ruolo o Utente

Permesso generale per accesso alla risorsa: Objects
Permesso per l'accesso al tipo di dataobject: SalesOrder e SalesOrderItem

POST/api/adp/egress/upsert-sales-order

Headers: Autenticazione

Query Params Parametri non presenti

Body

Body Request

{
    "action": "execute",
    "messages": [
{
    "msgId": "640ee776f545844f1472f0bc",
    "msg": {
    "id": "gid://shopify/Order/6465221689584",
    "orderNumber": null,
    "orderName": "#1065",
    "channel": "soh-romolino",
    "srcName": null,
    "note": null,
    "tags": [],
    "test": false,
    "orderNotes": {},
    "paymentStatus": "PENDING",
    "fulfillmentStatus": "UNFULFILLED",
    "isPickupInStore": false,
    "pickupInStoreLocation": null,
    "shippingAddress": {
    "firstName": "Giulia",
    "lastName": "Verdi",
    "company": null,
    "street1": "Via Bruno Buozzi",
    "street2": null,
    "city": "Bari",
    "zip": "70132",
    "province": "Bari",
    "provinceCode": "BA",
    "country": "Italy",
    "countryCode": "IT",
    "phone": null
},
    "billingAddress": {
    "firstName": "Giulia",
    "lastName": "Verdi",
    "company": null,
    "street1": "Via Bruno Buozzi",
    "street2": null,
    "city": "Bari",
    "zip": "70132",
    "province": "Bari",
    "provinceCode": "BA",
    "country": "Italy",
    "countryCode": "IT",
    "phone": null
},
    "customer": {
    "id": "gid://shopify/Customer/6419340329200",
    "channel": null,
    "email": "giulia.verdi3234435434356@gmail.com",
    "createdAt": null,
    "updatedAt": null,
    "firstName": "Giulia",
    "lastName": "Verdi",
    "phone": null,
    "locale": "en",
    "tags": null,
    "acceptsEmailMarketing": false,
    "acceptsEmailMarketingDate": null,
    "acceptsSmsMarketing": false,
    "acceptsSmsMarketingDate": null
},
    "cancelReason": null,
    "cancelledAt": null,
    "orderItems": [
{
    "id": "gid://shopify/LineItem/15621939953904",
    "sku": "67878e765fc84-green-M",
    "productId": "gid://shopify/Product/9175608131824",
    "variantId": "gid://shopify/ProductVariant/46989400342768",
    "imageUrl": null,
    "bundleCode": null,
    "name": "Annoying Alligator - M / Verde",
    "requiresShipping": false,
    "vendor": "SOH Romolino",
    "isGiftCard": false,
    "giftCards": [],
    "metadata": null,
    "shopTotals": {
    "currencyCode": "EUR",
    "unitPrice": 500,
    "originalUnitPrice": 500,
    "totalNetPrice": 409.84,
    "totalPrice": 500,
    "originalTotalPrice": 500
},
    "customerTotals": {
    "currencyCode": "EUR",
    "unitPrice": 500,
    "originalUnitPrice": 500,
    "totalNetPrice": 409.84,
    "totalPrice": 500,
    "originalTotalPrice": 500
},
    "taxLines": [
{
    "title": "IT IVA",
    "rate": 0.22,
    "shopCurrencyCode": "EUR",
    "shopAmount": 90.16,
    "customerCurrencyCode": "EUR",
    "customerAmount": 90.16
}
    ],
    "taxBreakdown": {},
    "unitWeight": null,
    "duties": {},
    "discountAllocations": [],
    "qtyOrdered": 1,
    "qtyShipped": 0,
    "qtyRefunded": 1,
    "unitAmountDiscounted": 0,
    "orderItemNotes": {},
    "itemGroup": null
},
{
    "id": "gid://shopify/LineItem/15621939986672",
    "sku": "67878e765fc84-green-S",
    "productId": "gid://shopify/Product/9175608131824",
    "variantId": "gid://shopify/ProductVariant/46989400375536",
    "imageUrl": null,
    "bundleCode": null,
    "name": "Annoying Alligator - S / Verde",
    "requiresShipping": false,
    "vendor": "SOH Romolino",
    "isGiftCard": false,
    "giftCards": [],
    "metadata": null,
    "shopTotals": {
    "currencyCode": "EUR",
    "unitPrice": 500,
    "originalUnitPrice": 500,
    "totalNetPrice": 409.84,
    "totalPrice": 500,
    "originalTotalPrice": 500
},
    "customerTotals": {
    "currencyCode": "EUR",
    "unitPrice": 500,
    "originalUnitPrice": 500,
    "totalNetPrice": 409.84,
    "totalPrice": 500,
    "originalTotalPrice": 500
},
    "taxLines": [
{
    "title": "IT IVA",
    "rate": 0.22,
    "shopCurrencyCode": "EUR",
    "shopAmount": 90.16,
    "customerCurrencyCode": "EUR",
    "customerAmount": 90.16
}
    ],
    "taxBreakdown": {},
    "unitWeight": null,
    "duties": {},
    "discountAllocations": [],
    "qtyOrdered": 1,
    "qtyShipped": 0,
    "qtyRefunded": 0,
    "unitAmountDiscounted": 0,
    "orderItemNotes": {},
    "itemGroup": null
}
    ],
    "shopTotals": {
    "currencyCode": "EUR",
    "subTotalPrice": 1000,
    "totalNetPrice": 819.68,
    "totalPrice": 1000,
    "totalShippingPrice": 0,
    "totalDiscounts": 0
},
    "customerTotals": {
    "currencyCode": "EUR",
    "subTotalPrice": 1000,
    "totalNetPrice": 819.68,
    "totalPrice": 1000,
    "totalShippingPrice": 0,
    "totalDiscounts": 0
},
    "taxExempt": false,
    "taxesIncluded": true,
    "taxLines": [
{
    "title": "IT IVA",
    "rate": 0.22,
    "shopCurrencyCode": "EUR",
    "shopAmount": 180.32,
    "customerCurrencyCode": "EUR",
    "customerAmount": 180.32
}
    ],
    "fulfillments": [],
    "transactions": [],
    "discounts": [],
    "createdAt": "2025-10-14T10:37:41+00:00",
    "updatedAt": "2025-10-14T10:38:43+00:00",
    "processedAt": "2025-10-14T10:37:41+00:00",
    "closedAt": null,
    "returns": [],
    "refunds": [
{
    "id": "gid://shopify/Refund/936189493488",
    "createdAt": "2025-10-14T10:38:28+00:00",
    "refundNote": null,
    "returnNote": "",
    "returnReference": "",
    "returnReason": "",
    "orderAdjustments": [],
    "refundLineItems": [
{
    "id": "gid://shopify/RefundLineItem/535112319216",
    "sku": "67878e765fc84-green-M",
    "qtyRefunded": 1,
    "shopTotalRefund": {
    "currencyCode": "EUR",
    "priceSet": 500,
    "subTotalPrice": 500,
    "totalTaxSet": 90.16
},
    "customerTotalRefund": {
    "currencyCode": "EUR",
    "priceSet": 500,
    "subTotalPrice": 500,
    "totalTaxSet": 90.16
}
}
    ],
    "refundShippingLines": [],
    "transactions": []
}
    ],
    "shippingLines": [],
    "metafields": [],
    "metadata": {}
},
    "meta": {}
}
    ],
    "requestId": "da7314de6b50407c9bf1b99acdadf65f",
    "meta": {}
}

Il body della risposta è compatibile con Flowlyze. Per ogni messaggio inviato sarà restituito l'esito, l'id del messaggio e la data di risposta.

Body Response 200 OK

{
    "requestId": "da7314de6b50407c9bf1b99acdadf65f",
    "isAsync": false,
    "messages": [
{
    "msgId": "640ee776f545844f1472f0bc",
    "status": "Success",
    "date": "2025-10-13T10:47:44+00:00"
}
    ]
}

Se durante il processo di creazione/aggiornamento del reso avvenisse un errore, il messaggio di risposta riporterà il messaggio di errore ottenuto, come nell'esempio sottostante.

È comunque presente un meccanismo di rollback, pertanto se si verifica un errore, lo stato del sistema viene ripristinato.

Body Response 400 Bad Request

{
    "requestId": "da7314de6b50407c9bf1b99acdadf65f",
    "isAsync": false,
    "messages": [
{
    "msgId": "640ee776f545844f1472f0bc",
    "status": "Error",
    "date": "2025-10-13T10:47:44+00:00",
    "errorMessage": "Error on creation"
}
    ]
}

Upsert Reso

Version ≥ 3.6

La chiamata consente di creare uno o più resi a partire da uno o più ordini esistenti.
La struttura del body della richiesta deve seguire l’esempio fornito.

Permessi Ruolo o Utente

Permesso generale per accesso alla risorsa: Objects
Permesso per l'accesso al tipo di dataobject: Returns e Refund

Struttura dei Messaggi

Per ogni messaggio è possibile:

Specificare l’ordine da cui partire per eseguire il reso.
Impostare lo status (solo se il reso è in fase di creazione).
Impostare se deve essere creato il rimborso
Impostare se rimborsare le spese di spedizione
Elencare i prodotti per i quali si intende effettuare il reso.

Dettaglio dei Prodotti

Per ciascun prodotto, è possibile configurare i seguenti campi:

Campo	Tipo	Descrizione
`sku`	string	Codice di riferimento del prodotto.
`qty`	number	Quantità del prodotto da restituire. Deve essere numerica, ≥ 1 e ≤ quantità acquistata.
`qtyAccepted`	number	Quantità accettata per il reso. Deve essere numerica, ≥ 1, ≤ quantità acquistata, e ≤ qty.
`reason`	string	Motivazione del reso (campo di testo libero).

Condizioni di Aggiornamento del Reso

Un reso già presente nel sistema viene aggiornato solo se:

Il reso si trova in uno stato diverso da closed.
I prodotti del reso corrispondono esattamente a quelli inviati nella richiesta e con le stesse quantità.

Se entrambe le condizioni sono soddisfatte le quantità accettate dei prodotti nel reso verranno aggiornate.

Creazione rimborso

La creazione del rimborso associato al reso avverrà in automatico. Il rimborso verrà quindi creato nello stato Confirmed

POST/api/adp/egress/upsert-returns

Headers: Autenticazione

Query Params Parametri non presenti

Body Request

{
    "action": "execute",
    "messages": [
{
    "msgId": "640ee776f545844f1472f0bc",
    "msg": {
    "orderName": "#1206",
    "status": "closed",
    "hasToBeRefunded": true,
    "refundShipment": true,
    "items": [
{
    "sku": "678790bb08755-green-M",
    "qty": 1,
    "qtyAccepted": 1,
    "reason": "Item too large"
},
{
    "sku": "678790bb08755-red-L",
    "qty": 5,
    "qtyAccepted": 2,
    "reason": "Item too large"
}
    ],
    "customFields": {
    "customerCustomField": "value"
}
},
    "meta": {}
}
    ],
    "requestId": "da7314de6b50407c9bf1b99acdadf65f",
    "meta": {}
}

Il body della risposta è compatibile con Flowlyze.

Per ogni messaggio inviato sarà restituito l'esito, l'id del messaggio e la data di risposta.

Body Response 200 OK

{
    "requestId": "da7314de6b50407c9bf1b99acdadf65f",
    "isAsync": false,
    "messages": [
{
    "msgId": "640ee776f545844f1472f0bc",
    "status": "Success",
    "date": "2025-10-13T10:47:44+00:00"
}
    ]
}

Se durante il processo di creazione/aggiornamento del reso avvenisse un errore, il messaggio di risposta riporterà il messaggio di errore ottenuto, come nell'esempio sottostante.

È comunque presente un meccanismo di rollback, pertanto se si verifica un errore, lo stato del sistema viene ripristinato.

Body Response 400 Bad Request

{
    "requestId": "da7314de6b50407c9bf1b99acdadf65f",
    "isAsync": false,
    "messages": [
{
    "msgId": "640ee776f545844f1472f0bc",
    "status": "Error",
    "date": "2025-10-13T10:47:44+00:00",
    "errorMessage": "Error on creation"
}
    ]
}

Create Refund

Version ≥ 3.6

La chiamata consente di creare uno o più rimborsi a partire da uno o più ordini esistenti.
La struttura del body della richiesta deve seguire l’esempio fornito.

Permessi Ruolo o Utente

Permesso generale per accesso alla risorsa: Objects
Permesso per l'accesso al tipo di dataobject: Refund

Struttura dei Messaggi

Per ogni messaggio è possibile:

Specificare l’ordine da cui partire per eseguire il rimborso.
Impostare lo status
Impostare se rimborsare le spese di spedizione
Elencare i prodotti per i quali si intende effettuare il rimborso

Dettaglio dei Prodotti

Per ciascun prodotto, è possibile configurare i seguenti campi:

Campo	Tipo	Descrizione
`sku`	string	Codice di riferimento del prodotto. Deve essere presente nell'ordine di riferimento
`qty`	number	Quantità del prodotto da restituire. Deve essere numerico, ≥ 1 e ≤ quantità acquistata.

POST/api/adp/egress/create-refunds

Headers: Autenticazione

Query Params Parametri non presenti

Body Request

{
    "action": "execute",
    "messages": [
{
    "msgId": "640ee776f545844f1472f0bc",
    "msg": {
    "orderName": "#1206",
    "externalId": "7463784hnd",
    "status": "confirmed",
    "reason": "returned",
    "shippingRefund": false,
    "items": [
{
    "sku": "678790bb08755-green-S",
    "qty": 3
},
{
    "sku": "A1113",
    "qty": 2
}
    ]
},
    "meta": {}
}
    ],
    "requestId": "da7314de6b50407c9bf1b99acdadf65f",
    "meta": {}
}

Il body della risposta è compatibile con Flowlyze.

Per ogni messaggio inviato sarà restituito l'esito, l'id del messaggio e la data di risposta.

Body Response 200 OK

{
    "requestId": "da7314de6b50407c9bf1b99acdadf65f",
    "isAsync": false,
    "messages": [
{
    "msgId": "640ee776f545844f1472f0bc",
    "status": "Success",
    "date": "2025-10-13T10:47:44+00:00"
}
    ]
}

Se durante il processo di creazione/aggiornamento del reso avvenisse un errore, il messaggio di risposta riporterà il messaggio di errore ottenuto, come nell'esempio sottostante.

È comunque presente un meccanismo di rollback, pertanto se si verifica un errore, lo stato del sistema viene ripristinato.

Body Response 400 Bad Request

{
    "requestId": "da7314de6b50407c9bf1b99acdadf65f",
    "isAsync": false,
    "messages": [
{
    "msgId": "640ee776f545844f1472f0bc",
    "status": "Error",
    "date": "2025-10-13T10:47:44+00:00",
    "errorMessage": "Error on creation"
}
    ]
}

Create Fulfillments

Version ≥ 3.8

La chiamata consente di creare uno o più fulfillment a partire da un ordine esistente.
La struttura del body della richiesta deve seguire l’esempio fornito.

Permessi Ruolo o Utente

Permesso generale per accesso alla risorsa: Objects
Permesso per l'accesso al tipo di dataobject: SalesOrder

Struttura dei Messaggi

Per ogni messaggio è possibile:

Specificare l’ordine da cui partire per creare il fulfillment.
Specificare il fulfillmentId
Impostare se avvisare il cliente
Specificare il magazzino
Specificare il corriere
Specificare il numero di tracciamento
Specificare la url per il tracciamento
Specificare la data di spedizione
Specificare se recuperare tutti i prodotti in automatico
Elencare i prodotti specificando le quantità da spedire

Dettaglio dei Prodotti

Per ciascun prodotto, è possibile configurare i seguenti campi:

Campo	Tipo	Descrizione
`sku`	string	Codice di riferimento del prodotto. Deve essere presente nell'ordine di riferimento
`qty`	number	Quantità del prodotto da spedire. Deve essere numerico, ≥ 1.

warning

Se il flag fulfillAllItems è impostato a true allora l'elenco dei prodotti non verrà utilizzato

POST/api/adp/egress/create-fulfillments

Headers: Autenticazione

Query Params Parametri non presenti

Body Request

{
    "action": "execute",
    "messages": [
{
    "msgId": "640ee776f545844f1472f0bc",
    "msg": {
    "orderNumber": "#1206",
    "fulfillmentId": "123457",
    "notifyCustomer": false,
    "fulfillAllItems": false,
    "lineItems": [
{
    "sku": "0980309917",
    "qty": 1
},
{
    "sku": "0980309918",
    "qty": 2
}
    ],
    "warehouseCode": "AR",
    "trackingNumber": "123123",
    "carrierName": "GLS",
    "trackingUrl": "https://www.asd.asd/asdasd?asd=asdasd",
    "shipmentDate": "2025-01-15T10:29:59+00:00"
},
    "meta": {}
}
    ],
    "requestId": "da7314de6b50407c9bf1b99acdadf65f",
    "meta": {}
}

Il body della risposta è compatibile con Flowlyze.

Per ogni messaggio inviato sarà restituito l'esito, l'id del messaggio e la data di risposta.

Body Response 200 OK

{
    "requestId": "da7314de6b50407c9bf1b99acdadf65f",
    "isAsync": false,
    "messages": [
{
    "msgId": "640ee776f545844f1472f0bc",
    "status": "Success",
    "date": "2025-10-13T10:47:44+00:00"
}
    ]
}

Se durante il processo di creazione del fulfillment avvenisse un errore, il messaggio di risposta riporterà il messaggio di errore ottenuto, come nell'esempio sottostante.

È comunque presente un meccanismo di rollback, pertanto se si verifica un errore, lo stato del sistema viene ripristinato.

Body Response 400 Bad Request

{
    "requestId": "da7314de6b50407c9bf1b99acdadf65f",
    "isAsync": false,
    "messages": [
{
    "msgId": "640ee776f545844f1472f0bc",
    "status": "Error",
    "date": "2025-10-13T10:47:44+00:00",
    "errorMessage": "Error on creation"
}
    ]
}

Update Stocks

Version ≥ 3.8

La chiamata consente di creare o aggiornare i ProductStock.

Permessi Ruolo o Utente

Permesso generale per accesso alla risorsa: Objects
Permesso per l'accesso al tipo di DataObject: ProductStock

POST/api/adp/egress/update-stocks

Headers: Autenticazione

Query Params Parametri non presenti

Body Request

{
    "action": "execute",
    "messages": [
{
    "msgId": "640ee776f545844f1472f0bc",
    "msg": {
    "productFieldName": "sku",
    "productFieldValue": "0004BK",
    "onHandQuantity": 10,
    "warehouseCode": "AR",
    "otherFieldOnProductStock": "otherValue"
}
},
{
    "msgId": "640ee776f545844f1472f0ba",
    "msg": {
    "productFieldName": "sku",
    "productFieldValue": "0004SV",
    "onHandQuantity": 9,
    "warehouseCode": "MIL"
}
}
    ],
    "requestId": "da7314de6b50407c9bf1b99acdadf65f",
    "meta": {}
}

Il body della risposta è compatibile con Flowlyze.

Per ogni messaggio inviato sarà restituito l'esito, l'id del messaggio e la data di risposta.

Body Response 200 OK

{
    "requestId": "da7314de6b50407c9bf1b99acdadf65f",
    "isAsync": false,
    "messages": [
{
    "msgId": "640ee776f545844f1472f0bc",
    "status": "Success",
    "date": "2025-10-13T10:47:44+00:00"
}
    ]
}

Body Response 400 Bad Request

{
    "requestId": "da7314de6b50407c9bf1b99acdadf65f",
    "isAsync": false,
    "messages": [
{
    "msgId": "640ee776f545844f1472f0bc",
    "status": "Error",
    "date": "2025-10-13T10:47:44+00:00",
    "errorMessage": "Error on creation"
}
    ]
}

Upsert Sales Order​

Upsert Reso​

Create Refund​

Create Fulfillments​

Update Stocks​

Upsert Sales Order

Upsert Reso

Create Refund

Create Fulfillments

Update Stocks