shipments

Listar envíos (paginado)

Por defecto: solo envíos creados por el usuario de la llave, para TODOS los roles — una llave admin ve únicamente sus propios envíos de cuenta de servicio.

Alcance por PDV (opt-in). Una llave admin que envía X-PDV-ID y tiene el scope shipments:read:pdv lista en cambio los envíos de ese punto de venta, sin importar qué operador los creó — el mismo fondo que ya responden /senders, /recipients y /balance bajo ese header. Sin el scope, el header no amplía nada y sigues viendo solo lo tuyo (los integradores que ya lo envían no cambian de resultados).

Cambio de contrato (2026-07): X-PDV-ID ahora se valida en esta ruta aunque no amplíe nada. Antes se ignoraba por completo, así que un PDV inexistente o fuera de la allowlist de la llave respondía 200 con lista vacía mientras /senders respondía 403; ahora responde 403 PDV_NOT_ALLOWED como todas las rutas hermanas.

Orden: más recientes primero. Requiere scope shipments:read (+ shipments:read:pdv para el alcance por PDV).

get/shipments

Request

  • Base URL: https://api.enviadores.com.mx/api/v1
  • URL: https://api.enviadores.com.mx/api/v1/shipments
  • Auth: HTTP bearer

Query parameters

pageinteger
limitinteger
guiastring

Búsqueda exacta por número de guía. Es la forma de llegar a un envío cuando solo tienes el número que ve el cliente (el id interno no es adivinable). Devuelve una página de 0 o 1 elementos, sujeta a la misma visibilidad que el resto del listado.

status'created' | 'collected' | 'in_transit' | 'out_for_delivery' | 'delivered' | 'exception' | 'returned' | 'cancelled' | 'unknown'

Filtra por estatus canónico — exactamente el mismo valor que devuelve el campo status de cada envío. Un valor fuera del enum es 422 VALIDATION_ERROR, nunca una lista vacía silenciosa.

fromstring date

Día calendario INCLUSIVO (zona horaria de negocio America/Mexico_City) desde el cual listar, por fecha de creación. Solo YYYY-MM-DD.

tostring date

Día calendario INCLUSIVO (America/Mexico_City) hasta el cual listar — el día completo, hasta las 23:59:59 locales. from posterior a to es 422.

Headers

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.

Response

Página de envíos.

successunknown required
requestIdstring required

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

Changes

No recorded changes to this operation across all 1 revision of this API.