Enviadores Public API

1# Ensaya con ek_test_ (sandbox). Con ek_live_ esto genera una guía real y cobra créditos.2​3# 0. Verifica tu clave4curl https://api.enviadores.com.mx/api/v1/balance -H "Authorization: Bearer ek_test_TU_CLAVE"5​6# 1. Cotiza (todas las paqueterías)7curl https://api.enviadores.com.mx/api/v1/rates \8  -H "Authorization: Bearer ek_test_TU_CLAVE" \9  -H "Content-Type: application/json" \10  -d '{11    "from": { "postal_code": "01000" },12    "to":   { "postal_code": "64000" },13    "package": { "weight_kg": 1, "length_cm": 20, "width_cm": 15, "height_cm": 10 }14  }'15# → { "services": [ { "id": "e2etest_E2ETestCarrier_E2EStandard_ab12cd34",16#       "service_name": "E2E Standard",17#       "pricing": { "total_price": 145.50, ... } }, ... ],18#     "rate_id_expires_in_seconds": 1800 }19# (el id es OPACO: cópialo tal cual, no interpretes ni valides su formato)20​21# 2. Crea el envío — pega en rate_id el id del paso 1 (Idempotency-Key fresco por envío)22curl https://api.enviadores.com.mx/api/v1/shipments \23  -H "Authorization: Bearer ek_test_TU_CLAVE" \24  -H "Idempotency-Key: 6f9c2b1e-8d4a-4f3b-9c2e-1a7b8d4f3c2e" \25  -H "Content-Type: application/json" \26  -d '{27    "rate_id": "PEGA_AQUI_EL_ID_DEL_PASO_1",28    "from": {29      "name": "Juan Pérez", "phone": "5512345678",30      "street": "Av. Insurgentes Sur", "number": "600",31      "colonia": "Del Valle", "city": "Ciudad de México",32      "state": "CDMX", "postal_code": "01000"33    },34    "to": {35      "name": "María López", "phone": "8187654321",36      "street": "Av. Constitución", "number": "400",37      "colonia": "Centro", "city": "Monterrey",38      "state": "Nuevo León", "postal_code": "64000"39    },40    "package": { "weight_kg": 1 },41    "contenido": "Ropa"42  }'43​44# 3. Descarga la etiqueta · 4. Cancela si hace falta45curl -L https://api.enviadores.com.mx/api/v1/labels/ENVIO_ID -H "Authorization: Bearer ek_test_TU_CLAVE" -o etiqueta.pdf46curl https://api.enviadores.com.mx/api/v1/cancellations -H "Authorization: Bearer ek_test_TU_CLAVE" \47  -H "Content-Type: application/json" -d '{ "shipment_id": "ENVIO_ID" }'

Autenticación

Manda tu clave en el header Authorization de cada petición:

Authorization: Bearer ek_live_TU_CLAVE

• Las claves son secretas y solo para uso server-to-server: nunca las pongas en un navegador ni en una app móvil. Esta superficie no habilita CORS por diseño.
• Nunca envíes la clave por query string.
• Una clave desconocida, revocada o ausente responde 401 UNAUTHORIZED de forma idéntica (sin revelar cuál caso fue).

Formato de respuesta

Toda respuesta JSON usa un sobre estable:

{
  "success": true,
  "data": { … },
  "requestId": "req_…"
}

{
  "success": false,
  "error": { "code": "…", "message": "…", "details": { … } },
  "requestId": "req_…"
}

• error.details es opcional.
• El requestId también viaja en el header X-Request-Id; inclúyelo al reportar un problema.
• Los códigos de error.code son estables y aptos para lógica de máquina — ver Errores y reintentos.

Límites de tasa

El límite es por clave (token bucket):

Ante un 429, respeta Retry-After con backoff exponencial.

Idempotencia

Manda un header Idempotency-Key en POST /shipments: un UUID fresco por operación lógica, de 1–128 caracteres ASCII imprimibles. La clave queda ligada al cuerpo exacto de la primera solicitud y al X-PDV-ID con que se envió.

Catálogo de servicios bloqueado

Algunas cuentas empiezan con el catálogo limitado: pueden ver todas las tarifas, pero solo pueden generar guías de:

• iMile Terrestre
• Estafeta Terrestre y Estafeta Día Siguiente sin recolección (en estas dos el remitente deja el paquete en una sucursal Estafeta y cualquier cargo extra —sobrepeso, servicios adicionales— se paga ahí).

Todo lo demás llega bloqueado, incluidos los servicios sin recolección de otros transportistas. Aplica a cuentas de registro propio que aún no verifican su identidad. No aplica a cuentas creadas por nuestro equipo.

Cómo detectarlo ANTES de crear el envío

1. 1
   Cada tarifa de POST /rates trae booking_locked (booleano). Si es true, esa tarifa NO es reservable por esta cuenta y POST /shipments responderá 403 SERVICE_UNLOCK_REQUIRED.
2. 2
   Cuando el catálogo está limitado, la respuesta también trae unlock_notice: un texto en español, listo para mostrarle al usuario, que explica cómo desbloquearlo.
3. 3
   Filtra por booking_locked === false antes de ofrecer opciones y nunca verás este error.

Cómo se desbloquea

Cualquiera de las dos, sin trámite con nosotros:

• verificar la identidad (INE) desde Mi cuenta, o
• acumular $2,500 MXN en recargas.

Al cumplirse, el catálogo completo queda disponible de inmediato y booking_locked pasa a false en la siguiente cotización.

Bultos, seguro y valor declarado

Una caja o varias

Tanto en POST /rates como en POST /shipments, manda uno de los dos — nunca ambos (422):

• Una cotización con varios bultos solo devuelve servicios que pueden llevar varias cajas juntas.
• El peso facturable es la SUMA de las cajas.
• La petición de creación debe llevar la MISMA lista que cotizaste; una lista distinta responde 409 RATE_PACKAGE_MISMATCH.
• Los códigos postales deben existir en el catálogo SEPOMEX: un CP inexistente (p. ej. 99999) responde 422 nombrando from.postal_code / to.postal_code antes de consultar a ninguna paquetería.

Medidas de la caja

Cada caja lleva su peso y el largo, ancho y alto exteriores de la caja ya cerrada:

Sin las tres medidas:

Es decir: sin las tres medidas el precio es estimado y no se puede generar la guía.

Vista agrupada

POST /rates?view=grouped lista cada servicio de envío distinto UNA sola vez (paquetería + nivel de servicio, p. ej. DHL · Express) con su rango de precios (price_from–price_to) y sus options[] reservables:

• Primero las que esta cuenta puede reservar (booking_locked:false), cada mitad de la más barata a la más cara.
• Reserva options[0].rate_id salvo que el usuario pida otra cosa.
• La forma plana por omisión no cambia.

Seguro vs. valor declarado — dos cosas distintas

Ejemplos de respuesta

Cuerpos de ejemplo (recortados, datos ficticios) del sobre de éxito de los endpoints principales. El id de una tarifa es OPACO: cópialo tal cual a POST /shipments — su formato no es parte del contrato y no debes interpretarlo ni validarlo (cambia entre el carril de prueba y el live).

Errores y reintentos

Todos los errores usan el sobre error.code estable. error.details lleva el contexto por código — la lista de campos en un 422, o los montos en un 402:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": { "fields": ["from.postal_code: must be a 5-digit Mexican postal code"] }
  },
  "requestId": "req_b0c1d2e3f4"
}

{
  "success": false,
  "error": {
    "code": "PACKAGE_DIMENSIONS_REQUIRED",
    "message": "Indica largo, ancho y alto de la caja ya cerrada (length_cm, width_cm, height_cm) y cotiza de nuevo.",
    "details": { "fields": ["package.length_cm", "package.width_cm", "package.height_cm"] }
  },
  "requestId": "req_d2e3f4a5b6"
}

{
  "success": false,
  "error": {
    "code": "CREDIT_ERROR",
    "message": "Créditos insuficientes. Necesitas $145.50 MXN. Disponible: $80.00 MXN",
    "details": { "required": 145.5, "available": 80, "shortfall": 65.5 }
  },
  "requestId": "req_c1d2e3f4a5"
}

Referencia rápida

Si conviene reintentar y qué hacer con cada código:

OpenAPI y SDKs

El documento OpenAPI 3.1 se sirve en https://api.enviadores.com.mx/api/v1/openapi.json. Genera un cliente PHP/Node/Python con openapi-generator:

npx @openapitools/openapi-generator-cli generate \
  -i https://api.enviadores.com.mx/api/v1/openapi.json \
  -g php -o ./enviadores-php

Cambia -g php por -g typescript-fetch o -g python para otros lenguajes. También puedes importar el spec como colección de Postman.

Webhooks

En lugar de consultar GET /shipments o GET /tracking/{guia} una y otra vez (polling), registra un endpoint https:// público y recibe un POST firmado por cada evento. Hasta 5 webhooks activos por cuenta (por modo).

Eventos

Todos los eventos usan este sobre; solo cambian event y data.

Registro

1. 1
   Registra tu endpoint y los eventos que quieres recibir:

   cURL

   1curl -X POST https://api.enviadores.com.mx/api/v1/webhooks \2  -H "Authorization: Bearer ek_live_..." \3  -H "Content-Type: application/json" \4  -d '{"url":"https://hooks.mitienda.com/enviadores","events":["shipment.created","shipment.delivered","shipment.exception"]}'5# 201 → data.webhook.id = "wh_…", data.secret = "whsec_…"  (se muestra UNA sola vez)

2. 2
   Guarda el secret de la respuesta 201. Se devuelve una sola vez: se deriva, no se almacena y no se puede volver a mostrar.
3. 3
   Prueba la conexión: POST /webhooks/{id}/test envía un ping firmado de inmediato y reporta si tu endpoint respondió 2xx.

Verifica la firma

Cada entrega trae tres headers:

Para aceptar una entrega:

1. 1
   Recomputa el HMAC-SHA256 con tu secret sobre <t>.<raw body>: los bytes crudos del cuerpo, tal como llegaron.
2. 2
   Compáralo con v1 en tiempo constante.
3. 3
   Rechaza un t con más de 5 minutos de antigüedad.

1// Node.js — verifica X-Enviadores-Signature sobre el cuerpo CRUDO2import { createHmac, timingSafeEqual } from 'node:crypto';3​4export function verifyEnviadores(rawBody, signatureHeader, secret, toleranceSeconds = 300) {5  const parts = Object.fromEntries(signatureHeader.split(',').map((kv) => kv.split('=')));6  const t = Number(parts.t);7  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;8  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');9  const given = Buffer.from(parts.v1 ?? '', 'hex');10  return given.length === 32 && timingSafeEqual(Buffer.from(expected, 'hex'), given);11}

Reglas de entrega

Qué URL se acepta

Política de URL (SSRF):

• Solo https://, en el puerto 443 o 8443.
• Con nombre de host público: sin localhost, .local, .internal, IPs privadas o de loopback, hosts que resuelvan a ellas, ni el propio API de Enviadores.
• Sin credenciales incrustadas.
• El ping de prueba reporta una clase de error general (timeout, connection failed, non-2xx status), nunca el detalle de red.

Modo de prueba (sandbox)

Las claves ek_test_ autentican y consumen los mismos scopes y límites que las live, pero operan en un carril de persistencia paralela: escriben y leen en tablas de sandbox, nunca tocan las tablas de dinero de producción y NO mueven dinero real. Cada endpoint transaccional devuelve el MISMO esquema JSON que el carril live.

Fallas forzadas

Manda metadata.test_scenario en POST /shipments con uno de estos valores:

Cambios

Los cambios dentro de v1 serán aditivos; un cambio incompatible se anunciará aquí y saldría como /v2.

• 2026-11-12

  Spec 1.2.0Solo documentación

  Sin cambios de comportamiento. El documento OpenAPI declara ahora cada evento de webhook en webhooks (OpenAPI 3.1) con su esquema y un ejemplo completo, así que los generadores de clientes y los agentes de IA ven el cuerpo exacto que recibirá tu endpoint. La referencia se mudó a su propia página, /desarrolladores/referencia, y cada endpoint trae un ejemplo listo para copiar en cURL, JavaScript, Python y PHP. Ver Webhooks.
• 2026-11-04

  Medidas de la caja

  POST /shipments exige largo, ancho y alto de cada caja: sin ellos responde 422 PACKAGE_DIMENSIONS_REQUIRED (antes se generaba la guía para una caja de 10×10×10 cm). POST /rates sigue cotizando sin medidas, pero marca la respuesta con size_estimated: true y size_notice (campos nuevos, aditivos). En la vista agrupada, options[] pone primero las opciones reservables, así que options[0] nunca es una tarifa bloqueada si el servicio tiene alguna abierta. Las cuentas con catálogo limitado solo pueden reservar iMile Terrestre, y Estafeta Terrestre y Día Siguiente sin recolección. Ver Bultos, seguro y valor declarado.
• 2026-09-21

  Etiquetas servidas desde EnviadoresCompatible

  GET /labels/{id} transmite nuestra copia y ya no redirige (302) a la URL de la paquetería. Con ?format=json (herramienta MCP get_label), label_url es un enlace firmado a /v1/label-files/… que se abre sin llave y vence en el nuevo campo expires_at (30 días); pide uno nuevo con la misma llamada. label_url sigue siendo una URL de PDF.
• 2026-09-04

  Varios bultos, vista agrupada y seguroAditivo

  Ahora se acepta packages (2–10 cajas, un solo envío) en POST /rates y POST /shipments (antes respondía 422); POST /rates?view=grouped devuelve una entrada por servicio distinto con su rango de precios y sus opciones reservables; el campo de seguro de la cotización ahora es insurance.insured_value (declared_value dentro de insurance queda como alias obsoleto) y POST /shipments acepta insurance y un declared_value raíz aparte (declaración a la paquetería). Los códigos postales deben existir en SEPOMEX en ambos endpoints. Ver Bultos, seguro y valor declarado.
• 2026-09-04

  WebhooksAditivo

  Nuevos endpoints POST/GET /webhooks, GET/DELETE /webhooks/{id} y POST /webhooks/{id}/test, con eventos de envíos y recolecciones firmados con HMAC-SHA256 (X-Enviadores-Signature), reintentos con espera creciente y desactivación automática. Nuevos scopes webhooks:write / webhooks:read (las llaves con permisos por omisión los adquieren solas). Ver Webhooks.
• 2026-08-30

  Catálogo limitado y booking_lockedAditivo

  Nuevo campo booking_locked en cada tarifa de POST /rates, y unlock_notice a nivel de la respuesta. Las cuentas de registro propio sin identidad verificada ven todas las tarifas pero solo pueden generar guías de Estafeta Terrestre y Día Siguiente sin recolección, e iMile Terrestre (desde el 2026-11-04; antes, cualquier servicio sin recolección); reservar una tarifa bloqueada responde 403 SERVICE_UNLOCK_REQUIRED. Las integraciones existentes no se rompen — en cuentas sin restricción booking_locked siempre es false y unlock_notice es null. Ver Catálogo de servicios bloqueado.
• 2026-07-28

  Dimensiones guardadas con el envío

  Las dimensiones declaradas (largo/ancho/alto) ahora se guardan con el envío. Antes solo se usaban para calcular el peso volumétrico y se descartaban, por lo que en envíos anteriores a esta fecha packages[].length_cm y sus pares llegan en null. El peso sí está disponible en todo el histórico.
• 2026-07-27

  Lectura de envíosCambio de contrato

  /shipments acepta ?guia=, ?status= y ?from=/?to=; cada envío incluye ahora lo capturado al crearlo (packages, billable_weight_kg, declared_value, content) y el sender. Nuevo scope ampliado shipments:read:pdv para listar los envíos de todo un PDV con X-PDV-ID. La búsqueda ?q= del directorio ahora abarca teléfono, email y dirección, con coincidencia por palabra. Cambio de contrato: X-PDV-ID ya se valida en las rutas de envíos y cancelaciones — un PDV fuera de la allowlist responde 403 en lugar de ignorarse.
• 2026-07-13

  Respuesta de /rates saneadaBreaking pre-adopción

  v1: respuesta de /rates saneada a snake_case; rechazo explícito de country≠MX / campos desconocidos (y de packages, aceptado desde 2026-09-04); tope de gasto opcional por llave; allowlist de PDV denegada por defecto.
• 2026-07-12

  Lanzamiento de la API pública v1

1claude mcp add --transport http enviadores https://api.enviadores.com.mx/api/v1/mcp \2  --header "Authorization: Bearer ek_test_..."

1{2  "mcpServers": {3    "enviadores": {4      "url": "https://api.enviadores.com.mx/api/v1/mcp",5      "headers": { "Authorization": "Bearer ek_test_..." }6    }7  }8}

1curl -X POST https://api.enviadores.com.mx/api/v1/mcp \2  -H "Authorization: Bearer ek_test_..." \3  -H "Content-Type: application/json" \4  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'