Hub per sviluppatoriStato dell'APISupporto

Guida ai casi d'uso dell'API Ordini v0

Migliora la sincronizzazione dell'inventario degli ordini, i flussi di lavoro e gli strumenti di reporting.

Versione API: v0

Cos'è l'API Ordini?

Usa il API per gli ordini per recuperare e inviare in modo programmatico le informazioni sugli ordini. Questa API è progettata per aiutare i partner di vendita a sviluppare applicazioni personalizzate veloci e flessibili che facilitano la sincronizzazione degli ordini, la ricerca degli ordini e gli strumenti di supporto decisionale basati sulla domanda.

📘

Nota

Gli ordini risalenti a più di due anni non verranno visualizzati nella risposta API, ad eccezione dei marketplace di SG, JP e AU, che supportano gli ordini dal 2016 in poi.

Per informazioni sull'autenticazione e l'autorizzazione, fare riferimento a Autorizzazione delle applicazioni API dei partner di vendita. Per informazioni sugli ordini regolamentati, consulta la Ordini regolamentati guida.

Caratteristiche principali

  • Recupera le informazioni sugli ordini con criteri di filtro: Il getOrders il funzionamento dell'API Orders restituisce gli ordini creati o aggiornati durante l'intervallo di tempo o altri criteri di filtro indicati dai parametri specificati. Se NextToken è presente, viene utilizzato per recuperare gli ordini anziché altri criteri.
  • Recupera le informazioni sull'ordine specificato: l'operazione getOrder dell'API Ordini restituisce le informazioni sull'ordine specificato.
  • Recupera le informazioni sugli articoli dell'ordine per l'ordine specificato: l'operazione getOrderItems dell'API Ordini restituisce informazioni dettagliate sugli articoli dell'ordine per l'ordine specificato. Se viene fornito NextToken, viene utilizzato per recuperare la pagina successiva degli articoli dell'ordine.
  • Conferma la spedizione per l'ordine specificato: l'operazione confirmShipment dell'API Ordini conferma lo stato di spedizione per un ordine specificato. Può essere utilizzata anche per modificare i dettagli di spedizione degli ordini che sono stati spediti.

Tutorial 1: Recuperare le informazioni sugli ordini con criteri di filtro

L'operazione getOrders dell'API Ordini restituisce gli ordini creati o aggiornati durante l'intervallo di tempo o altri criteri di filtro indicati dai parametri specificati. Se NextToken è presente, verrà utilizzato per recuperare gli ordini al posto di altri criteri.

🚧

Avvertenza

L'operazione getOrders presenta un ritardo sistematico nel recupero dei dati. I dati più aggiornati sugli ordini saranno disponibili 2 minuti dopo la creazione o l'ultimo aggiornamento dell'ordine. Per assicurarti di recuperare i dati degli ultimi ordini, chiama l'operazione 2 minuti dopo la creazione o l'aggiornamento dell'ordine.

Prerequisiti

Per completare correttamente questo tutorial, devi avere:

Per accedere alle informazioni sull'acquirente e sull'indirizzo di spedizione, devi:

Richiesta getOrders

Chiama l'operazione getOrders.

Parametri di query

NomeDescrizioneObbligatorio
CreatedAfterUna data utilizzata per selezionare gli ordini creati dopo (o al momento) di un'ora specificata. Vengono restituiti solo gli ordini effettuati dopo l'ora specificata. Devi fornire il parametro CreatedAfter o il parametro LastUpdatedAfter. Se entrambi sono vuoti, la chiamata non è valida.No
CreatedBeforeUna data utilizzata per selezionare gli ordini creati prima (o in) un'ora specificata. Vengono restituiti solo gli ordini effettuati prima dell'ora specificata. La data deve essere inserita ISO 8601 formato.No
LastUpdatedAfterUna data utilizzata per selezionare gli ordini che sono stati aggiornati l'ultima volta dopo (o in) un'ora specificata. Per aggiornamento si intende qualsiasi modifica dello stato dell'ordine, inclusa la creazione di un nuovo ordine. Include gli aggiornamenti effettuati da Amazon e dal venditore. La data deve essere inserita ISO 8601 formato. È necessario fornire o CreatedAfter parametro o LastUpdatedAfter parametro. Se entrambi sono vuoti, la chiamata non è valida.No
LastUpdatedBeforeUna data utilizzata per selezionare gli ordini che sono stati aggiornati l'ultima volta prima (o in) un'ora specificata. Per aggiornamento si intende qualsiasi modifica dello stato dell'ordine, inclusa la creazione di un nuovo ordine. Include gli aggiornamenti effettuati da Amazon e dal venditore. La data deve essere inserita ISO 8601 formato.No
OrderStatusesUn elenco di valori OrderStatus usati per filtrare i risultati.

Valori possibili:
- PendingAvailability (Questo stato è disponibile solo per i preordini. L'ordine è stato effettuato, il pagamento non è stato autorizzato e la data di rilascio dell'articolo è nel futuro).
- Pending (L'ordine è stato effettuato ma il pagamento non è stato autorizzato.)
- Unshipped (Il pagamento è stato autorizzato e l'ordine è pronto per la spedizione, ma nessun articolo dell'ordine è stato spedito.)
- PartiallyShipped (Uno o più articoli dell'ordine, ma non tutti, sono stati spediti.)
- Shipped (Tutti gli articoli dell'ordine sono stati spediti.)
- InvoiceUnconfirmed (Tutti gli articoli dell'ordine sono stati spediti. Il venditore non ha ancora confermato ad Amazon che la fattura è stata spedita all'acquirente.)
- Canceled (L'ordine è stato annullato.)
- Unfulfillable (L'ordine non può essere gestito. Questo stato si applica solo agli ordini con gestione multicanale.)
No
MarketplaceIdsUn elenco di MarketplaceId valori. Utilizzato per selezionare gli ordini che sono stati effettuati nel marketplaces.br specificato>
Fare riferimento a ID del Marketplace per un elenco completo di marketplaceId valori.
Numero massimo : 50
FulfillmentChannelsUn elenco che indica come è stato gestito un ordine. Filtra i risultati per canale di gestione. Valori possibili: AFN (Rete logistica di Amazon); MFN (Rete logistica del venditore).No
PaymentMethodsUn elenco dei valori dei metodi di pagamento. Utilizzato per selezionare gli ordini pagati utilizzando i metodi di pagamento specificati. Valori possibili: Pagamento alla consegna (contrassegno); CVS (pagamento in negozio); Altro (qualsiasi metodo di pagamento diverso da COD o CVS).No
BuyerEmailL'indirizzo e-mail di un acquirente. Utilizzato per selezionare gli ordini che contengono l'indirizzo e-mail specificato.No
SellerOrderIdUn identificativo di ordine specificato dal venditore. Utilizzato per selezionare solo gli ordini che corrispondono all'identificativo di ordine. Se è specificato SellerOrderId, non possono essere specificati FulfillmentChannels, OrderStatuses, PaymentMethod, LastUpdatedAfter, LastUpdatedBefore e BuyerEmail.No
MaxResultsPerPageUn numero che indica il numero massimo di ordini che possono essere restituiti per pagina. Il valore deve essere compreso tra 1 e 100. Valore predefinito 100.No
EasyShipShipmentStatusesUn elenco di valori EasyShipShipmentStatus. Utilizzato per selezionare ordini Easy Ship con stati che corrispondono ai valori specificati. Se è specificato EasyShipShipmentStatus, vengono restituiti solo gli ordini Amazon Easy Ship.

Valori possibili:
- PendingSchedule (Il pacco è in attesa dell'orario di ritiro.)
- PendingPickUp (Amazon non ha ancora ritirato il pacco dal venditore.)
- PendingDropOff (Il venditore consegnerà il pacco al corriere.)
- LabelCanceled (Il venditore ha annullato il ritiro.)
- PickedUp (Amazon ha ritirato il pacco dal venditore.)
- DroppedOff (Il pacco viene consegnato al corriere dal venditore.)
- AtOriginFC (Il pacco si trova presso il centro logistico di origine.)
- AtDestinationFC (Il pacco si trova presso il centro logistico di destinazione.)
- Delivered (Il pacco è stato consegnato.)
- RejectedByBuyer (Il pacco è stato rifiutato dall'acquirente.)
- Undeliverable (Il pacco non può essere consegnato.)
- ReturningToSeller (Il pacco non è stato consegnato e verrà restituito al venditore.)
- ReturnedToSeller (Il pacco non è stato consegnato ed è stato restituito al venditore.)
- Lost (Il pacco è stato smarrito.)
- OutForDelivery (Il pacco è in consegna.)
- Damaged (Il pacco è stato danneggiato dal corriere.)
No
ElectronicInvoiceStatusesUn elenco di valori ElectronicInvoiceStatus. Utilizzato per selezionare ordini con stati di fattura elettronica che corrispondono ai valori specificati.

Valori possibili:
- NotRequired (L'invio della fattura elettronica non è richiesto per questo ordine.)
- NotFound (La fattura elettronica non è stata inviata per questo ordine.)
- Processing (La fattura elettronica è in fase di elaborazione per questo ordine.)
- Errored (L'ultima fattura elettronica inviata è stata rifiutata per questo ordine.)
- Accepted (L'ultima fattura elettronica è stata inviata e accettata.)
No
NextTokenUn token di stringa restituito nella risposta alla tua richiesta precedente.No
AmazonOrderIdsUn elenco di valori AmazonOrderId. Un AmazonOrderId è un identificativo di ordine definito da Amazon, nel formato 3-7-7.
Numero massimo: 50
No
ActualFulfillmentSupplySourceIdIndica il valore consigliato sourceId da dove deve essere evaso l'ordine.No
IsISPUSe vero, questo ordine è contrassegnato per essere ritirato in un negozio anziché consegnato.No
StoreChainStoreIdL'identificativo della catena di negozi. Collegato a un negozio specifico di una catena di negozi.No

Esempio di richiesta

GET https://sellingpartnerapi-eu.amazon.com/orders/v0/orders? MarketplaceIds=ATVPDKIKX0DER &CreatedAfter=2020-10-10 &MaxResultPerPage=2

Risposta

Una risposta con esito positivo include quanto segue:

NomeDescrizioneObbligatorio
OrdersUn elenco di ordini.
Tipo: Order matrice
NextTokenSe presente e non vuoto, trasmette questo token di stringa nella richiesta successiva per restituire la pagina di risposta successiva.No
LastUpdatedBeforeUna data utilizzata per selezionare gli ordini che sono stati aggiornati l'ultima volta prima (o in) un'ora specificata. Per aggiornamento si intende qualsiasi modifica dello stato dell'ordine, inclusa la creazione di un nuovo ordine. Include gli aggiornamenti effettuati da Amazon e dal venditore. Tutte le date devono essere inserite ISO 8601 formato.No
CreatedBeforeUna data utilizzata per selezionare gli ordini creati prima (o in) un'ora specificata. Vengono restituiti solo gli ordini effettuati prima dell'ora specificata. La data deve essere inserita ISO 8601 formato.No

Esempi di risposta

Di seguito è riportato un esempio di risposta generale del getOrders operazione.

{ "payload": { "NextToken": "2YgYW55IGNhcm5hbCBwbGVhc3VyZS4", "Orders": [ { "AmazonOrderId": "902-3159896-1390916", "PurchaseDate": "2017-01-20T19:49:35Z", "LastUpdateDate": "2017-01-20T19:49:35Z", "OrderStatus": "Pending", "FulfillmentChannel": "SellerFulfilled", "NumberOfItemsShipped": 0, "NumberOfItemsUnshipped": 0, "PaymentMethod": "Other", "PaymentMethodDetails": [ "CreditCard", "GiftCertificate" ], "MarketplaceId": "ATVPDKIKX0DER", "ShipmentServiceLevelCategory": "Standard", "OrderType": "StandardOrder", "EarliestShipDate": "2017-01-20T19:51:16Z", "LatestShipDate": "2017-01-25T19:49:35Z", "IsBusinessOrder": false, "IsPrime": false, "IsAccessPointOrder": false, "IsGlobalExpressEnabled": false, "IsPremiumOrder": false, "IsSoldByAB": false, "IsIBA": false, "ShippingAddress": { "Name": "Michigan address", "AddressLine1": "1 Cross St.", "City": "Canton", "StateOrRegion": "MI", "PostalCode": "48817", "CountryCode": "US" }, "BuyerInfo": { "BuyerEmail": "user@example.com", "BuyerName": "John Doe", "BuyerTaxInfo": { "CompanyLegalName": "A Company Name" }, "PurchaseOrderNumber": "1234567890123" } } ] } }

Quando un ordine viene spedito a un indirizzo in Brasile, potresti ricevere anche campi relativi all'indirizzo aggiuntivi (ad esempio, StreetName, StreetNumber, Complement e Neighborhood), come mostrato nell'esempio seguente.

{ "ShippingAddress": { "Name": "Brazil address", "AddressLine1": "Street 9 450", "AddressLine2": "Suite 30 Central", "ExtendedFields": { "StreetName": "Street 9", "StreetNumber": "450", "Complement": "Suite 30", "Neighborhood": "Central" }, "City": "Rio de Janeiro", "StateOrRegion": "RJ", "PostalCode": "48817", "CountryCode": "BR" } }

Per ulteriori informazioni su quando gli indirizzi di spedizione contengono campi estesi, consulta la Order schema in Riferimento API v0 per gli ordini.

Per un elenco dei possibili campi estesi, fare riferimento a AddressExtendedFields nel Riferimento API v0 per gli ordini.

Tutorial 2: Recuperare le informazioni sull'ordine

Il tutorial mostra come usare il getOrder funzionamento dell'API Orders per recuperare le informazioni sugli ordini specificate.

Prerequisiti

Per completare correttamente questo tutorial, devi avere:

Per accedere alle informazioni sull'acquirente e sull'indirizzo di spedizione, devi:

Richiesta

Parametro Descrizione Obbligatorio
orderId Un identificativo d'ordine definito da Amazon, nel formato 3-7-7.

Tipo: stringa

Esempio di richiesta

GET https://sellingpartnerapi-eu.amazon.com/orders/v0/orders/205-1725759-9209952/

Risposta

Una risposta con esito positivo include quanto segue:

NomeDescrizioneObbligatorio
OrderInformazioni sull'ordine
Tipo: Order

Fai riferimento a Order nel riferimento API per i dettagli sui possibili oggetti e proprietà in un ordine.

Esempio di risposta

{ "payload": { "BuyerInfo": {}, "AmazonOrderId": "026-1520163-6049104", "EarliestShipDate": "2022-03-10T00:00:00Z", "SalesChannel": "Amazon.co.uk", "AutomatedShippingSettings": { "HasAutomatedShippingSettings": false }, "OrderStatus": "Canceled", "NumberOfItemsShipped": 0, "OrderType": "StandardOrder", "IsPremiumOrder": false, "IsPrime": false, "FulfillmentChannel": "MFN", "NumberOfItemsUnshipped": 0, "HasRegulatedItems": true, "IsReplacementOrder": false, "IsSoldByAB": false, "LatestShipDate": "2022-03-10T23:59:59Z", "ShipServiceLevel": "Std UK Dom_1", "IsISPU": false, "MarketplaceId": "A1F83G8C2ARO7P", "PurchaseDate": "2022-03-09T22:03:02Z", "IsAccessPointOrder": false, "IsBusinessOrder": false, "OrderTotal": { "CurrencyCode": "GBP", "Amount": "20.00" }, "PaymentMethodDetails": [ "Standard" ], "IsGlobalExpressEnabled": false, "LastUpdateDate": "2022-03-14T22:05:14Z", "ShipmentServiceLevelCategory": "Standard" } }

Tutorial 3: Recuperare informazioni dettagliate sull'articolo dell'ordine

Il tutorial mostra come usare il getOrderItems funzionamento dell'API Orders per recuperare le informazioni sugli ordini specificate.

Prerequisiti

Per completare correttamente questo tutorial, devi avere:

Per accedere alle informazioni sull'acquirente e sull'indirizzo di spedizione, devi:

Richiesta

Type Parametro Descrizione Obbligatorio
Path orderId Un identificativo d'ordine definito da Amazon, nel formato 3-7-7.

Tipo: stringa

Query NextToken Un token di stringa restituito nella risposta alla tua richiesta precedente.

Tipo: stringa

No

Esempio di richiesta

GET https://sellingpartnerapi-na.amazon.com/orders/v0/orders/902-9855239-8990202/orderItems

Risposta

Una risposta con esito positivo include quanto segue:

NomeDescrizioneObbligatorio
OrderItemsUn elenco degli articoli dell'ordine.
Tipo: OrderItem matrice
NextTokenSe presente e non vuoto, trasmette questo token di stringa nella richiesta successiva per restituire la pagina di risposta successiva.No
AmazonOrderIdUn identificativo d'ordine definito da Amazon, nel formato 3-7-7.

Esempio di risposta

{ "payload": { "OrderItems": [ { "TaxCollection": { "Model": "MarketplaceFacilitator", "ResponsibleParty": "Amazon Services, Inc." }, "ProductInfo": { "NumberOfItems": "1" }, "BuyerInfo": {}, "ItemTax": { "CurrencyCode": "USD", "Amount": "1.13" }, "QuantityShipped": 1, "BuyerRequestedCancel": { "IsBuyerRequestedCancel": "false", "BuyerCancelReason": "" }, "ItemPrice": { "CurrencyCode": "USD", "Amount": "11.00" }, "ASIN": "B004RKQM8I", "SellerSKU": "AN-M9GI-4QE5", "Title": "Sony MDR-ZX100 ZX Series Headphones (White)", "IsGift": "false", "ConditionSubtypeId": "Acceptable", "IsTransparency": false, "QuantityOrdered": 1, "PromotionDiscountTax": { "CurrencyCode": "USD", "Amount": "0.00" }, "ConditionId": "Used", "PromotionDiscount": { "CurrencyCode": "USD", "Amount": "0.00" }, "OrderItemId": "43345934312798" } ], "AmazonOrderId": "902-0300094-5705429" } }

Tutorial 4: Confermare una spedizione

Questo tutorial mostra come confermare una spedizione con l'operazione confirmShipment dopo aver ricevuto la notifica che l'ordine è pronto per essere gestito. Non sarà necessario confermare la spedizione se acquisti un'etichetta di spedizione tramite l'API di spedizione o l'interfaccia utente di acquisto e spedizione. L'operazione confirmShipment può essere utilizzata per tutti i casi d'uso supportati nei feed di gestione degli ordini, incluso il supporto di più numeri di spedizione per ordine. Per inviare più numeri di spedizione per pacco, dovrai inviare più richieste con lo stesso numero di ordine ma diversi numeri di riferimento del pacco.

Esempio:

Call OrderID PackageReferenceId
1a chiamata 902-0300094-570542 101
2a chiamata 902-0300094-570542 102

L'ID di riferimento del pacco supporta qualsiasi valore numerico positivo e serve a modificare una spedizione dopo averla confermata. Puoi inviare qualsiasi valore numerico come packageReferenceID e conserveremo i dati. Se devi apportare una modifica alla spedizione, invia un'altra operazione confirmShipment con lo stesso packageReferenceID. Gli altri dettagli della spedizione verranno modificati una volta completato l'invio. Se non inserisci alcun ID al momento dell'invio, Amazon assegnerà automaticamente un packageReferenceID.

Prerequisiti

Per completare correttamente questo tutorial, devi avere:

Se sei stato approvato per il ruolo Consegna diretta al consumatore (con restrizioni), avrai accesso all'operazione confirmShipment.

Passaggio 1. Conferma la spedizione di un ordine

Chiama l'operazione confirmShipment, passando i seguenti parametri:

Parametri del percorso

Parametro Descrizione Obbligatorio
orderId Un identificativo d'ordine definito da Amazon, nel formato 3-7-7.

Tipo: stringa

Parametri del corpo

NomeDescrizioneObbligatorio
packageDetailProprietà dei pacchi
Tipo PackageDetail
codCollectionMethodIl metodo di raccolta con pagamento alla consegna, supportato solo in Giappone.
Tipo CodCollectionMethod
No
marketplaceIdL'identificatore del marketplace non offuscato.
Tipo MarketplaceId

Esempio di richiesta

POST https://sellingpartnerapi-eu.amazon.com/orders/v0/orders/205-1725759-9209952/shipmentConfirmation { "marketplaceId": "ATVPDKIKX0DER", "codCollectionMethod": "", "packageDetail": { "packageReferenceId": "123", "carrierCode": "UPS", "carrierName": "UPS", "shippingMethod": "SHIPPING", "trackingNumber": "1Z86V8030385598957", "shipDate": "2022-11-30T16:15:30Z", "shipFromSupplySourceId": "057d3fcc-b750-419f-bbcd-4d340c60c430", "orderItems": [ { "orderItemId": "60696125413094", "quantity": 1 } ] } }

Risposta

Proprietà della risposta:

HTTP CodeDescrizioneSchema
204Operazione riuscita.
Intestazioni:
x-amzn-RateLimit-Limit (string): il limite di velocità (richieste al secondo) per questa operazione.
x-amzn-RequestId (string): l'identificatore univoco di riferimento della richiesta.
Nessun contenuto

Per i codici di stato degli errori, le descrizioni e gli schemi, fai riferimento a Conferma la risposta all'errore di spedizione.

🌟

Suggerimento

Per confermare più ordini, utilizza il API dei feed v2021-06-30 e passa il POST_ORDER_FULFILLMENT_DATA tipo di alimentazione. Per ulteriori informazioni, fare riferimento a Conferma più ordini tramite il feed di evasione degli ordini.

Passaggio 2. Modifica le informazioni di spedizione per un ordine

Dopo il passaggio 1, viene creato un pacco per l'ordine. Puoi comunque modificare le informazioni di spedizione come data di spedizione, corriere, servizio di spedizione (o metodo di spedizione), numero di spedizione (fornito dal corriere) chiamando di nuovo l'operazione confirmShipment.

Parametri che devono essere coerenti

Per assicurarti di modificare la stessa spedizione, non modificare i seguenti parametri.

Parametro Descrizione In
orderId Un identificativo d'ordine definito da Amazon, nel formato 3-7-7.

Tipo: stringa

Path
packageReferenceId Un identificativo fornito dal venditore che identifica in modo univoco un pacco nell'ambito di un ordine. È supportato solo un valore numerico positivo."

Tipo: stringa

PackageDetail
orderItemId L'identificativo univoco dell'articolo dell'ordine.

Tipo: stringa

ConfirmShipmentOrderItem
quantity La quantità dell'articolo.

Tipo: intero

ConfirmShipmentOrderItem

Esempio di richiesta

POST https://sellingpartnerapi-eu.amazon.com/orders/v0/orders/205-1725759-9209952/shipmentConfirmation { "marketplaceId": "ATVPDKIKX0DER", "codCollectionMethod": "", "packageDetail": { "packageReferenceId": "123", "carrierCode": "USPS", "carrierName": "USPS", "shippingMethod": "SHIPPING", "trackingNumber": "1Z86V8030385598957", "shipDate": "2022-11-30T20:15:30Z", "shipFromSupplySourceId": "057d3fcc-b750-419f-bbcd-4d340c60c430", "orderItems": [ { "orderItemId": "60696125413094", "quantity": 1 } ] } }

Risposta

Proprietà della risposta:

HTTP CodeDescrizioneSchema
204Operazione riuscita.
Intestazioni:
x-amzn-RateLimit-Limit (string): il limite di velocità (richieste al secondo) per questa operazione.
x-amzn-RequestId (string): l'identificatore univoco di riferimento della richiesta.
Nessun contenuto

Per i codici di stato degli errori, le descrizioni e gli schemi, fai riferimento a Risposte e schemi di errore.


Questa pagina ti è stata utile?