Saltar al contenido
Referencia de la API
/
/
Comprar etiqueta

Comprar etiqueta

Solicitud

Crea y paga una etiqueta de envío utilizando el rate_id obtenido en una llamada previa a get_rates. Este endpoint también permite contratar un seguro de envío en la misma solicitud (el seguro no puede comprarse por separado).

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
rate_idstring(ShipmentRateId)requerido

Identificador único de una tarifa de envío devuelta por el endpoint get_rates. Usa este valor para referenciar una tarifa específica al comprar una etiqueta.

Ejemplo:"dc288147-f7dd-494d-9353-5ce00020c7aa"
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"
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/create_and_pay
curl -i -X POST \
  https://x-api.shipsaving.com/api/shipment/create_and_pay \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "rate_id": "dc288147-f7dd-494d-9353-5ce00020c7aa",
    "platform_uk_id": "platformUkId175377917713",
    "insurance_data": {
      "rate_id": "dc288147-f7dd-494d-9353-5ce00020c7aa"
    },
    "label_print_type": "common",
    "is_return_label": false,
    "is_exchange_label": false
  }'

Respuestas

OK

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