Consulta tarifas de mercado con la API

Qué devuelve la API de Tarifas de Mercado, cómo obtener una clave y qué saber sobre lotes, caché y datos de prueba antes de construir.

Broker

Updated

October 2, 2026

En 4 pasos

Pide una clave a tu contacto en Cargado
Envía una consulta a POST /rates/history
Lee los resultados ruta por ruta
Prueba primero en el sandbox

La API de Tarifas de Mercado lleva el mismo rango Bajo, Medio y Alto que ves en la plataforma a tu propio TMS, herramienta de precios o pantalla de cotización. Envías una ruta y recibes un historial semanal de tarifas; la entrada más reciente es la que muestra la plataforma. La referencia completa está en docs.cargado.com.

Paso 1: Pide una clave a tu contacto en Cargado

Pide a tu contacto en Cargado una clave de API con el permiso de tarifas de mercado. En Obtén una clave de API para tu integración explicamos cómo funcionan las claves y cómo protegerlas. Envía la clave en el encabezado api-key en cada solicitud a https://api.cargado.com.

Paso 2: Envía una consulta a POST /rates/history

Llama a POST /rates/history con una lista requests de 1 a 16 rutas. Cada ruta necesita:

Paradas: una recolección al inicio y una entrega al final. Cada lugar puede ser una ciudad estructurada, un código postal, una dirección o una dirección en texto libre.
Remolque: exactamente un tipo de remolque.
Cruce (opcional, solo en rutas que cruzan la frontera entre Estados Unidos y México): agrega una parada de cruce fronterizo, o déjala fuera y Cargado usa su cruce recomendado y lo reporta en pricingLane. No la agregues en una ruta que no cruza la frontera.
Millas de la ruta (opcional): tu propia distancia, si quieres que sustituya la de Cargado.

Agrega currency (USD, MXN o CAD) a la solicitud. Por defecto es USD.

Arriba: un editor de código, oscurecido, con el cuerpo de la solicitud a POST https://api.cargado.com/rates/history resaltado y marcado como Paso 2. Abajo, de cerca: la solicitud de una ruta, Monterrey a Chicago, caja seca. La marca 1 señala la lista stops. La marca 2 señala la parada BORDER_CROSSING con usMxBorderCrossing LAREDO_INTL_BRIDGE. La marca 3 señala trailerRequirements con allowedTypes DRY_VAN.

Ejemplo: una ruta de muestra; la clave del editor es ficticia y está oculta.

stops: la recolección primero y la entrega al final.
BORDER_CROSSING: la parada de cruce fronterizo, opcional y solo en rutas que cruzan la frontera entre Estados Unidos y México. Aquí, Laredo.
trailerRequirements: exactamente un tipo de remolque.

Paso 3: Lee los resultados ruta por ruta

Los resultados llegan en el mismo orden que tus solicitudes, uno por ruta, cada uno marcado como DATA o ERROR. Un resultado DATA incluye:

La ruta consultada: el origen y el destino (el mercado al que se asignó cada uno, y si es un mercado extendido), la categoría de remolque y el cruce.
suggestedRates, allInRates y perMileRates: entradas semanales, de la más antigua a la más reciente. Cada una trae p25, p50 y p75 en la unidad menor de la moneda; el margen de error y la confianza se incluyen cuando Cargado los tiene. Las tres series no siempre cubren las mismas semanas: perMileRates solo tiene entradas donde existe una distribución por milla.
latestSuggestedRate: la cifra que la plataforma muestra como Bajo, Medio y Alto.
Las millas de la ruta, con y sin el movimiento vacío hasta los centros de los mercados.

Puede faltar alguna semana. Si una ruta no tiene historial, recibes un resultado ERROR con el código RATE_HISTORY_NOT_FOUND; hay otros códigos de error para otras fallas.

Arriba: un editor de código, oscurecido, con el primer resultado de la respuesta resaltado y marcado como Paso 3. Abajo, de cerca: un resultado DATA con rateHistory, currencyCode USD y latestSuggestedRate. La marca 1 señala type DATA. La marca 2 señala amountDistribution con p25 300000, p50 330000 y p75 362000. La marca 3 señala confidence STRONG.

Ejemplo: los montos y la etiqueta de confianza son ilustrativos, no una cotización real.

type: DATA o ERROR, uno por ruta.
amountDistribution: p25, p50 y p75 en centavos. 330000 es $3,300.
confidence: STRONG, MEDIUM o LOWER cuando viene, igual que en la plataforma.

Paso 4: Prueba primero en el sandbox

Pide al equipo de Cargado acceso al sandbox en https://api.sandbox.cargado.com. Por defecto el sandbox devuelve tarifas simuladas, así que úsalo para probar tu integración, nunca para cotizar.

Importante: una solicitud admite hasta 16 rutas y las tarifas semanales llegan de la más antigua a la más reciente.

Para tomar en cuenta

Uso y reutilización: para las empresas de logística, los resultados exitosos de cada ruta cuentan para el uso medido del plan, igual que las consultas en la plataforma y en Excel, sujetos a deduplicación: las consultas repetidas de la misma ruta cuentan una vez por versión de los datos, mercados, categoría de remolque y cruce, y una versión nueva de los datos vuelve a contar. Aparte, Cargado reutiliza un resultado guardado en lugar de crear una consulta nueva cuando ya tiene uno para la misma organización, la misma solicitud, la misma moneda y la misma versión de los datos de tarifas. Consulta Límites del plan y qué significan los correos de aviso de uso.
Consultas guardadas: puedes recuperar una consulta guardada por su id con GET /rates/history/{id}.
Una ruta con error no afecta el lote: en una solicitud válida, una ruta sin datos regresa como ERROR con el código RATE_HISTORY_NOT_FOUND y las demás rutas se procesan de forma independiente. Un cuerpo de solicitud mal formado falla completo antes de consultar cualquier ruta.
Moneda: los montos vienen en la unidad menor de la moneda que pediste: centavos de dólar para USD y CAD, centavos de peso para MXN. En USD, 330000 es $3,300.
Millas de la ruta: cada resultado DATA incluye las millas de la ruta, con y sin el movimiento vacío hasta los centros de los mercados. Si enviaste tu propio routeMiles, los dos valores usan tu cifra.
Referencia: los endpoints están documentados en docs.cargado.com.