Saltar al contenido
/
Integración
Última actualización

Integración

Colección de Postman

Proporcionamos una colección de Postman lista para usar que te ayudará a explorar y probar rápidamente la API V2.

Inicio rápido con Postman
  1. Descarga y descomprime el archivo de abajo
  2. Abre Postman → haz clic en Import (arriba a la izquierda)
  3. Arrastra y suelta los 3 archivos JSON, o haz clic en Choose Files para seleccionarlos
  4. En el menú desplegable de entornos en la parte superior derecha, selecciona ShipSaving V2 — SANDBOX o PROD
  5. Haz clic en el ícono del ojo junto al menú de entornos → establece tu appKey y appSecret
  6. Ejecuta primero Get Access Token — el Bearer token se guardará automáticamente
  7. Listo para enviar solicitudes

Descarga: Colección de Postman ShipSaving API V2 (ZIP)

El ZIP incluye la colección de la API y dos archivos de entorno (Entorno de pruebas y producción).

La API de ShipSaving ofrece dos modos de integración para crear etiquetas de envío:

  1. Integración en dos pasos – Ideal cuando deseas revisar y seleccionar un nivel de servicio antes de comprar.
  • Paso 1: Solicita todas las tarifas disponibles.
  • Paso 2: Compra una etiqueta usando la tarifa seleccionada.
  1. Integración en un solo paso – Ideal para flujos de trabajo totalmente automatizados, combina la obtención de tarifas y la compra de la etiqueta en una sola llamada a la API.

Integración en dos pasos

Para obtener todas las tarifas de envío disponibles y comprar una etiqueta para la tarifa seleccionada, sigue estos pasos:

Paso 1 – Obtener tarifas

Llama al endpoint /api/shipment/get_rates para crear un envío y obtener las opciones de tarifas. El cuerpo de la solicitud debe incluir:

  • Dos objetos de dirección: from_address_data y to_address_data

  • Objeto package_data

  • Opcional: custom_data

  • Opcional: option_data

  • Opcional: shipment_rate_carrier_data — Te permite filtrar las tarifas por transportista y nivel de servicio para consultas más rápidas:

    • Especifica uno o más transportistas usando provider_id

    • Especifica uno o más niveles de servicio usando el arreglo service_levels

    • Ejemplo:

      "shipment_rate_carrier_data": [
  {
      "provider_id": "USPS_X",
      "service_levels": ["USPS_GROUND_ADVANTAGE"]
  }
]
      INFORMACIÓN

      Filtrar por transportistas y niveles de servicio específicos puede mejorar el rendimiento al reducir el número de búsquedas de tarifas.

Ejemplo de solicitud:

curl --location 'https://x-api.shipsaving.us/api/shipment/get_rates' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJraWQiOiIxIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJTU19MSVZFX2RYbzNPeTlXRXFLWTRmcHVDT013Q3pDX1BqcElEd3VKc1dDZiIsImF1ZCI6IlNTX0xJVkVfZFhvM095OVdFcUtZNGZwdUNPTXdDekNfUGpwSUR3dUpzV0NmIiwibmJmIjoxNzU0OTQ2MDc3LCJjb21wYW55X2lkIjoiMTgxOCIsInVzZXJfaWQiOiIyNDAyIiwic2NvcGUiOlsiQVBJIl0sImlzX3ZhbGlkIjp0cnVlLCJpc3MiOiJodHRwczovL3gtYXBpLnNoaXBzYXZpbmcudXMiLCJleHAiOjE3NTQ5NDc4NzcsImlhdCI6MTc1NDk0NjA3NywidGVzdF9tb2RlbCI6ZmFsc2V9.ZZTr3HBLjlrKMck2YeQmpkh-6c8r7Z9aqLLVRLioKkcD7c3M41GMDx3qb-LG3XvAJicJe-BYX64pcJ0heCpP7uG6sSq0P7pLR--VdysbinCRB4Bz1VIWRjFkmsMtab2Gi3YToPR4JRV99zVWFI6cKqmaqWIBLyVkWmgAUMIi4PTmFgMUyouqo_GJ6FFmwKb-Av1JrrUe8t5DhDMBuXRl8Da-eLqZSRsQyQ1WV5-uLP7ESYM0k0h5R6I7u-7uT8vf8NR8U8jUYIkzcMb47PuWUxsaWn5ngFLTq03H28g1QV10gxFkBMFgzKEPumxadzzttfDbFXtSd7ALzvC7pXigxA' \
--data-raw '{
    "to_address_data": {
        "city": "City Of Industry",
        "country": "US",
        "state": "CA",
        "street": "17XXX Castleton Street",
        "street2": "STE 500",
        "zip_code": "91XXX",
        "first_name": "Alice",
        "last_name": "Li",
        "phone": "1234567890",
        "email": "it@shipsaving.com"
    },
    "from_address_data": {
        "city": "City Of Industry",
        "country": "US",
        "state": "CA",
        "street": "17XXX Castleton Street",
        "street2": "STE 500",
        "zip_code": "91XXX",
        "first_name": "Alice",
        "last_name": "Li",
        "phone": "1234567890",
        "email": "it@shipsaving.com"
    },
    "package_data": {
        "width": 3,
        "length": 6,
        "height": 0.25,
        "dimension_unit": "in",
        "weight": 2,
        "weight_unit": "oz",
        "type": "my_package" 
    },
    "custom_data": {
        "signing_person": "Ray",
        "content_type": "merchandise",
        "tax_ids": [
            {
                "tax_id_type": "TIN",
                "tax_id_number": "tin2888",
                "country_code": "US"
            }
        ],
        "eel_pfc_type": "EXEMPTION_CODE",
        "eel_pfc_code": "NOEEI 30.37(a)",
        "undeliverable_option": "return_to_sender",
        "item_data_list": [
            {
                "description": "cloth",
                "quantity": 1,
                "origin": "CN",
                "weight": 1,
                "unit_cost": 10.1,
                "weight_unit": "lb"
            }
        ]
    },
    "option_data": {
        "signature": null,
        "custom_text_on_label_1": "",
        "custom_text_on_label_2": "",
        "hazardous_materials": false,
        "additional_handling": false
    },
    "shipment_rate_carrier_data": [
        {
            "provider_id": "UPS_SS_DNI",
            "service_levels": ["UPS_GROUND"]
        }
    ],
    "ship_date": "2025-08-15T00:00:00+08:00"
}'

La respuesta de /api/shipment/get_rates contiene:

  • Cotizaciones de todos los transportistas y niveles de servicio activos vinculados a tu cuenta
  • Orden por más rápido, más barato y otros criterios
  • error_info para transportistas o servicios que no pudieron proporcionar una tarifa

Ejemplo de respuesta:

{
    "code": "ok",
    "msg": "ok",
    "data": {
        "fastest": null,
        "cheapest": {
            "zone": "1",
            "currency": "USD",
            "price_details": null,
            "cubic": false,
            "rate_id": "f3bfa0b5-3dde-4ccb-822f-f995d7e512c6",
            "carrier_code": "GOFO_EXPRESS",
            "provider_id": "GOFO_EXPRESS_A",
            "service_name": "Gofo Express ECO",
            "service_level": "GOFO_EXPRESS_ECO",
            "service_level_desc": "ECO",
            "returned_package_code": "my_package",
            "delivery_days": "2-3",
            "delivery_date": null,
            "delivery_weekday": null,
            "service_detail": "ECO",
            "price": 2.75,
            "origin_price": null,
            "retail_price": null,
            "discount_text": null,
            "insurance_info": null,
            "ship_date": "2025-08-08T00:00:00+08:00",
            "saturday_delivery": false,
            "one_rate": false
        },
        "shipment_rate_data": [
            {
                "zone": "1",
                "currency": "USD",
                "price_details": null,
                "cubic": false,
                "rate_id": "5d73c5d9-3379-44b3-94b0-79c0d17c87e5",
                "carrier_code": "USPS",
                "provider_id": "USPS_X",
                "service_name": "USPS Media Mail",
                "service_level": "USPS_MEDIA_MAIL",
                "service_level_desc": "A cost-effective way to send eligible books, media, and educational materials.",
                "returned_package_code": "my_package",
                "delivery_days": "4",
                "delivery_date": null,
                "delivery_weekday": null,
                "service_detail": "A cost-effective way to send eligible books, media, and educational materials.",
                "price": 4.47,
                "origin_price": null,
                "retail_price": 4.47,
                "discount_text": null,
                "insurance_info": null,
                "ship_date": "2025-08-08T00:00:00+08:00",
                "saturday_delivery": false,
                "one_rate": false
            },
            {
                "zone": "1",
                "currency": "USD",
                "price_details": null,
                "cubic": false,
                "rate_id": "f1ed77b3-4525-47f9-b536-8964a8681251",
                "carrier_code": "USPS",
                "provider_id": "USPS_X",
                "service_name": "USPS Ground Advantage",
                "service_level": "USPS_GROUND_ADVANTAGE",
                "service_level_desc": "Low rates for packages with expected delivery in 2-5 business days.",
                "returned_package_code": "my_package",
                "delivery_days": "2",
                "delivery_date": null,
                "delivery_weekday": null,
                "service_detail": "Low rates for packages with expected delivery in 2-5 business days.",
                "price": 5.91,
                "origin_price": null,
                "retail_price": 8.70,
                "discount_text": null,
                "insurance_info": null,
                "ship_date": "2025-08-08T00:00:00+08:00",
                "saturday_delivery": false,
                "one_rate": false
            }
        ],
        "fastest_and_cheapest": null,
        "error_info": {
            "USPS": [
                {
                    "code": "invalid_request_params",
                    "message": "cannot be in the past or more than 30 days in the future"
                }
            ]
        }
    }
}

Paso 2 – Comprar etiqueta

Después de seleccionar un rate_id de la respuesta de /api/shipment/get_rates, llama al endpoint /api/shipment/create_and_buy para comprar la etiqueta de envío. También puedes incluir insurance_data si corresponde.

Ejemplo de solicitud:

curl --location 'https://x-api.shipsaving.us/api/shipment/create_and_pay' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJraWQiOiIxIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJTU19MSVZFX2RYbzNPeTlXRXFLWTRmcHVDT013Q3pDX1BqcElEd3VKc1dDZiIsImF1ZCI6IlNTX0xJVkVfZFhvM095OVdFcUtZNGZwdUNPTXdDekNfUGpwSUR3dUpzV0NmIiwibmJmIjoxNzU0NzAxNjA4LCJjb21wYW55X2lkIjoiMTgxOCIsInVzZXJfaWQiOiIyNDAyIiwic2NvcGUiOlsiQVBJIl0sImlzX3ZhbGlkIjp0cnVlLCJpc3MiOiJodHRwczovL3gtYXBpLnNoaXBzYXZpbmcudXMiLCJleHAiOjE3NTQ3MDM0MDgsImlhdCI6MTc1NDcwMTYwOCwidGVzdF9tb2RlbCI6ZmFsc2V9.oi14AMVCn_yGYEDCnBaYeci5FDRfAiO-VKSG_pMRCJEwM7zBJ93m0_-uUS1xmrFV7f3f4OPNeiHzSmNLhS0L2YYn5NXwU8PxMgpVhPGZgCWu31B6VIMaX2nnE5bB26sOrHDObE5wQeB1Yp0geG4KZ_2H5wwrK9fGfRWEH48GbOduQKgS5llIGDilUY0zvFKyeB7HTjDY0kO-hR0F7g0x77PVEk5PVvkBWiN1rOUlT7tAmMdtP-xHpM28U8xKQPOplcbdn4A8t9K2l3TZE84YvsJCzrtmQjr5Qj9m_uadmUNhSyzw5p3KvpI0-l_FWxHC3stkD2Q8CAoCs2Kb3Ur6bg' \
--data '{
    "platform_uk_id": "c_eDQCbv=2YVGw)7#$v_aCI9%ynJEa2O",
    "rate_id": "d9437e43-5283-4289-9ed3-5ef306bb50dd",
    "insurance_data": {
        "rate_id": "50c4685e-5045-4f85-aadc-1a58ff24e147"
    },
    "label_print_type": "common"
}'

Ejemplo de respuesta:

{
    "code": "ok",
    "msg": "ok",
    "data": {
        "shipment_no": "1222243143",
        "tracking_no": "1ZXXXXXXXXXXXXXXXX",
        "total_fee": 34.81,
        "label_fee": 34.81,
        "insurance_fee": null,
        "label_urls": [
            "https://xxx.amazonaws.com/labels/2025-08-11/8f6558b8fbb44fd2bdf826c645c9778e_0.png"
        ],
        "commercial_urls": null,
        "label_print_type": "common"
    }
}

Integración en un solo paso

Ideal para flujos de trabajo totalmente automatizados, este modo combina la obtención de tarifas y la compra de la etiqueta en una sola llamada a la API a /api/shipment/direct_buy. Proporcionas todos los detalles necesarios del envío junto con el campo service_level para especificar el servicio exacto a comprar, eliminando el paso separado de selección de tarifa. También puedes incluir el objeto insurance_data en la misma solicitud para comprar el seguro del envío junto con la etiqueta. Este enfoque reduce el número de llamadas a la API y simplifica la integración cuando el nivel de servicio está predeterminado.

Ejemplo de solicitud:

{
  "service_level": "USPS_GROUND_ADVANTAGE",
  "from_address_data": {
    "phone": "7819991234",
    "email": null,
    "street": "xxxx Castleton Street",
    "street2": "xxxxx",
    "city": "Los Angeles",
    "state": "CA",
    "country": "US",
    "company_name": "Shipsaving02",
    "first_name": "Alice",
    "last_name": "Green",
    "zip_code": "91xxx",
    "address_type": "residential"
  },
  "to_address_data": {
    "first_name": "GU",
    "last_name": "GU",
    "country": "US",
    "phone": "9898912324",
    "street": "1328 Pale San Vitores Road, Tumon",
    "city": "Tamuning",
    "state": "GU",
    "zip_code": "96913",
    "street2": ""
  },
  "package_data": {
    "type": "my_package",
    "length": 12,
    "width": 11,
    "height": 5,
    "weight": 1,
    "dimension_unit": "in",
    "weight_unit": "lb"
  },
  "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": "Dazy Plus Plus Size Retro French Fashion Plaid 2 Pieces Set, Chic Outfit For Summer",
        "quantity": 1,
        "origin": "CN",
        "weight": 10,
        "unit_cost": 14.4,
        "weight_unit": "oz",
        "hs_tariff_number": "10.1234"
      }
    ]
  },
  "option_data": {
    "signature": null,
    "custom_text_on_label_1": "text1",
    "custom_text_on_label_2": "text2",
    "hazardous_materials": true,
    "additional_handling": false
  },
  "ship_date": "2025-08-15T00:00:00+08:00",
  "platform_uk_id": "platform_2344343535353",
  "insurance_data": {
    "rate_id": "57e8c472-e699-4900-9e0b-673b2b2034a5"
  },
  "label_print_type": "common"
}

Autenticación

Guía de parámetros