Registro de cambios

Todos los cambios destacables de este proyecto se documentarán en este archivo.

El formato está basado en Mantener un registro de cambios, y este proyecto sigue Semantic Versioning. Versión 2.1.0

• POST /api/shipment/direct_buy: Se añadió el campo label_processing_fee a la respuesta, la tarifa fija de procesamiento cobrada por la creación de la etiqueta (p. ej. 0.05).

• POST /api/shipment/direct_buy: Se añadió el campo de solicitud option_data.is_lithium_battery. Cuando es true, el envío se declara automáticamente como mercancía peligrosa: option_data.hazardous_materials se fuerza a true y se aplica la clasificación HAZMAT de USPS para baterías de litio en paquete sin marcar (Clase 9), por lo que solo se devuelven tarifas de USPS Ground Advantage.

• POST /api/shipment/get_rates: Se añadió el campo price_details a cada tarifa, un arreglo específico de FedEx que desglosa la tarifa por componente de cargo (p. ej. {"code":"BASE_CHARGE","description":"Shipping Label Charge","price":99.31}). El campo admite nulos y puede devolver null para tarifas que no son de FedEx.

• POST /api/scan_form/create_scan_form: Nuevo endpoint para crear un SCAN Form de USPS (PS Form 5630) para un conjunto de envíos USPS ya comprados; devuelve la URL del PDF del SCAN Form en scan_form_image.

• POST /api/shipment/submit_pod: Nuevo endpoint para enviar una solicitud de Prueba de Entrega (POD) de un envío USPS y enviar por correo la carta POD a entre 1 y 3 destinatarios. Devuelve transaction_message, p. ej. Your Proof of Delivery record is complete and will be processed shortly.
• GET /api/shipment/direct/tracking_by_tracking_no: Se añadió el campo recipient_name a la respuesta, el nombre de la persona que firmó la entrega (p. ej. Alice).

• Solicitud de envío options.signature: Se agregaron dos valores de enum: usps_signature_restricted (Confirmación de firma con entrega restringida) y usps_adult_signature_restricted (Firma de adulto con entrega restringida, 21+). Los valores existentes signature y adult_signature no cambian.

• GET /api/shipment/direct/tracking_by_tracking_no: Se añadió el campo status_summary a la respuesta, un resumen legible del estado actual de seguimiento (p. ej. Your item has been delivered and is available at a PO Box at 9:34 am on June 22, 2026 in GRANITEVILLE, SC 29829.). El campo admite nulos y puede devolver null cuando no hay resumen disponible.

• Se añadió soporte para documentación en español, lo que permite a los usuarios consultar la documentación de la API de ShipSaving en español.

• Se agregaron descripciones a nivel de campo (límites de longitud, patrones de formato y reglas de campos obligatorios) para pickup_location y una longitud máxima de 255 caracteres para package_location_ext en POST /api/shipment/pickup/add.
• Se agregaron ejemplos de respuesta 400 para POST /api/shipment/pickup/add y POST /api/shipment/pickup/cancel.
• Se agregó una sección de Códigos de error de recolección (Pickup) en el Apéndice, que lista todos los códigos de error devueltos por POST /api/shipment/pickup/add y POST /api/shipment/pickup/cancel.

• Se añadió una colección de Postman descargable (ZIP) en la Guía de integración, que incluye la colección de la API y los archivos de entorno (Sandbox y Producción) para pruebas rápidas.

• Se añadió la nueva página de documentación Errores y límites de tasa, que cubre el formato de respuesta de errores, códigos de estado HTTP, convención de nombres de códigos de error, limitación de tasa y recomendaciones de manejo.
• Se añadieron tablas de Referencia de códigos de error en el Apéndice.

• Se añadió el campo return_to_sender a la respuesta del siguiente endpoint:

  • GET /api/shipment/tracking_by_platform_uk_id

  Este campo booleano indica si el envío ha sido devuelto al remitente.

• Se añadió soporte para niveles de servicio de USPS Returns al siguiente endpoint:

  • POST /api/shipment/direct_buy

  Los niveles de servicio de USPS Returns soportados incluyen:

  • USPS_GROUND_ADVANTAGE_RETURN
  • USPS_PRIORITY_MAIL_RETURN
  • USPS_PRIORITY_MAIL_EXPRESS_RETURN

  Las definiciones del enum de niveles de servicio se pueden encontrar en el Apéndice.

• Se añadió el objeto return_address_data al cuerpo de la solicitud de los siguientes endpoints:

  • POST /api/shipment/direct_buy
  • POST /api/shipment/get_rates

  Este campo es solo para USPS y especifica la dirección a la que se debe devolver el paquete si se considera no entregable o es devuelto al remitente.

• Se añadió un Apéndice específico para la Nueva API (v2), documentando definiciones de enum y tablas de referencia exclusivas de v2.
• Se obsoleta la página de Apéndice de nivel superior y se conserva como punto de entrada compatible con versiones anteriores, dirigiendo a los usuarios al Apéndice de la Nueva API (v2).

• Se añadió soporte para documentación bilingüe (Inglés / Chino), permitiendo a los usuarios cambiar de idioma al consultar la documentación de la API de ShipSaving.

• Se añadió un nuevo endpoint de rastreo GET /api/shipment/direct/tracking_by_tracking_no, que devuelve las marcas de tiempo de los eventos de rastreo en formato ISO 8601 con offsets UTC incluidos, permitiendo una interpretación precisa de las horas locales de los eventos en diferentes zonas horarias.

• Se corrigió un error tipográfico: el campo additional_handing se renombró a additional_handling en la API. Endpoints afectados:
  • POST /api/shipment/batch/quick_rate
  • POST /api/shipment/direct_buy
  • POST /api/shipment/get_rates

• Se añadieron códigos de paquete predefinidos de UPS Canada en el enum carrier_package_code.
• Se añadió el parámetro booleano require_saturday_delivery para indicar una preferencia por la entrega en sábado, si el transportista y el nivel de servicio lo permiten. Establecer este flag en true puede generar recargos adicionales del transportista o tarifas de envío más altas. Endpoints afectados:
  • POST /api/shipment/batch/quick_rate
  • POST /api/shipment/direct_buy
  • POST /api/shipment/get_rates

• Se añadió soporte para obtener tarifas de envío de UPS Canada y comprar etiquetas de envío de UPS Canada en los siguientes endpoints:
  • POST /api/shipment/batch/quick_rate
  • POST /api/shipment/get_rates
  • POST /api/shipment/direct_buy

• Se actualizó la lista de transportistas: se añadió soporte para el nuevo transportista SwiftX Express y su nivel de servicio.
• Se actualizaron /api/shipment/batch/quick_rate y /api/shipment/get_rates: los clientes ahora pueden obtener tarifas para SwiftX Express especificando provider_id="SWIFTX" y service_levels="SWIFTX_EXP" en shipment_rate_carrier_data.
• Se actualizó /api/shipment/direct_buy: ahora se soporta la compra de etiquetas usando SwiftX Express. Para usar este servicio, establece carrier_code="SWIFTX" y service_level="SWIFTX_EXP" al enviar la solicitud.

• Se actualizó /api/shipment/batch/quick_rate: se añadió soporte para el parámetro opcional shipment_rate_carrier_data, permitiendo a los clientes solicitar tarifas para transportistas y niveles de servicio específicos en lugar del USPS Ground Advantage por defecto.
• Se actualizó /api/shipment/direct_buy: se añadieron los campos carrier_code y service_level. Estos dos campos ahora trabajan juntos para determinar qué nivel de servicio del transportista se usará para la compra de la etiqueta.

• Se mejoró /api/shipment/tracking_by_tracking_no: se añadieron estimate_delivery_date, original_tracking_location y destination_tracking_location para proporcionar estimaciones de entrega más claras y detalles más completos de origen/destino reportados por el transportista.

• Conjunto de APIs de recolección de USPS, que permite a los comerciantes programar, cancelar y consultar solicitudes de recolección de USPS:
  • POST /api/shipment/pickup/add — Crear una solicitud de recolección de USPS.
  • POST /api/shipment/pickup/cancel — Cancelar una solicitud de recolección existente.
  • GET /api/shipment/pickup/list — Obtener una lista paginada de registros de recolección.
  • GET /api/shipment/pickup/package/location/list — Obtener los valores disponibles de ubicación del paquete para USPS.

• Se amplió /api/shipment/tracking_by_tracking_no: se añadió soporte para el rastreo de Amazon Shipping, incluyendo consulta de estado e historial de eventos.

• Se añadió /api/shipment/tracking_by_tracking_no: proporciona consulta de rastreo de USPS y UPS por tracking_no, devolviendo el estado de rastreo actual, la información del último escaneo y el historial completo de eventos de rastreo.

• Se actualizaron /api/shipment/direct_buy y /api/shipment/create_and_pay: ahora devuelven tanto la etiqueta estándar como la etiqueta con código QR al comprar servicios de USPS con "label_print_type": "qrcode".

• Se introdujo el parámetro is_return_label en los endpoints /api/shipment/direct_buy y /api/shipment/get_rates, permitiendo a los clientes especificar si la etiqueta es para un envío de devolución. El valor por defecto es false.

• Se añadió el nuevo campo tracking_events (array) a las respuestas de /api/shipment/tracking y /api/shipment/tracking_by_platform_uk_id.
  Este campo representa la línea de tiempo completa de rastreo del envío (todos los eventos de rastreo).

• Se añadió documentación detallada para el campo data.status en la respuesta de /api/shipment/tracking y /api/shipment/tracking_by_platform_uk_id.
  Se introdujeron valores de estado enumerados con descripciones:
  • created, available_for_pickup, in_transit, out_for_delivery, delivered, return_to_sender, voided, error, seized_by_law_enforcement, unknown.

• Se añadió el endpoint /api/shipment/batch/quick_rate para soportar consultas de tarifas de envío por lotes (hasta 10 solicitudes por llamada).
• Se añadió un mecanismo de verificación de duplicados a /api/shipment/direct_buy y /api/shipment/create_and_pay.

• Se añadió el nuevo campo de respuesta scanned_time a la API de rastreo.
• Nuevo endpoint /api/address/validate para validar direcciones de EE. UU., devolver componentes estandarizados y proporcionar detalles de errores/correcciones.

• Nuevo endpoint /api/shipment/tracking_by_platform_uk_id para consultar el estado de rastreo de un envío por platform_uk_id.

• /api/shipment/void_label ahora soporta platform_uk_id para anular una etiqueta.

• Lanzamiento inicial de la Nueva API de ShipSaving, que soporta cotización de envíos, compra de etiquetas, anulación de etiquetas y rastreo de envíos.