Guía de casos de uso de la API de pedidos v0

Mejore la sincronización del inventario de pedidos, los flujos de trabajo y las herramientas de generación de informes.

Versión de API: v0

¿Qué es la API de pedidos?

Usa el API de pedidos para recuperar y enviar la información del pedido de forma programática. Esta API está diseñada para ayudar a los socios vendedores a desarrollar aplicaciones personalizadas rápidas y flexibles que faciliten la sincronización de los pedidos, la búsqueda de pedidos y las herramientas de apoyo a la toma de decisiones basadas en la demanda.

📘

Nota

Los pedidos con más de dos años de antigüedad no se mostrarán en la respuesta de la API, excepto en los sitios web de SG, JP y AU, que admiten pedidos de 2016 y posteriores.

Para obtener información sobre la autenticación y la autorización, consulte Autorización de las aplicaciones de API de los socios vendedores. Para obtener información sobre los pedidos regulados, consulte el Órdenes reguladas guía.

Características principales

  • Recupera la información de los pedidos con criterios de filtrado: El getOrders el funcionamiento de la API de pedidos devuelve los pedidos creados o actualizados durante el período u otros criterios de filtrado indicados por los parámetros especificados. Si NextToken está presente, se usa para recuperar los pedidos en lugar de otros criterios.
  • Recuperar información de un pedido especificado: la operación getOrder de la API de pedidos devuelve la información del pedido especificado.
  • Recuperar información de artículos de un pedido para el pedido especificado: la operación getOrderItems de la API de pedidos devuelve información detallada de artículos para el pedido especificado. Si se proporciona NextToken, se utilizará para recuperar la siguiente página de artículos del pedido.
  • Confirmar el envío del pedido especificado: la operación confirmShipment de la API de pedidos confirma el estado de envío de un pedido especificado. También se puede utilizar para editar los detalles de envío de los pedidos que ya se han enviado.

Tutorial 1: Recuperar información de pedidos con criterios de filtro

La operación getOrders de la API de pedidos devuelve los pedidos creados o actualizados durante el período de tiempo especificado por los parámetros establecidos u otros criterios de filtro. Si NextToken está presente, esta operación se utilizará para recuperar pedidos en lugar de otros criterios.

🚧

Advertencia

La operación getOrders tiene un retraso sistemático en la recuperación de datos. La información de pedido más actualizada está disponible 2 minutos después de que el pedido se haya creado o actualizado por última vez. Para asegurarse de tener la información más reciente sobre el pedido, llama al servicio de atención al cliente transcurridos 2 minutos de la creación o actualización del pedido.

Requisitos

Para completar con éxito este tutorial, debes tener lo siguiente:

Para acceder a la información del comprador y la dirección de envío, debes:

Solicitud getOrders

Llama a la operación getOrders.

Parámetros de consulta

NombreDescripciónObligatorio
CreatedAfterFecha utilizada para seleccionar pedidos creados después de (o en) una hora especificada. Solo se devuelven los pedidos realizados después de la hora especificada. Debes proporcionar el parámetro CreatedAfter o LastUpdatedAfter. Si ambos están vacíos, la llamada no será válida.No
CreatedBeforeUna fecha que se utiliza para seleccionar los pedidos creados antes (o en) una hora específica. Solo se devuelven los pedidos realizados antes de la hora especificada. La fecha debe estar en ISO 8601 formato.No
LastUpdatedAfterUna fecha que se utiliza para seleccionar los pedidos que se actualizaron por última vez después (o en) una hora específica. Una actualización se define como cualquier cambio en el estado de un pedido, incluida la creación de un nuevo pedido. Incluye las actualizaciones realizadas por Amazon y por el vendedor. La fecha debe estar en ISO 8601 formato. Debe proporcionar ya sea el CreatedAfter parámetro o el LastUpdatedAfter parámetro. Si ambos están vacíos, la llamada no es válida.No
LastUpdatedBeforeUna fecha que se utiliza para seleccionar los pedidos que se actualizaron por última vez antes (o en) una hora específica. Una actualización se define como cualquier cambio en el estado de un pedido, incluida la creación de un nuevo pedido. Incluye las actualizaciones realizadas por Amazon y por el vendedor. La fecha debe estar en ISO 8601 formato.No
OrderStatusesUna lista de valores de OrderStatus utilizada para filtrar los resultados.

Posibles valores:
- PendingAvailability (este estado solo está disponible para los pedidos previos. El pedido se ha realizado, el pago no se ha autorizado y la fecha de lanzamiento del artículo es futura).
- Pending (el pedido se ha realizado, pero el pago no se ha autorizado).
- Unshipped (el pago se ha autorizado y el pedido está listo para su envío, pero no se ha enviado ningún artículo del pedido).
- PartiallyShipped (se han enviado uno o más artículos del pedido, pero no todos).
- Shipped (se han enviado todos los artículos del pedido).
- InvoiceUnconfirmed (se han enviado todos los artículos del pedido. El vendedor aún no ha confirmado a Amazon que la factura ha sido enviada al comprador).
- Canceled (el pedido ha sido cancelado).
- Unfulfillable (el pedido no se puede procesar. Este estado solo se aplica a los pedidos de gestión logística multicanal).
No
MarketplaceIdsUna lista de MarketplaceId valores. Se usa para seleccionar los pedidos que se realizaron en los mercados especificados.br>
Consulte Identificadores de mercado para obtener una lista completa de marketplaceId valores.
Recuento máximo : 50
FulfillmentChannelsUna lista que indica cómo se ha gestionado un pedido. Filtra los resultados por canal de gestión logística. Posibles valores: Red logística de Amazon (Logística de Amazon) y Red logística del vendedor (gestionado por el vendedor).No
PaymentMethodsUna lista de valores de métodos de pago. Se utiliza para seleccionar los pedidos pagados mediante los métodos de pago especificados. Posibles valores: pago contra reembolso, pago en tienda u otro (cualquier método de pago que no sea contra reembolso o en tienda).No
BuyerEmailDirección de correo electrónico del comprador. Permite seleccionar los pedidos que contienen la dirección de correo electrónico especificada.No
SellerOrderIdUn identificador de pedido especificado por el vendedor. Se utiliza para seleccionar solo los pedidos que coinciden con el identificador del pedido. Si se especifica SellerOrderId, no se pueden especificar FulfillmentChannels, OrderStatuses, PaymentMethod, LastUpdatedAfter, LastUpdatedBefore ni BuyerEmail.No
MaxResultsPerPageUn número que indica el número máximo de pedidos que se pueden devolver por página. El valor debe estar entre 1 y 100. El valor predeterminado es 100.No
EasyShipShipmentStatusesUna lista de valores de EasyShipShipmentStatus. Se utiliza para seleccionar pedidos Easy Ship con estados que coinciden con los valores especificados. Si se especifica EasyShipShipmentStatus, solo se devolverán los pedidos de Amazon Easy Ship.

Posibles valores:
- PendingSchedule (el paquete está esperando una hora de recogida).
- PendingPickUp (Amazon aún no ha recogido el paquete del vendedor).
- PendingDropOff (el vendedor entregará el paquete al transportista).
- LabelCanceled (el vendedor ha cancelado la recogida).
- PickedUp (Amazon ha recogido el paquete del vendedor).
- DroppedOff (el vendedor ha entregado el paquete al transportista).
- AtOriginFC (el paquete se encuentra en el centro logístico de origen).
- AtDestinationFC (el paquete se encuentra en el centro logístico de destino).
- Delivered (el paquete se ha entregado).
- RejectedByBuyer (el comprador ha rechazado el paquete).
- Undeliverable (el paquete no se puede entregar).
- ReturningToSeller (el paquete no se ha entregado y se devolverá al vendedor).
- ReturnedToSeller (el paquete no se ha entregado y se ha devuelto al vendedor).
- Lost (el paquete se ha perdido).
- OutForDelivery (el paquete está en reparto).
- Damaged (el transportista ha dañado el paquete).
No
ElectronicInvoiceStatusesUna lista de valores de ElectronicInvoiceStatus. Se utiliza para seleccionar los pedidos con estado de factura electrónica que coinciden con los valores especificados.

Posibles valores:
- NotRequired (no es necesario enviar una factura electrónica para este pedido).
- NotFound (la factura electrónica no se ha enviado para este pedido).
- Processing (la factura electrónica se está procesando para este pedido).
- Errored (la última factura electrónica enviada fue rechazada para este pedido).
- Accepted (la última factura electrónica fue enviada y aceptada).
No
NextTokenSe ha devuelto un token de cadena en la respuesta de tu solicitud anterior.No
AmazonOrderIdsUna lista de valores de AmazonOrderId. Un AmazonOrderId es un identificador de pedido definido por Amazon, con el formato 3-7-7.
Número máx.: 50
No
ActualFulfillmentSupplySourceIdIndica lo recomendado sourceId desde dónde se debe tramitar el pedido.No
IsISPUCuando es True, el pedido se selecciona para su recogida en una tienda en lugar de marcarse para entregar.No
StoreChainStoreIdEl identificador de tienda de la cadena de tiendas. Vinculado a una tienda específica de una cadena de tiendas.No

Ejemplo de solicitud

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

Respuesta

Una respuesta correcta incluye lo siguiente:

NombreDescripciónObligatorio
OrdersUna lista de pedidos.
Tipo: Order gama
NextTokenSi está presente y no está vacío, pasa este token de cadena en la siguiente solicitud para volver a la siguiente página de respuesta.No
LastUpdatedBeforeUna fecha que se utiliza para seleccionar los pedidos que se actualizaron por última vez antes (o en) una hora específica. Una actualización se define como cualquier cambio en el estado de un pedido, incluida la creación de un nuevo pedido. Incluye las actualizaciones realizadas por Amazon y por el vendedor. Todas las fechas deben estar en ISO 8601 formato.No
CreatedBeforeUna fecha que se utiliza para seleccionar los pedidos creados antes (o en) una hora específica. Solo se devuelven los pedidos realizados antes de la hora especificada. La fecha debe estar en ISO 8601 formato.No

Respuestas de ejemplo

El siguiente es un ejemplo de una respuesta general del getOrders operación.

{ "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" } } ] } }

Cuando se envía un pedido a una dirección de Brasil, es posible que también recibas campos de dirección adicionales (por ejemplo, StreetName, StreetNumber, Complement y Neighborhood), como se muestra en el siguiente ejemplo.

{ "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" } }

Para obtener más información sobre cuándo las direcciones de envío contienen campos ampliados, consulta la Order esquema en el Referencia v0 de la API de pedidos.

Para obtener una lista de los posibles campos extendidos, consulte AddressExtendedFields en el Referencia v0 de la API de pedidos.

Tutorial 2: Recuperar información del pedido

En el tutorial se muestra cómo utilizar el getOrder funcionamiento de la API de pedidos para recuperar la información del pedido que especifiques.

Requisitos

Para completar con éxito este tutorial, debes tener lo siguiente:

Para acceder a la información del comprador y la dirección de envío, debes:

Solicitud

Parámetro Descripción Obligatorio
orderId Un identificador de pedido definido por Amazon, en formato 3-7-7.

Tipo: cadena

Ejemplo de solicitud

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

Respuesta

Una respuesta correcta incluye lo siguiente:

NombreDescripciónObligatorio
OrderInformación del pedido.
Tipo: Order

Consulta Order en la referencia de la API para obtener más detalles sobre los posibles objetos y propiedades de un pedido.

Ejemplo de respuesta

{ "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: Recuperar información detallada de los artículos del pedido

En el tutorial se muestra cómo utilizar el getOrderItems funcionamiento de la API de pedidos para recuperar la información del pedido que especifiques.

Requisitos

Para completar con éxito este tutorial, debes tener lo siguiente:

Para acceder a la información del comprador y la dirección de envío, debes:

Solicitud

Type Parámetro Descripción Obligatorio
Path orderId Un identificador de pedido definido por Amazon, en formato 3-7-7.

Tipo: cadena

Query NextToken Se ha devuelto un token de cadena en la respuesta de tu solicitud anterior.

Tipo: cadena

No

Ejemplo de solicitud

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

Respuesta

Una respuesta correcta incluye lo siguiente:

NombreDescripciónObligatorio
OrderItemsUna lista de los artículos del pedido.
Tipo: OrderItem gama
NextTokenSi está presente y no está vacío, pasa este token de cadena en la siguiente solicitud para volver a la siguiente página de respuesta.No
AmazonOrderIdUn identificador de pedido definido por Amazon, en formato 3-7-7.

Ejemplo de respuesta

{ "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: Confirmar un envío

En este tutorial se muestra cómo confirmar un envío con la operación confirmShipment después de recibir una notificación de que el pedido está listo para su envío. No necesitarás confirmar el envío si compras una etiqueta de envío a través de la API de envío o de la IU de compra de envíos. La operación confirmShipment es compatible con todos los casos de uso que se admitían en los ficheros de gestión logística, incluida la compatibilidad con varios ID de seguimiento por pedido. Para enviar varios ID de seguimiento de paquetes, debes enviar varias solicitudes con el mismo ID de pedido pero diferentes ID de referencia de paquete.

Ejemplo:

Call OrderID PackageReferenceId
1.ª llamada 902-0300094-570542 101
2.ª llamada 902-0300094-570542 102

El ID de referencia del paquete es compatible con cualquier valor numérico positivo y se utiliza para editar un envío una vez confirmado. Puedes especificar cualquier valor numérico como packageReferenceID y guardaremos los datos. Si necesitas editar el envío, realiza otra operación confirmShipment con el mismo packageReferenceID. Los demás datos del envío se editarán tras el envío correcto. Si no introduces ningún ID al realizar el envío, Amazon asignará automáticamente un packageReferenceID.

Requisitos

Para completar con éxito este tutorial, debes tener lo siguiente:

Si has recibido aprobación para el rol Entrega directa al consumidor (restringido), tendrás acceso a la operación confirmShipment.

Paso 1. Confirmar el envío de un pedido

Llama a la operación confirmShipment, utilizando los siguientes parámetros:

Parámetros de ruta

Parámetro Descripción Obligatorio
orderId Un identificador de pedido definido por Amazon, en formato 3-7-7.

Tipo: cadena

Parámetros de texto

NombreDescripciónObligatorio
packageDetailPropiedades de los paquetes
Tipo PackageDetail
codCollectionMethodMétodo de cobro Pago contra reembolso, admitido solo en Japón.
Tipo CodCollectionMethod
No
marketplaceIdEl identificador no ofuscado del sitio web.
Tipo MarketplaceId

Ejemplo de solicitud

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 } ] } }

Respuesta

Propiedades de la respuesta:

HTTP CodeDescripciónSchema
204Correcto.
Encabezados :
x-amzn-RateLimit-Limit (cadena) : tu límite de tasa (solicitudes por segundo) para esta operación.
x-amzn-RequestId (cadena): identificador único de referencia de la solicitud.
Sin contenido

Para obtener códigos de estado de error, descripciones y esquemas, consulta Confirmar la respuesta de error del envío.

🌟

Sugerencia

Para confirmar varios pedidos, usa el API de feeds v2021-06-30 y pasa el POST_ORDER_FULFILLMENT_DATA tipo de alimentación. Para obtener más información, consulte Confirma varios pedidos a través del fichero de gestión logística de pedidos.

Paso 2. Editar la información de envío de un pedido

Después del paso 1, se crea un paquete para el pedido. Todavía puedes editar la información de envío, como la fecha de envío, el transportista, el servicio de envío (o método de envío), el número de seguimiento (proporcionado por el transportista). Para ello, basta con llamar de nuevo a la operación confirmShipment.

Parámetros que deben ser coherentes

Para asegurarte de que estás editando el mismo envío, no cambies los siguientes parámetros.

Parámetro Descripción En
orderId Un identificador de pedido definido por Amazon, en formato 3-7-7.

Tipo: cadena

Path
packageReferenceId Un identificador proporcionado por el vendedor que identifica de forma única un paquete dentro del ámbito de un pedido. Ten en cuenta que solo se permite un valor numérico positivo.

Tipo: cadena

PackageDetail
orderItemId El identificador único del artículo del pedido.

Tipo: cadena

ConfirmShipmentOrderItem
quantity La cantidad del artículo.

Tipo: entero

ConfirmShipmentOrderItem

Ejemplo de solicitud

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 } ] } }

Respuesta

Propiedades de la respuesta:

HTTP CodeDescripciónSchema
204Correcto.
Encabezados :
x-amzn-RateLimit-Limit (cadena) : tu límite de tasa (solicitudes por segundo) para esta operación.
x-amzn-RequestId (cadena): identificador único de referencia de la solicitud.
Sin contenido

Para obtener códigos de estado de error, descripciones y esquemas, consulta Respuestas de error y esquemas.


¿Te ha ayudado esta página?