Compra directa de etiqueta

Referencia de la API

Compra directa de etiqueta

Solicitud

Crea y compra una etiqueta de envío en un solo paso sin necesidad de llamar a get_rates por separado.

Actualmente, este endpoint admite los niveles de servicio de USPS Returns. Consulta el Apéndice para ver la lista completa de valores soportados.

Para evitar compras duplicadas causadas por fluctuaciones de red o reintentos, la API verifica si ya existe un envío bajo el platform_uk_id especificado.

Si se encuentra un envío relacionado, se devolverá la información del envío existente y el campo duplicate_label en la respuesta se establecerá en true.
Si no existe ningún envío, se creará un nuevo envío de forma normal y el campo duplicate_label será false.

Seguridad

BearerAuth

Cuerpoapplication/jsonrequerido

platform_uk_idstring(PlatformUkId)requerido

Identificador único proporcionado por quien realiza la llamada (por ejemplo, el número de pedido del cliente). Cada platform_uk_id debe corresponder exactamente a un envío y no puede reutilizarse en varios envíos.

Ejemplo:"platformUkId175377917713"

carrier_codestring(CarrierCodeEnum)requerido

Identificador del código de transportista.

Enum:"USPS""UPS""FEDEX""DHL_EXPRESS""SWIFTX""GOFO_EXPRESS""UPS_CANADA"

Ejemplo:"USPS"

service_levelstring(ServiceLevelEnum)requerido

Nivel de servicio del transportista. Consulta Apéndice - Tipos de servicio por transportista para ver las relaciones válidas entre carrier_code, provider_id y service_level.

Enum:"USPS_FIRST_CLASS_MAIL""USPS_GROUND_ADVANTAGE""USPS_PRIORITY_MAIL""USPS_PRIORITY_MAIL_EXPRESS""USPS_MEDIA_MAIL""USPS_LIBRARY_MAIL""USPS_FIRST_CLASS_MAIL_INTERNATIONAL""USPS_PRIORITY_MAIL_INTERNATIONAL""USPS_PRIORITY_MAIL_EXPRESS_INTERNATIONAL""UPS_GROUND"

Ejemplo:"USPS_GROUND_ADVANTAGE"

return_address_dataobject(AddressReturn)

Dirección a la que se debe devolver el paquete si no se puede entregar o si se devuelve al remitente. Nota: Solo USPS admite la impresión de una dirección de devolución específica en la etiqueta.

from_address_dataobject(AddressFrom)requerido

to_address_dataobject(AddressTo)requerido

package_dataobject(ShipmentPackageData)requerido

option_dataobject(ShipmentOptionData)

Opciones de envío adicionales

ship_datestring(ShipDate)requerido

Marca de tiempo en formato ISO 8601, incluyendo la hora local y el desplazamiento de zona horaria.

Ejemplo:"2025-07-31T00:00:00+08:00"

custom_dataobject(ShipmentCustomData)

Datos aduaneros

insurance_dataobject(InsuranceData)

label_print_typestring(LabelPrintTypeEnum)requerido

Define el formato de impresión de la etiqueta. Los tipos admitidos varían según el transportista y también pueden depender del nivel de servicio seleccionado. Por ejemplo, USPS y FedEx pueden admitir qrcode, mientras que UPS puede admitir barcode.

Enum:"common""qrcode""barcode"

Ejemplo:"common"

is_return_labelboolean(IsReturnLabel)

Indica si la etiqueta corresponde a un envío de devolución.

Predeterminado:false

Ejemplo:false

is_exchange_labelboolean(IsExchangeLabel)

Indica si la etiqueta de envío pertenece a un flujo de cambio/devolución específico de una plataforma. Este campo se utiliza para ciertas integraciones de marketplaces y se almacenará internamente en el campo tag.

Predeterminado:false

Ejemplo:false

POST

/api/shipment/direct_buy

curl -i -X POST \
  https://x-api.shipsaving.com/api/shipment/direct_buy \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "platform_uk_id": "platformUkId175377917713",
    "carrier_code": "USPS",
    "service_level": "USPS_GROUND_ADVANTAGE",
    "return_address_data": {
      "first_name": "Alice",
      "last_name": "Green",
      "company_name": "ShipSaving",
      "phone": "1234567890",
      "email": "it@shipsaving.com",
      "street": "xxxx Olive Street",
      "street2": "STE XXX",
      "city": "Los Angeles",
      "state": "CA",
      "zip_code": "021XX",
      "country": "US"
    },
    "from_address_data": {
      "first_name": "Alice",
      "last_name": "Green",
      "company_name": "ShipSaving",
      "phone": "1234567890",
      "email": "it@shipsaving.com",
      "street": "xxxx Olive Street",
      "street2": "STE XXX",
      "city": "Los Angeles",
      "state": "CA",
      "zip_code": "021XX",
      "country": "US"
    },
    "to_address_data": {
      "first_name": "Alice",
      "last_name": "Green",
      "company_name": "ShipSaving",
      "phone": "1234567890",
      "email": "it@shipsaving.com",
      "street": "xxxx Olive Street",
      "street2": "STE XXX",
      "city": "Los Angeles",
      "state": "CA",
      "zip_code": "021XX",
      "country": "US",
      "address_type": "residential"
    },
    "package_data": {
      "type": "my_package",
      "length": 10,
      "width": 10,
      "height": 10,
      "weight": 10,
      "carrier_package_code": "USPS_SMALL_FLAT_RATE_BOX",
      "dimension_unit": "in",
      "weight_unit": "lb"
    },
    "option_data": {
      "signature": "signature",
      "custom_text_on_label_1": "Por favor, deja el paquete en el casillero.",
      "custom_text_on_label_2": "Por favor, deja el paquete en el casillero.",
      "hazardous_materials": true,
      "is_lithium_battery": false,
      "additional_handling": false,
      "require_saturday_delivery": false
    },
    "ship_date": "2025-07-31T00:00:00+08:00",
    "custom_data": {
      "signing_person": "Ray",
      "content_type": "merchandise",
      "tax_ids": [
        {
          "tax_id_type": "TIN",
          "tax_id_number": "tin2888",
          "country_code": "US"
        }
      ],
      "eel_pfc_type": "ITN",
      "eel_pfc_code": "X20250719123456",
      "undeliverable_option": "return_to_sender",
      "item_data_list": [
        {
          "description": "ropa",
          "quantity": 10,
          "origin": "US",
          "weight": 10,
          "unit_cost": 19.99,
          "weight_unit": "lb",
          "hs_tariff_number": "xx"
        }
      ]
    },
    "insurance_data": {
      "rate_id": "dc288147-f7dd-494d-9353-5ce00020c7aa"
    },
    "label_print_type": "common",
    "is_return_label": false,
    "is_exchange_label": false
  }'

Respuestas

Cuerpoapplication/json

codestring

Ejemplo:"ok"

msgstring

Ejemplo:"ok"

dataobject(ShipmentItem)

Response

{
  "code": "ok",
  "msg": "ok",
  "data": {
    "zone": "1",
    "currency": "USD",
    "shipment_no": "1222243159",
    "tracking_no": "9234690381085700XXXXX",
    "total_fee": 39.39,
    "label_fee": 39.39,
    "insurance_fee": null,
    "label_processing_fee": 0.05,
    "label_urls": [ … ],
    "qrcode_urls": [ … ],
    "commercial_urls": null,
    "duplicate_label": true,
    "label_print_type": "common"
  }
}