Versione API: v0

Cos'è l'API Gestito dal venditore?

Utilizza l'API Merchant Fulfillment per creare applicazioni per consentire ai venditori di utilizzare i servizi Buy Shipping di Amazon per acquistare la spedizione per ordini non Prime e Prime.

Puoi creare applicazioni in grado di:

• Visualizzare l'anteprima delle offerte dei servizi di spedizione in base ai requisiti di spedizione, come la data di spedizione, la data di arrivo prevista, le dimensioni, il peso del pacco e altro ancora.
• Crea spedizioni in base alle offerte dei servizi di spedizione selezionate dal venditore.
• Paga automaticamente la spedizione tramite il servizio API.
• Ricevi e stampa le etichette di spedizione.

📘

Controlla i ruoli che hai collegato al tuo profilo

Il tuo accesso ai dati SP-API Amazon dipende dai ruoli che hai collegato al tuo profilo sviluppatore e alla tua applicazione. Per ulteriori informazioni, consulta Ruoli nell'API per i partner di vendita.

Terminologia

Tutorial 1: gestisci gli ordini Prime e non Prime gestiti dal venditore

Amazon consiglia di utilizzare questo flusso di lavoro del servizio Merchant Fulfillment per evadere gli ordini Prime gestiti dal venditore. Questo flusso di lavoro è pensato per integrare un sistema di evasione degli ordini. Il sistema di evasione degli ordini recupera i report sugli ordini pianificati che utilizzano il servizio Reports. Gli ordini in arrivo che non vengono evasi utilizzando il flusso di lavoro qui descritto devono essere evasi dal venditore utilizzando un metodo diverso.

Prerequisiti

Per completare questo tutorial, hai bisogno di:

• Autorizzazione dal partner di vendita per il quale stai effettuando chiamate. Per ulteriori informazioni, vedi Autorizzazione delle applicazioni API per i partner di vendita.
• Approvazione per il Ruolo di spedizione diretta al consumatore (con restrizioni) nel tuo profilo sviluppatore.
• Il ruolo Spedizione diretta al consumatore (con restrizioni) selezionato nella pagina di registrazione dell'app per la tua applicazione.
• I venditori che utilizzano un'applicazione sviluppata in base a questo flusso di lavoro devono aggiungere queste colonne ai report sugli ordini. Possono utilizzare l'area delle colonne opzionali di Add or remove order report columns in Seller Central.

❗️

Importante

I report sugli ordini XML in arrivo devono contenere IsPrime e LatestShipDate. I report sugli ordini in formato flat file in arrivo devono contenere is-prime e latest-ship-date.

Fase 1. Identifica gli ordini e recupera le informazioni

Identifica nuovi ordini monitorando ORDER_CHANGE notifiche. Per abbonarsi alle notifiche MFN, consulta Tutorial 5: iscriviti alle notifiche MFN. In alternativa, puoi identificare i nuovi ordini dai report sugli ordini in entrata.

Recupera le informazioni sull'ordine tramite l'API Orders. Gli ordini Prime hanno IsPrime attributo contrassegnato come true. Assicurarsi che FulfillmentChannels l'attributo è MFN.

Non usare l'attributo FulfillmentServiceLevel o la colonna ship-service-level nei report sugli ordini per identificare gli ordini Prime.

Esempio di codice:

Passaggio 2. Determina l'ultima data di spedizione per gli ordini Prime

Usa l'attributo LatestShipDate o la colonna latest-ship-date da un report sugli ordini in formato file di testo per determinare la data entro la quale gli ordini Prime devono essere spediti.

Passaggio 3. Controlla l'inventario e convalida l'ordine

Controlla il numero di inventario e assicurati che l'ordine ricevuto sia pronto per essere gestito.

Esempio di codice:

Passaggio 4. Ricevi offerte per i servizi di spedizione

Chiama il getEligibleShipmentServices operazione per ottenere le offerte di servizi di spedizione per gli ordini identificati in Fase 1, quindi selezionane uno che corrisponde alle tue priorità (ad esempio, il più economico o il più veloce).

📘

Cose da fare e da non fare nell'evasione degli ordini Prime e non Prime gestiti dal venditore

• Usa il LatestShipDate attributo dall'API Orders o dal latest-ship-date valore dal rapporto sugli ordini per ShipDate parametro.
• Non specificare il parametro MustArriveByDate, in quanto ciò limiterà inutilmente il numero di offerte per i servizi di spedizione che vengono riportate.
• Salva il ShippingServiceId valore derivante da ciascuna offerta di servizi di spedizione restituita. Lo utilizzerai per le successive chiamate al createShipment operazione quando si creano spedizioni per offerte di servizi di spedizione specifici.
• Controlla gli elementi inclusi ed esclusi Benefits prima di selezionare un'offerta di servizio di spedizione.

Esempi di codice:

Fase 5. (Facoltativo) Dichiarare merci pericolose

Se il tuo ordine contiene merci pericolose, queste devono essere dichiarate in modo che possano essere gestite correttamente. Gli attributi relativi alle merci pericolose vengono raccolti su ogni articolo. In qualità di spedizioniere, devi fornire questi attributi. Amazon non fornisce un modo per trovare questi attributi per il tuo articolo.

📘

Nota

Alcuni corrieri hanno requisiti aggiuntivi per la spedizione di merci pericolose. Rivolgiti al corriere per assicurarti che le tue spedizioni soddisfino i suoi requisiti.

Richiesta

L'esempio seguente è una richiesta per Amazon Shipping che include gli attributi relativi alle merci pericolose. Per ulteriori informazioni su ciascun attributo, consulta la Riferimento alla Merchant Fulfillment API v0.

Esempio di richiesta

{
    "ShipmentRequestDetails": {
        "AmazonOrderId": "903-3489051-5871062",
        "ItemList": [{
            "OrderItemId": "6220427528165",
            "Quantity": 1,
            "IsHazmat": true,
            "LiquidVolume": {
                "Unit": "C",
                "Value": 3
            },
            "DangerousGoodsDetails": {
                "UnitedNationsRegulatoryId": "UN1090",
                "TransportationRegulatoryClass": "3",
                "PackingGroup": "III",
                "PackingInstruction": "PI965_SECTION_IA"
            }
        }],
        "ShipFromAddress": {
            "Name": "John Doe",
            "AddressLine1": "300 Turnbull Ave",
            "Email": "jdoeasdfllkj@yahoo.com",
            "City": "Detroit",
            "StateOrProvinceCode": "MI",
            "PostalCode": "48123",
            "CountryCode": "US",
            "Phone": "7132341234"
        },
        "PackageDimensions": {
            "Length": 10.25,
            "Width": 10.25,
            "Height": 10.25,
            "Unit": "inches"
        },
        "Weight": {
            "Value": 10.25,
            "Unit": "oz"
        },
        "ShippingServiceOptions": {
            "DeliveryExperience": "DeliveryConfirmationWithoutSignature",
            "CarrierWillPickUp": false,
            "CarrierWillPickUpOption": "NoPreference"
        }
    }
}

Fase 6. Crea una spedizione

Dopo aver scelto il servizio di spedizione più adatto al tuo caso d'uso, chiama il createShipment operazione per una delle offerte di servizi di spedizione restituite nella fase precedente.

Utilizza i seguenti valori dei parametri:

• ShipmentRequestDetails: Usa gli stessi valori che hai incluso nel tuo getEligibleShipmentServices chiama Fase 4.

🚧

Importante

Assicurati di includere gli attributi relativi alle merci pericolose per il tuo articolo (consulta Fase 5). È necessario dichiarare le merci pericolose in modo che possano essere gestite correttamente.

• ShippingServiceId: Utilizza il valore associato a questa offerta di servizi di spedizione.

Le createShipment l'operazione avvia la procedura di pagamento per la spedizione, che detrae dall'account venditore Amazon del venditore e conferma la spedizione.

📘

Salva l'elenco degli articoli e l'ID di spedizione

Salva il ShipmentId valore restituito da createShipment operazione. Se il venditore desidera stampare una nuova etichetta, annullare una spedizione o controllare lo stato della spedizione in un secondo momento, ShipmentId viene utilizzato per identificare la spedizione. Salva l'elenco degli articoli insieme a ciascun ID di spedizione.

Esempio di codice:

Fase 7. Estrarre e stampare l'etichetta di spedizione

Estrarre l'etichetta di spedizione dal Label attributo restituito da createShipment operazione. Stampa o conserva l'etichetta di spedizione.

Per ulteriori informazioni, fare riferimento a Tutorial 3: Manipolare le etichette di spedizione.

Esempi di codice:

Fase 8. Crea spedizioni per gli ordini rimanenti

Ripetere Fasi 3 attraverso 5 fino a quando non avrai creato le spedizioni per gli ordini identificati in Fase 1.

Tutorial 2: Annullare una spedizione

Questo tutorial mostra come aggiungere funzionalità al flusso di lavoro descritto in Come gestire gli ordini Prime gestiti dal venditore.

Passaggio 1. Chiama l'operazione cancelShipment

Chiama il cancelShipment operazione e specificare ShipmentId valore della spedizione che desideri annullare.

Ciò restituisce i dettagli di una spedizione, che include lo stato della spedizione. Potrebbe anche restituire uno o più errori imprevisti verificatisi durante il cancelShipment operazione.

Passaggio 2. (Opzionale) Verifica lo stato della spedizione annullata

1. Chiama il getShipment operazione e specificare ShipmentId valore per la spedizione annullata.
2. Ottieni lo stato di annullamento dall'elemento di stato restituito da getShipment operazione.

❗️

Errori

Il servizio restituisce LabelCancelWindowExpired errore se il periodo di tempo assegnato per l'annullamento di un'etichetta è scaduto. Fare riferimento a Codici di errore.

Tutorial 3: Manipolare le etichette di spedizione

Le createShipment e getShipment le operazioni restituiscono un file di etichetta di spedizione in formato PDF, PNG o ZPL, a seconda del corriere. Amazon comprime i dati del documento prima di restituirli come stringa con codifica Base64.

Estrai i dati del documento da un file compresso

1. Decodifica la stringa con codifica Base64.
2. Salva la stringa decodificata con un .gzip estensione.
3. Estrai il file PDF, PNG o ZPL dal file GZIP.

createShipment e getShipment restituisce anche un hash MD5 con codifica Base64 per convalidare i dati del documento.

Ristampa un'etichetta di spedizione

1. Chiama il getShipment funzionamento e includere ShipmentId per la spedizione che richiede l'etichetta di spedizione.
2. Estrarre e stampare l'etichetta di spedizione dal FileContents elemento che viene restituito da getShipment operazione.

Tutorial 4: Includi dati di input aggiuntivi per il venditore

Le getAdditionalSellerInputs l'operazione restituisce un elenco di input aggiuntivi richiesti al venditore per acquistare la spedizione per alcuni servizi di spedizione. È richiesto solo per i servizi di spedizione che richiedono input aggiuntivi da parte del venditore.

Passaggio 1. Determina se il servizio di spedizione richiede input aggiuntivi da parte del venditore

1. Chiama l'operazione getEligibleShipmentServices.
2. Recupera l'elenco dei ShippingServices restituito dall'operazione.
3. Verificare la presenza di RequiresAdditionalSellerInputs attributo.
4. Se RequiresAdditionalSellerInputs è true, significa che il servizio di spedizione richiede input aggiuntivi da parte del venditore.

Passaggio 2. Chiama l'operazione getAdditionalSellerInputs

Se il servizio di spedizione richiede ulteriori input da parte del venditore, chiama il getAdditionalSellerInputs funzionamento e includono tutti i parametri richiesti. La risposta include un elenco di parametri obbligatori che un venditore deve includere se desidera acquistare servizi di spedizione.

Passaggio 3. Rivedi gli input aggiuntivi richiesti dal venditore

1. Esamina la risposta del getAdditionalSellerInputs operazione.
2. Identifica gli input aggiuntivi specifici richiesti dal venditore.

Passaggio 4. Fornisci gli input richiesti dal venditore

1. Raccogli le informazioni necessarie in base agli input aggiuntivi del venditore identificati nella risposta.
2. Assicurati che le informazioni fornite soddisfino i requisiti di sintassi specificati nella risposta.
3. Prepara gli input richiesti dal venditore per il passaggio successivo.

Passaggio 5. Crea la spedizione

1. Se gli input richiesti dal venditore vengono raccolti e preparati, chiama il createShipment operazione.
2. Utilizza i parametri necessari e gli input del venditore con createShipment operazione.
3. Segui i requisiti di sintassi appropriati per gli input del venditore nel getAdditionalSellerInputs risposta.

Passaggio 6. (Opzionale) Recupera i valori salvati

Le getAdditionalSellerInputs l'operazione restituisce valori salvati precedentemente forniti ad Amazon. Per accedere a questi valori salvati, esamina la risposta di getAdditionalSellerInputs operazione.

Tutorial 5: Iscriversi alle notifiche della Rete logistica del venditore

Puoi usare API per le notifiche dei partner di vendita per iscriversi alle notifiche pertinenti all'attività di un partner di vendita. Con questa API, puoi creare una destinazione per ricevere, sottoscrivere ed eliminare le sottoscrizioni alle notifiche. Invece di richiedere informazioni, la tua applicazione può ricevere informazioni direttamente da Amazon quando un evento attiva una notifica a cui sei iscritto.

🚧

Importante

I venditori possono abbonarsi al ORDER_CHANGE notifica, che viene inviata ogni volta che si verifica una modifica dello stato di disponibilità dell'ordine.

Le MFN_ORDER_STATUS_CHANGE e ORDER_STATUS_CHANGE i tipi di notifica sono stati rimossi. Aggiorna le tue applicazioni per utilizzare il ORDER_CHANGE notifica. [ORDER_CHANGE] (https://developer-docs.amazon.com/sp-api/docs/notifications-api-v1-use-case-guide#order_change) invia un payload a livello di ordine ogni volta che c'è una modifica importante nell'ordine. Le modifiche importanti includono le modifiche allo stato dell'ordine e le cancellazioni richieste dall'acquirente. Per informazioni dettagliate sulle date di obsolescenza delle SP-API, consulta la tabella delle deprezzazioni.

Fase 1. Abbonati al ORDER_CHANGE notifica

Per configurare e abbonarsi al ORDER_CHANGE notifica, segui il Tutorial SQS sull'API delle notifiche. La figura seguente fornisce una panoramica illustrata del tutorial.

Passaggio 2. Esegui il polling della coda per recuperare gli ultimi ORDER_CHANGE messaggi

1. Recupera l'URL della coda: Connettiti al servizio SQS e recupera l'URL della coda che riceve il ORDER_CHANGE messaggi. Questo URL identifica in modo univoco la coda e viene utilizzato per interagire con essa.
2. Configurare i parametri di polling: Rivedi i parametri di polling per determinare con quale frequenza e quanti messaggi recuperare alla volta. Ciò include il tempo di attesa tra i successivi tentativi di polling e il numero massimo di messaggi da recuperare in ogni richiesta.
3. Sondate la coda: Per interrogare la coda, invia le richieste per recuperare i messaggi. Usa il ReceiveMessage operazione per recuperare i messaggi dalla coda. Quando si chiama questa operazione, è possibile specificare l'URL della coda, il numero massimo di messaggi da recuperare e altri parametri opzionali, come il timeout di visibilità.

In alternativa, puoi configurare mappatura della sorgente degli eventi per richiamare automaticamente una funzione Lambda quando arrivano nuovi messaggi nella coda SQS. Per ulteriori informazioni sulla mappatura delle sorgenti degli eventi, fare riferimento a Tutorial: Usare Lambda con Amazon SQS.
4. Elabora i messaggi: Quando ricevi i messaggi, puoi elaborarli in base ai requisiti della tua applicazione. Nel caso di ORDER_CHANGE messaggi dall'SP-API, è possibile estrarre le informazioni pertinenti, come l'ID dell'ordine, i dettagli della modifica dello stato e i timestamp.
5. Elimina i messaggi elaborati: Dopo che ogni messaggio è stato elaborato con successo, assicurati di eliminarlo dalla coda con il DeleteMessage operazione fornita da SQS. Questo passaggio garantisce che i messaggi elaborati vengano rimossi dalla coda e non vengano recuperati nuovamente nei successivi tentativi di polling.

Passaggio 3. Elabora le informazioni sull'ordine e chiama i servizi di spedizione

La notifica ORDER_CHANGE riporta informazioni di alto livello relative all'ordine, come OrderId, OrderItemId e il OrderStatus. Per saperne di più sugli attributi che possono essere riportati, consulta le notifiche ORDER_CHANGE.

Per automatizzare il processo di evasione degli ordini, devi:

• Controllare i messaggi di notifica che hanno un OrderStatus di UpComing, Pending o Unshipped e verificare che MFN sia all'interno dell'attributo FulfillmentChannel.
• Recuperare le informazioni sull'ordine e sulla spedizione tramite l'operazione getOrder.
• Trasmettere queste informazioni all'operazione getEligibileShipmentServices e seguire i passaggi nel Tutorial 1.

Codici di errore

La tabella seguente descrive i codici di errore Merchant Fulfillment.