Guida ai casi d'uso dell'API Gestione logistica diretta per i fornitori v1
Help vendors in the direct fulfillment (DF) program use the Orders API to manage their direct fulfillment operations.
Versione API: v1
What is the Direct Fulfillment Orders API?
Using the Direct Fulfillment Orders API, vendors can receive purchase orders and send order acknowledgements.
Sono disponibili le seguenti operazioni:
Operazione | Metodo HTTP | Path | Descrizione |
---|---|---|---|
getOrders
|
GET | /vendor/directFulfillment/orders/v1/purchaseOrders |
Returns a list of purchase orders created during the time frame that you specify. You define the time frame using the createdAfter and createdBefore parameters. You must use both parameters. You can choose to get only the purchase order numbers by setting the includeDetails parameter to false. In that case, the operation returns a list of purchase order numbers. You can then call the getOrder operation to return the details of a specific order.Note: This is a restricted operation and therefore requires a Restricted Data Token (RDT) for authorization. For more information, refer to the Tokens API Use Case Guide. |
getOrder
|
GET | /vendor/directFulfillment/orders/v1/purchaseOrders /{purchaseOrderNumber} |
Returns purchase order information for the purchaseOrderNumber that you specify.Note: This is a restricted operation and therefore requires a Restricted Data Token (RDT) for authorization. For more information, refer to the Tokens API Use Case Guide. |
submitAcknowledgement
|
POST | /vendor/directFulfillment/orders/v1/acknowledgements |
Submits acknowledgements for one or more purchase orders. |
You can use the getOrders
operation to access orders created during a time frame that you specify (time range of seven days from a rolling window of the last six months, after the vendor went live on the API). You can also get detailed order information for specific orders using the getOrder
operation. You can then acknowledge the order using the submitAcknowledgement
operation.
Retrieving only order numbers
To retrieve order numbers without complete order details, use the
getOrders
operation withincludeDetails=false
as a query parameter. The default value for this parameter istrue
, so if you don't include this query parameter, you will get the full details of the purchase orders.
The following diagram shows the workflow using the Direct Fulfillment Orders APIs:
Direct Fulfillment customer data transmission
Vendors do not receive customer data such as name, address, or phone number for certain orders available through the getOrder
and getOrders
operations. Direct Fulfillment shares customer information directly on Amazon provided shipping labels. This applies to all shipments fulfilled by Amazon label only vendors and ATS-Small Parcel.
Customer name, address, and phone number are available if your operations require you to generate a label using a Direct Fulfillment Amazon carrier account. The information is also available to you if you use a vendor own label (VOL) or vendor own carrier (VOC) shipping label to fulfill the Direct Fulfillment order. If you generate your own AMXL shipping labels, you can access customer data.
Definitions
- Amazon label only vendor: Vendors who exclusively use Amazon provided shipping labels to fulfill all Direct Fulfillment orders.
- Amazon Transportation Services (ATS-Small Parcel): A carrier operated by Amazon.
The details for each operation are in the following sections.
getOrders
The getOrders
operation returns a list of order references (purchase order numbers) or complete order details for all orders which meet the criteria specified. If you only request order numbers, you can use each order number later with the getOrder
operation to get order details for a specific order.
Autorizzazione con token di dati con restrizioni
Si tratta di un'operazione soggetta a restrizioni, la cui autorizzazione richiede un token di dati con restrizioni. Per maggiori informazioni, consulta Guida ai casi d'uso dell'API Token.
You should use this API to get purchase orders available to you for fulfillment. Amazon recommends that vendors check for orders at least once per hour during business hours. Depending on your business volume, you can choose to check more frequently. You can return up to 100 orders in one API call. If there are more than 100 orders you can use the nextToken
value in the response to get the next set of orders.
Il seguente diagramma illustra il flusso di lavoro di integrazione per il recupero di ordini d'acquisto:
Richiesta getOrders
To return a list of purchase orders, call the getOrders
operation and pass the following parameters:
Parametri di query:
+Nome | Descrizione | Obbligatorio |
---|---|---|
shipFromPartyId |
The vendor warehouse identifier for the fulfillment warehouse. If not specified, the result will contain orders for all warehouses.
Tipo: stringa |
No |
status |
Returns only the purchase orders that match the specified status. If not specified, the result will contain orders that match any status.
Type: enum ( Status ) |
No |
limit | The limit to the number of purchase orders returned.
Minimo: 1 Massimo: 100 Type: integer (int64) |
No |
createdAfter |
Purchase orders that became available after this date and time will be included in the result. Must be in ISO-8601 date/time format.
Tipo: stringa (data-ora) |
Sì |
createdBefore |
Purchase orders that became available before this date and time will be included in the result. Must be in ISO-8601 date/time format.
Tipo: stringa (data-ora) |
Sì |
sortOrder |
Sort the list in ascending or descending order by order creation date.
Tipo: enum ( |
No |
nextToken |
Utilizzato per l'impaginazione quando ci sono più ordini rispetto al limite di dimensione dei risultati specificato. Il valore del token è restituito nella chiamata API precedente. Tipo: stringa |
No |
includeDetails |
When true, returns the complete purchase order details. Otherwise, only purchase order numbers are returned.
Tipo: stringa (booleana) Impostazione predefinita: |
No |
Esempio di richiesta:
GET https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/orders/v1/purchaseOrders?limit=2&createdAfter=2020-02-15T14:00:00-08:00&createdBefore=2020-02-20T00:00:00-08:00&sortOrder=DESC&includeDetails=true
getOrders Response
Una risposta con esito positivo include quanto segue:
Nome | Descrizione | Obbligatorio |
---|---|---|
pagination |
Se vengono restituiti più di 100 ordini, nella risposta per l'impaginazione viene restituito nextToken . Tipo: stringa |
No |
orders |
Includes details for the purchase order.
Type:
|
No |
Esempio di risposta:
{
"pagination": {
"nextToken": "MDAwMDAwMDAwMQ=="
},
"orders": [
{
"purchaseOrderNumber": "2JK3S9VC",
"orderDetails": {
"customerOrderNumber": "123-ABC",
"orderDate": "2020-02-20T13:51:00Z",
"shipmentDetails": {
"isPriorityShipment": false,
"isScheduledDeliveryShipment": false,
"isPslipRequired": true,
"isGift": false,
"shipMethod": "UPS_2ND",
"shipmentDates": {
"requiredShipDate": "2020-02-21T00:00:00Z",
"promisedDeliveryDate": "2020-02-24T00:00:00Z"
},
"messageToCustomer": "This shipment completes your order. You can always check the status of your orders from the \"Your Account\" link at the top of each page of our site.Thank you for shopping at Amazon.com"
},
"taxTotal": {
"taxLineItem": [
{
"taxRate": "0.1",
"taxAmount": {
"currencyCode": "USD",
"amount": "190"
},
"type": "TOTAL"
}
]
},
"sellingParty": {
"partyId": "999US"
},
"shipFromParty": {
"partyId": "ABCD"
},
"shipToParty": {
"name": "John Doe",
"attention": "John Doe",
"addressLine1": "123 Any Street",
"addressLine2": "Apt 5",
"city": "Any Town",
"stateOrRegion": "CA",
"postalCode": "94086",
"countryCode": "USA"
},
"billToParty": {
"partyId": "ABCD"
},
"items": [
{
"itemSequenceNumber": "00001",
"buyerProductIdentifier": "B07DFVDRAB",
"vendorProductIdentifier": "8806098286500",
"title": "LG 8 kg Inverter Wi-Fi Fully-Automatic Front Loading Washing Machine (FHT1408SWS, STS-VCM, Inbuilt Heater)",
"orderedQuantity": {
"amount": 1,
"unitOfMeasure": "EACH"
},
"netPrice": {
"currencyCode": "USD",
"amount": "500"
},
"taxDetails": {
"taxLineItem": [
{
"taxRate": "0.1",
"taxAmount": {
"currencyCode": "USD",
"amount": "50"
},
"type": "TOTAL"
}
]
}
},
{
"itemSequenceNumber": "00002",
"buyerProductIdentifier": "B07DFYF5AB",
"vendorProductIdentifier": "8806098286123",
"title": "LG 6.5 kg Inverter Fully-Automatic Front Loading Washing Machine (FHT1065SNW, Blue and White, Inbuilt Heater)",
"orderedQuantity": {
"amount": 2,
"unitOfMeasure": "EACH"
},
"netPrice": {
"currencyCode": "USD",
"amount": "700"
},
"taxDetails": {
"taxLineItem": [
{
"taxRate": "0.1",
"taxAmount": {
"currencyCode": "USD",
"amount": "140"
},
"type": "TOTAL"
}
]
}
}
]
}
}
]
}
getOrder
The getOrder
operation returns information about the purchase order that you specify using the purchase order number. The response includes complete purchase order information for the purchase order, including line item details, quantity, and cost.
Autorizzazione con token di dati con restrizioni
Si tratta di un'operazione soggetta a restrizioni, la cui autorizzazione richiede un token di dati con restrizioni. Per maggiori informazioni, consulta Guida ai casi d'uso dell'API Token.
You should use this API to get the details of specific orders returned by the getOrders
operation. You can also use this API to get details for any purchase order in the time range of seven days from a rolling window of the last six months after the vendor went live on the API.
The following diagram shows the integration workflow to retrieve a specific purchase order:
Requisiti aziendali specifici per paese
Funzionalità | India | Europa | Nord America |
---|---|---|---|
Net Cost | Conditional. Either net cost or list price. | Conditional. Either net cost or list price. | Conditional. Either net cost or list price. |
List Price | Conditional. Either net cost or list price. | Condizionale. Costo netto o prezzo di listino. | Conditional. Either net cost or list price. |
Ship From Party | The warehouse code assigned to the vendor. | The warehouse code assigned to the vendor. | The warehouse code assigned to the vendor. |
Selling Party | The vendor code assigned to the vendor. | The vendor code assigned to the vendor. | The vendor code assigned to the vendor. |
Ship To Party | The address of the customer. | The address of the customer. For Amazon label only vendors, certain fields will be replaced with the fictitious value 'XXXXX'. Refer to the Direct Fulfillment customer data transmission section for more information. | The address of the customer. For Amazon label only vendors, certain fields will be replaced with the fictitious value 'XXXXX'. Refer to the Direct Fulfillment customer data transmission |
Bill To Party | The address of the bill to entity. | The address of the bill to entity. | Not applicable. |
getOrder Request
To return information about a specific purchase order, call the getOrder
operation and pass the following parameter:
Parametro del percorso:
Nome | Descrizione | Obbligatorio |
---|---|---|
purchaseOrderNumber |
The order identifier for the purchase order that you want. Formatting Notes: alpha-numeric code.
Tipo: stringa |
Sì |
Esempio di richiesta:
GET https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/orders/v1/purchaseOrders/4Z32PABC
getOrder Response
Una risposta con esito positivo include quanto segue:
Nome | Descrizione | Obbligatorio |
---|---|---|
purchaseOrderNumber |
The purchase order number for this order. Formatting Notes: alpha-numeric code.
Tipo: stringa |
No |
orderDetails |
Purchase order details.
Tipo: |
No |
Esempio di risposta:
{
"purchaseOrderNumber": "2JK3S9VC",
"orderDetails": {
"customerOrderNumber": "123-ABC",
"orderDate": "2020-02-20T13:51:00Z",
"shipmentDetails": {
"isPriorityShipment": false,
"isScheduledDeliveryShipment": false,
"isPslipRequired": true,
"isGift": false,
"shipMethod": "UPS_2ND",
"shipmentDates": {
"requiredShipDate": "2020-02-21T00:00:00Z",
"promisedDeliveryDate": "2020-02-24T00:00:00Z"
},
"messageToCustomer": "This shipment completes your order. You can always check the status of your orders from the \"Your Account\" link at the top of each page of our site.Thank you for shopping at Amazon.com"
},
"taxTotal": {
"taxLineItem": [
{
"taxRate": "0.1",
"taxAmount": {
"currencyCode": "USD",
"amount": "190"
},
"type": "TOTAL"
}
]
},
"sellingParty": {
"partyId": "999US"
},
"shipFromParty": {
"partyId": "ABCD"
},
"shipToParty": {
"name": "John Doe",
"attention": "John Doe",
"addressLine1": "123 Any Street",
"addressLine2": "Apt 5",
"city": "San Jose",
"stateOrRegion": "Any Town",
"postalCode": "94086",
"countryCode": "USA"
},
"billToParty": {
"partyId": "ABCD"
},
"items": [
{
"itemSequenceNumber": "00001",
"buyerProductIdentifier": "B07DFVDRAB",
"vendorProductIdentifier": "8806098286500",
"title": "LG 8 kg Inverter Wi-Fi Fully-Automatic Front Loading Washing Machine (FHT1408SWS, STS-VCM, Inbuilt Heater)",
"orderedQuantity": {
"amount": 1,
"unitOfMeasure": "EACH"
},
"netPrice": {
"currencyCode": "USD",
"amount": "500"
},
"taxDetails": {
"taxLineItem": [
{
"taxRate": "0.1",
"taxAmount": {
"currencyCode": "USD",
"amount": "50"
},
"type": "TOTAL"
}
]
}
},
{
"itemSequenceNumber": "00002",
"buyerProductIdentifier": "B07DFYF5AB",
"vendorProductIdentifier": "8806098286123",
"title": "LG 6.5 kg Inverter Fully-Automatic Front Loading Washing Machine (FHT1065SNW, Blue and White, Inbuilt Heater)",
"orderedQuantity": {
"amount": 2,
"unitOfMeasure": "EACH"
},
"netPrice": {
"currencyCode": "USD",
"amount": "700"
},
"taxDetails": {
"taxLineItem": [
{
"taxRate": "0.1",
"taxAmount": {
"currencyCode": "USD",
"amount": "140"
},
"type": "TOTAL"
}
]
}
}
]
}
}
submitAcknowledgement
The submitAcknowledgement
operation allows vendors to accept or reject a purchase order for fulfillment. Amazon expects a complete acknowledgement, including all purchase order line items of the purchase order. If the vendor does not provide all line items of the purchase order in the acknowledgement, Amazon does not accept the partial acknowledgement.
Amazon expects the vendor to submit the acknowledgement as fast as possible, at the latest within 24 hours. The acknowledgement should be an accurate view of the actual shipment quantities and items.
Verifica delle conferme dell'ordine inviate correttamente
Vendors can verify the status of the original/updated version of the order acknowledgement using Vendor Central or using the Direct Fulfillment Transaction Management API. Allow the system to take up to 15 minutes to show the original/updated version after submission. If Vendor Central is not showing the correct values for the acknowledgement, open a Contact Us case in Vendor Central.
Il seguente diagramma illustra il flusso di lavoro di integrazione per la conferma degli ordini.
Requisiti aziendali
The following list is an example of the codes that can be used in the Amazon acknowledgement. Amazon and the vendor will mutually agree upon a list of codes that will be appropriate for their relationship.
Code & Description
- "00" Shipping 100 percent of ordered product
- "02" Canceled due to missing/invalid SKU
- "03" Canceled out of stock
- "04" Canceled due to duplicate Amazon Ship ID
- "05" Canceled due to missing/invalid Bill To Location Code
- "06" Canceled due to missing/invalid Ship From Location Code
- "07" Canceled due to missing/invalid Customer Ship to Name
- "08" Canceled due to missing/invalid Customer Ship to Address Line 1
- "09" Canceled due to missing/invalid Customer Ship to City
- "10" Canceled due to missing/invalid Customer Ship to State
- "11" Canceled due to missing/invalid Customer Ship to Postal Code
- "12" Canceled due to missing/invalid Customer Ship to Country Code
- "13" Canceled due to missing/invalid Shipping Carrier/Shipping Method
- "20" Canceled due to missing/invalid Unit Price
- "21" Canceled due to missing/invalid Ship to Address Line 2
- "22" Canceled due to missing/invalid Ship to Address Line 3
- "50" Canceled due to Tax Nexus Issue
- "51" Canceled due to Restricted SKU/Qty
- "53" Canceled due to USPS > $400
- "54" Canceled due to Missing AmazonShipID
- "55" Canceled due to Missing AmazonOrderID
- "56" Canceled due to Missing LineItemId
- "71" Canceled due to discontinued item
Amazon acknowledgement
Amazon expects an acknowledgement even if all the line items on the purchase order were invalid and did not produce an order or invoice.
Requisiti aziendali specifici per paese
There are no country specific requirements for order acknowledgements.
submitAcknowledgement Request
To submit order acknowledgements, call the submitAcknowledgement
operation and pass the following parameter:
Parametro del corpo:
Nome | Descrizione | Obbligatorio |
---|---|---|
orderAcknowledgements |
A list of one or more purchase orders.
Tipo:< |
Sì |
Esempio di richiesta:
POST https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/orders/v1/acknowledgements
{
"orderAcknowledgements": [
{
"purchaseOrderNumber": "2JK3S9VC",
"vendorOrderNumber": "ABC",
"acknowledgementDate": "2020-02-20T19:17:34.304Z",
"acknowledgementStatus": {
"code": "00",
"description": "Shipping 100 percent of ordered product"
},
"sellingParty": {
"partyId": "999US"
},
"shipFromParty": {
"partyId": "ABCD"
},
"itemAcknowledgements": [
{
"itemSequenceNumber": "00001",
"buyerProductIdentifier": "B07DFVDRAB",
"vendorProductIdentifier": "8806098286500",
"acknowledgedQuantity": {
"amount": 1,
"unitOfMeasure": "Each"
}
}
]
}
]
}
submitAcknowledgements Response
Una risposta con esito positivo include quanto segue:
Nome | Descrizione | Obbligatorio |
---|---|---|
ID transazione | GUID assigned by Amazon to identify this transaction. This value can be used with the Transaction Status API to return the status of this transaction.
Tipo: stringa |
Sì |
Esempio di risposta:
{
"transactionId": "20190827182357-8725bde9-c61c-49f9-86ac-46efd82d4da5"
}
Acknowledgement use cases
Articolo non valido in una voce dell'ordine d'acquisto
If the vendor receives an invalid product identifier in the purchase order, the vendor should reject the item with an acknowledgement code "02" and the "description" as "Canceled due to missing/invalid SKU".
{
"orderacknowledgements": [
{
"purchaseOrderNumber": "2JK3S9VC",
"vendorOrderNumber": "ABC",
"acknowledgementDate": "2020-02-20T19:17:34.304Z",
"acknowledgementStatus": {
"code": "02",
"description": "Canceled due to missing/invalid SKU"
},
"sellingParty": {
"partyId": "999US"
},
"shipFromParty": {
"partyId": "ABCD"
},
"items": [
{
"itemSequenceNumber": "1",
"buyerProductIdentifier": "B07DFVDRAB",
"vendorProductIdentifier": 8806098286500,
"acknowledgedQuantity": {
"amount": 1,
"unitOfMeasure": "Each"
}
}
]
}
]
}
Out of stock line item in the purchase order
If the vendor receives a product in the purchase order which is now out of stock, the vendor should reject the item with an acknowledgement code "03" and the "description" as "Canceled out of stock".
{
"orderacknowledgements": [
{
"purchaseOrderNumber": "2JK3S9VC",
"vendorOrderNumber": "ABC",
"acknowledgementDate": "2020-02-20T19:17:34.304Z",
"acknowledgementStatus": {
"code": "03",
"description": "Canceled out of stock"
},
"sellingParty": {
"partyId": "999US"
},
"shipFromParty": {
"partyId": "ABCD"
},
"items": [
{
"itemSequenceNumber": "1",
"buyerProductIdentifier": "B07DFVDRAB",
"vendorProductIdentifier": 8806098286500,
"acknowledgedQuantity": {
"amount": 1,
"unitOfMeasure": "Each"
}
}
]
}
]
}
Confirm purchase order as accepted
If the vendor receives a product in the purchase order which is available to ship, the vendor should accept the item with an acknowledgement code "00" and the "description" as "Shipping 100 percent of ordered product".
{
"orderacknowledgements": [
{
"purchaseOrderNumber": "2JK3S9VC",
"vendorOrderNumber": "ABC",
"acknowledgementDate": "2020-02-20T19:17:34.304Z",
"acknowledgementStatus": {
"code": "00",
"description": "Shipping 100 percent of ordered product"
},
"sellingParty": {
"partyId": "999US"
},
"shipFromParty": {
"partyId": "ABCD"
},
"items": [
{
"itemSequenceNumber": "1",
"buyerProductIdentifier": "B07DFVDRAB",
"vendorProductIdentifier": 8806098286500,
"acknowledgedQuantity": {
"amount": 1,
"unitOfMeasure": "Each"
}
}
]
}
]
}
Updated 23 days ago