shipments

Crear un envío (genera la guía y cobra créditos)

Crea el envío contra un rate_id vigente (≤ 30 min) cotizado con la MISMA llave (y mismo PDV, si aplica). Solo domésticos MX (customs/ocurre, country ≠ MX o campos desconocidos → 422). Bultos: los MISMOS que se cotizaron — package (uno) o packages (2–10 en un solo envío; ambos → 422); un conjunto distinto al cotizado responde 409 RATE_PACKAGE_MISMATCH. CP: origen/destino inline deben existir en SEPOMEX (422 nombrando from.postal_code/to.postal_code, antes de retener saldo). Seguro vs. valor declarado (no son lo mismo): insurance.insured_value es la póliza de plataforma que YA se cotizó — debe coincidir con la cotización (422 INSURANCE_MISMATCH si difiere o falta; el total firmado nunca se recalcula al crear); declared_value es el valor de la mercancía que se declara a la paquetería (MXN, informativo; algunos servicios lo exigen — DECLARED_VALUE_REQUIRED). Remitente/destinatario van inline (la plataforma crea o reutiliza los registros del directorio con dedupe exacto normalizado) o por referencia (from_id/to_id del directorio — la fila guardada se usa tal cual). El cargo sigue el ciclo autorizar→capturar/anular — un envío rechazado nunca deja fondos retenidos. Usa Idempotency-Key en todo intento.

Idempotency-Keystring

UUID fresco por operación lógica (1–128 caracteres ASCII imprimibles; presente pero inválida → 400 IDEMPOTENCY_KEY_INVALID). Un reintento con la misma llave Y el mismo cuerpo repite la respuesta 2xx original (Idempotent-Replay: true) sin doble cargo, durante 15 minutos. La llave queda ligada al cuerpo exacto de la primera solicitud y al X-PDV-ID: cuerpo distinto → 409 IDEMPOTENCY_KEY_PAYLOAD_MISMATCH; pasados los 15 min → 409 IDEMPOTENCY_KEY_EXPIRED. Cambio 2026-08: ya NO se comparte espacio de nombres con el carril web del mismo usuario (antes una llave se repetía entre /v1/shipments y la app web; ahora eso responde 409 IDEMPOTENCY_KEY_REUSED). Fuertemente recomendado en POST /shipments.

X-PDV-IDstring

Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (pdv_allowlist); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → 403 PDV_NOT_ALLOWED. El valor personal_account equivale a omitir el header.

Request body

rate_idstring required

El id de una tarifa de POST /rates cotizada con esta misma llave (y mismo X-PDV-ID, si se usó), con menos de 30 minutos. Trátalo como OPACO: cópialo tal cual; su formato no es parte del contrato (difiere entre el carril de prueba y el live) y no debe interpretarse ni validarse.

from_idstring

Id de un remitente del directorio. Mutuamente excluyente con from.

to_idstring

Id de un destinatario del directorio (debe pertenecer al from_id enviado). Mutuamente excluyente con to; requiere from_id.

declared_valuenumber

Valor de la mercancía DECLARADO A LA PAQUETERÍA (MXN). NO es seguro, pero la paquetería puede cobrarlo: debe ser EXACTAMENTE el valor con el que se cotizó (el asegurado) — un valor que la cotización no llevaba responde 422 DECLARED_VALUE_MISMATCH, salvo en servicios que lo tratan como informativo (la recuperación de DECLARED_VALUE_REQUIRED). Si se omite se declara el valor cotizado; si la cotización no llevaba ninguno, no se inventa. declared_value must equal the value the rate was quoted with; a carrier may price it.

contenidostring

Descripción del contenido (aparece en la guía cuando la paquetería lo soporta).

referencestring

RESERVADO — aceptado pero no persistido en v1.

Example request

{
  "rate_id": "e2etest_E2ETestCarrier_E2EStandard_ab12cd34",
  "from": {
    "name": "Juan Pérez",
    "phone": "5512345678",
    "street": "Av. Insurgentes Sur",
    "number": "600",
    "colonia": "Del Valle",
    "city": "Ciudad de México",
    "state": "CDMX",
    "postal_code": "01000"
  },
  "to": {
    "name": "María López",
    "phone": "8187654321",
    "street": "Av. Constitución",
    "number": "400",
    "colonia": "Centro",
    "city": "Monterrey",
    "state": "Nuevo León",
    "postal_code": "64000"
  },
  "package": {
    "weight_kg": 1
  },
  "contenido": "Ropa"
}

Response

Envío creado (o repetido idempotentemente — header Idempotent-Replay: true; o deduplicado contra una guía existente — duplicate: true, en cuyo caso carrier/service pueden ser null).

successunknown required

requestIdstring required

Correlación de logs; también en el header X-Request-Id.

Crear un envío (genera la guía y cobra créditos)

Request

Headers

Request body

Example request

Response

Changes