# Tarifa rápida por lotes

Este endpoint te permite obtener rápidamente cotizaciones de tarifas de envío proporcionando `from_address_data`, `to_address_data`, `package_data` y la `ship_date`.
</br>
**Cada llamada a la API puede incluir hasta 10 solicitudes de tarifa individuales.**
Anteriormente, este endpoint solo devolvía tarifas para USPS Ground Advantage.
Con la nueva actualización, puedes especificar opcionalmente transportistas y niveles de servicio adicionales mediante el campo `shipment_rate_carrier_data`. En el esquema de la solicitud encontrarás una explicación detallada sobre cómo utilizar este parámetro.
- Si se omite `shipment_rate_carrier_data`:
El sistema devolverá tarifas solo para USPS Ground Advantage (comportamiento predeterminado).
- Si se proporciona `shipment_rate_carrier_data`:
El sistema devolverá tarifas únicamente para los proveedores y niveles de servicio especificados.
Pueden enviarse varias combinaciones en una sola solicitud.

Endpoint: POST /api/shipment/batch/quick_rate
Version: v2
Security: BearerAuth

## Request fields (application/json):

  - `rate_requests` (array, required)
    Lista de solicitudes de tarifa individuales. Cada llamada puede incluir hasta 10 elementos.

  - `rate_requests.request_unique_id` (string, required)
    Identificador único generado por el cliente que realiza la solicitud para marcar una solicitud de tarifa individual dentro de un lote. Este valor se devolverá en la respuesta correspondiente, garantizando una correspondencia uno a uno entre solicitudes y respuestas.
    Example: unique_uuid_001

  - `rate_requests.from_address_data` (object, required)

  - `rate_requests.from_address_data.first_name` (string, required)
    Nombre correspondiente a la dirección. Para la API de Batch Quick Rate, este parámetro es opcional.
    Example: Alice

  - `rate_requests.from_address_data.last_name` (string, required)
    Apellido correspondiente a la dirección. Para la API de Batch Quick Rate, este parámetro es opcional.
    Example: Green

  - `rate_requests.from_address_data.company_name` (string)
    Nombre de la empresa o comercio correspondiente a la dirección.
    Example: ShipSaving

  - `rate_requests.from_address_data.phone` (string)
    Número de teléfono del remitente/destinatario. Es obligatorio para envíos internacionales. Se recomienda proporcionar un número de teléfono en todos los envíos para garantizar una entrega precisa y facilitar el contacto del transportista en caso de ser necesario.
    Example: 1234567890

  - `rate_requests.from_address_data.email` (string)
    Dirección de correo electrónico del remitente/destinatario. El transportista puede utilizarla para notificaciones de entrega o para resolver incidencias.
    Example: it@shipsaving.com

  - `rate_requests.from_address_data.street` (string, required)
    El número del edificio junto con el nombre de la vía o calle en la que se encuentra.
    Example: xxxx Olive Street

  - `rate_requests.from_address_data.street2` (string)
    El identificador de unidad secundaria, como el número de apartamento (APT) o suite (STE), que define la ubicación exacta de la dirección dentro de un edificio.
    Example: STE XXX

  - `rate_requests.from_address_data.city` (string, required)
    Nombre de la ciudad de la dirección.
    Example: Los Angeles

  - `rate_requests.from_address_data.state` (string, required)
    - Para direcciones de EE. UU., este campo debe ser un código de estado válido de dos letras (por ejemplo, "CA" para California, "NY" para Nueva York).
- Para direcciones fuera de EE. UU., no existe restricción sobre el valor.
    Example: CA

  - `rate_requests.from_address_data.zip_code` (string, required)
    Código postal de la dirección.
    Example: 021XX

  - `rate_requests.from_address_data.country` (string, required)
    Código de país de 2 letras. El valor de este campo será un [código de dos dígitos ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1).
    Example: US

  - `rate_requests.to_address_data` (object, required)

  - `rate_requests.to_address_data.address_type` (string, required)
    Indica si la dirección de destino es residencial o comercial.
Este indicador se utiliza para determinar los recargos específicos del transportista (por ejemplo, recargos de UPS por entrega residencial).
    Enum: "residential", "commercial"

  - `rate_requests.package_data` (object, required)

  - `rate_requests.package_data.type` (string)
    Define el tipo de paquete que se envía.
- `my_package`: Úsalo cuando especifiques dimensiones personalizadas del paquete. Requiere `width`, `length`, `height`, `dimension_unit`, `weight` y `weight_unit`.
- `predefined`: Úsalo cuando selecciones un tipo de paquete predefinido del transportista. Solo requiere `carrier_package_code` y los campos de peso; los campos de dimensiones se ignoran.
    Enum: "my_package", "predefined"

  - `rate_requests.package_data.length` (number)
    Largo del paquete en la unidad seleccionada.
    Example: 10

  - `rate_requests.package_data.width` (number)
    Ancho del paquete en la unidad seleccionada.
    Example: 10

  - `rate_requests.package_data.height` (number)
    Alto del paquete en la unidad seleccionada.
    Example: 10

  - `rate_requests.package_data.weight` (number)
    Peso del paquete en la unidad seleccionada.
    Example: 10

  - `rate_requests.package_data.carrier_package_code` (string)
    Identificador del código de paquete del transportista. Consulta Apéndice - Códigos de paquete por transportista para ver los valores admitidos en la nueva API de ShipSaving (v2).
    Enum: "USPS_LETTER", "USPS_LARGE_ENVELOPE_OR_FLAT", "USPS_THICK_ENVELOPE", "USPS_SMALL_FLAT_RATE_BOX", "USPS_MEDIUM_FLAT_RATE_BOX", "USPS_LARGE_FLAT_RATE_BOX", "USPS_FLAT_RATE_ENVELOPE", "USPS_PADDED_FLAT_RATE_ENVELOPE", "USPS_LEGAL_FLAT_RATE_ENVELOPE", "UPS_LETTER", "UPS_25KG_BOX", "UPS_10KG_BOX", "UPS_TUBE", "UPS_PAK", "UPS_EXPRESS_BOX_SMALL", "UPS_EXPRESS_BOX_MEDIUM", "UPS_EXPRESS_BOX_LARGE", "FEDEX_ENVELOPE", "FEDEX_PAK", "FEDEX_TUBE", "FEDEX_EXTRA_SMALL_BOX", "FEDEX_SMALL_BOX", "FEDEX_MEDIUM_BOX", "FEDEX_LARGE_BOX", "FEDEX_EXTRA_LARGE_BOX", "FEDEX_BOX", "FEDEX_10KG_BOX", "FEDEX_25KG_BOX", "UPS_CANADA_LETTER", "UPS_CANADA_25KG_BOX", "UPS_CANADA_10KG_BOX", "UPS_CANADA_TUBE", "UPS_CANADA_PAK", "UPS_CANADA_EXPRESS_BOX_SMALL", "UPS_CANADA_EXPRESS_BOX_MEDIUM", "UPS_CANADA_EXPRESS_BOX_LARGE", "UPS_CANADA_EXPRESS_BOX"

  - `rate_requests.package_data.dimension_unit` (string)
    Unidad de dimensión seleccionada.
    Enum: "in", "cm"

  - `rate_requests.package_data.weight_unit` (string)
    Unidad de peso seleccionada.
    Enum: "lb", "oz", "kg", "g"

  - `rate_requests.option_data` (object)
    Opciones de envío adicionales

  - `rate_requests.option_data.signature` (string)
    Solicita confirmación de firma en la entrega. Valores:
- `signature` = Confirmación de firma de;
- `adult_signature` = Firma de adulto requerida (21+);
- `usps_signature_restricted` = Confirmación de firma con entrega restringida
(se entrega únicamente al destinatario indicado o a su agente autorizado);
- `usps_adult_signature_restricted` = Firma de adulto con entrega restringida (21+)
(el destinatario debe tener 21 años o más y ser la persona indicada).
    Enum: "signature", "adult_signature", "usps_signature_restricted", "usps_adult_signature_restricted"

  - `rate_requests.option_data.custom_text_on_label_1` (string)
    Texto personalizado para imprimir en la etiqueta. Si la etiqueta admite contenido de impresión personalizado, este campo se imprimirá en la etiqueta.
    Example: Por favor, deja el paquete en el casillero.

  - `rate_requests.option_data.hazardous_materials` (boolean)
    Indica si este envío contiene mercancías peligrosas o materiales peligrosos (solo para el servicio USPS Ground Advantage). Consulta el tutorial sobre cómo embalar, etiquetar y enviar HAZMAT para envíos nacionales.
    Example: true

  - `rate_requests.option_data.is_lithium_battery` (boolean)
    Indica si el paquete contiene baterías de litio.
**Nota**:
- Cuando este campo es `true`, `hazardous_materials` se sobrescribe a `true`.
- Los envíos con destino u origen en territorios insulares de EE. UU. (como Guam, Puerto Rico) normalmente requieren que este campo sea `true` para poder enviar baterías de litio.
- Consulta las pautas de USPS sobre baterías de litio antes de realizar el envío.
    Example: false

  - `rate_requests.option_data.additional_handling` (boolean)
    Indica si el paquete requiere manejo adicional debido a su tamaño, peso o embalaje que no cumple con las pautas estándar de envío. Los transportistas pueden aplicar cargos adicionales cuando este campo se establece en `true`.
    Example: false

  - `rate_requests.option_data.require_saturday_delivery` (boolean)
    Cuando es `true`, solo se devuelven las cotizaciones de tarifas que admiten entrega en sábado. Si es `false` o se omite, se devuelven todas las cotizaciones de tarifa disponibles independientemente del soporte de entrega en sábado.
**Nota**:
- La disponibilidad real de entrega en sábado depende del transportista y del nivel de servicio; algunos transportistas o servicios pueden no admitirla.
- Activar esta preferencia puede dar lugar a recargos adicionales del transportista o a costos de envío más altos si el nivel de servicio seleccionado aplica cargos extra por entrega en sábado.
    Example: false

  - `rate_requests.ship_date` (string, required)
    Marca de tiempo en formato ISO 8601, incluyendo la hora local y el desplazamiento de zona horaria.
    Example: 2025-07-31T00:00:00+08:00

  - `rate_requests.is_return_label` (boolean)
    Indica si la etiqueta corresponde a un envío de devolución.
    Example: false

  - `rate_requests.shipment_rate_carrier_data` (array)
    Al especificar este parámetro, puedes filtrar las tarifas por transportista y nivel de servicio, lo que permite consultas más rápidas.

  - `rate_requests.shipment_rate_carrier_data.provider_id` (string)
    id del proveedor del transportista
    Enum: "UPS_SS_DNI", "USPS_X", "FEDEX_X", "DHL_A", "GOFO_EXPRESS_A", "SWIFTX", "UPS_CANADA"

  - `rate_requests.shipment_rate_carrier_data.service_levels` (array)
    Niveles de servicio del transportista.

## Response 200 fields (application/json):

  - `code` (string)
    Example: ok

  - `msg` (string)
    Example: ok

  - `data` (array)

  - `data.request_unique_id` (string)
    Identificador único generado por el cliente que realiza la solicitud para marcar una solicitud de tarifa individual dentro de un lote. Este valor se devolverá en la respuesta correspondiente, garantizando una correspondencia uno a uno entre solicitudes y respuestas.
    Example: unique_uuid_001

  - `data.shipment_rate_data` (array)

  - `data.shipment_rate_data.zone` (string)
    Example: 8Rural

  - `data.shipment_rate_data.currency` (string)
    Example: USD

  - `data.shipment_rate_data.cubic` (boolean)
    Example: false

  - `data.shipment_rate_data.rate_id` (string)
    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.
    Example: dc288147-f7dd-494d-9353-5ce00020c7aa

  - `data.shipment_rate_data.carrier_code` (string)
    Identificador del código de transportista.
    Enum: "USPS", "UPS", "FEDEX", "DHL_EXPRESS", "SWIFTX", "GOFO_EXPRESS", "UPS_CANADA"

  - `data.shipment_rate_data.provider_id` (string)
    id del proveedor del transportista
    Enum: "UPS_SS_DNI", "USPS_X", "FEDEX_X", "DHL_A", "GOFO_EXPRESS_A", "SWIFTX", "UPS_CANADA"

  - `data.shipment_rate_data.service_name` (string)
    Example: USPS Media Mail

  - `data.shipment_rate_data.service_level` (string)
    Example: USPS_MEDIA_MAIL

  - `data.shipment_rate_data.service_level_desc` (string)
    Example: Una forma rentable de enviar libros, contenido multimedia y materiales educativos elegibles.

  - `data.shipment_rate_data.returned_package_code` (string)
    Example: my_package

  - `data.shipment_rate_data.delivery_days` (string)
    Example: 2

  - `data.shipment_rate_data.delivery_date` (string)
    Example: 2025-08-08T00:00:00+08:00

  - `data.shipment_rate_data.delivery_weekday` (string)
    Example: MONDAY

  - `data.shipment_rate_data.service_detail` (string)
    Example: Tarifas bajas para paquetes con entrega prevista en 2-5 días hábiles.

  - `data.shipment_rate_data.price` (number)
    Example: 5.91

  - `data.shipment_rate_data.origin_price` (number)
    Example: null

  - `data.shipment_rate_data.retail_price` (number)
    Example: 8.7

  - `data.shipment_rate_data.discount_text` (string)

  - `data.shipment_rate_data.insurance_info` (string)

  - `data.shipment_rate_data.ship_date` (string)
    Marca de tiempo en formato ISO 8601, incluyendo la hora local y el desplazamiento de zona horaria.
    Example: 2025-07-31T00:00:00+08:00

  - `data.shipment_rate_data.saturday_delivery` (boolean)
    Example: false

  - `data.shipment_rate_data.one_rate` (boolean)
    Example: false

  - `data.shipment_rate_data.base_rate` (object)
    Representa la tarifa base cobrada por un transportista para un nivel de servicio determinado.

  - `data.shipment_rate_data.base_rate.amount` (number)
    Example: 33.21

  - `data.shipment_rate_data.base_rate.currency` (string)
    Example: USD

  - `data.shipment_rate_data.base_rate.list_amount` (number)
    Example: 33.21

  - `data.shipment_rate_data.base_rate.retail_amount` (number)
    Example: 59.55

  - `data.shipment_rate_data.surcharges` (object)
    Representa un único recargo aplicado a un envío o tarifa.

  - `data.shipment_rate_data.surcharges.object` (string)
    El tipo de objeto, que indica que este elemento representa un recargo.

  - `data.shipment_rate_data.surcharges.type` (string)
    Un código que identifica el tipo específico de recargo.
Por ejemplo, `nonstandard_22` puede indicar un cargo por manejo de paquete no estándar.
    Example: nonstandard_22

  - `data.shipment_rate_data.surcharges.category` (string)
    La categoría del recargo, que agrupa tipos de cargos similares.
Ejemplos comunes incluyen `HANDLING`, `FUEL`, etc.
    Example: HANDLING

  - `data.shipment_rate_data.surcharges.amount` (number)
    El monto total del recargo cobrado por este elemento.
    Example: 4

  - `data.shipment_rate_data.surcharges.currency` (string)
    El código de moneda de tres letras (ISO 4217) del recargo.
    Example: USD

  - `data.shipment_rate_data.surcharges.list_amount` (number)
    Example: 4

  - `data.shipment_rate_data.surcharges.retail_amount` (number)
    Example: 4

  - `data.shipment_rate_data.usps_dim_rate_type` (string)
    Example: dim-weight

  - `data.shipment_rate_data.price_details` (array)
    Un desglose por componente de la tarifa. Específico de FedEx.

  - `data.shipment_rate_data.price_details.code` (string)
    Un código que identifica el componente del cargo.
Ejemplos comunes incluyen `BASE_CHARGE`, `FUEL`, `RESIDENTIAL_DELIVERY`,
`DEMAND_OVERSIZE`, `DEMAND`, `OVERSIZE` y `DELIVERY_AREA`.
    Example: BASE_CHARGE

  - `data.shipment_rate_data.price_details.description` (string)
    Una descripción legible del componente del cargo.
    Example: Shipping Label Charge

  - `data.shipment_rate_data.price_details.price` (number)
    El monto cobrado por este componente.
    Example: 99.31

  - `data.error_info` (object)