---
title: "Listar tus solicitudes de recolección"
method: GET
path: "/pickups"
tags: ["pickups"]
---

# Listar tus solicitudes de recolección

`GET /pickups`

## Request

- Base URL: `https://api.enviadores.com.mx/api/v1`
- URL: `https://api.enviadores.com.mx/api/v1/pickups`
- Auth: HTTP bearer

Las solicitudes de recolección de la cuenta, de la más reciente a la más antigua — qué pediste, para cuándo, y si nuestro equipo ya la gestionó.

Visibilidad idéntica a la del listado de envíos: por omisión las recolecciones de los envíos que creó el usuario de la llave; con `X-PDV-ID` validado **y** el scope ampliado `shipments:read:pdv`, las de ese punto de venta (las dos ramas son EXCLUYENTES). Mientras la programación de recolecciones no esté habilitada en la cuenta, este listado responde **200 con una página vacía** — un listado de algo que no puedes usar no tiene nada que reportar. Requiere scope `pickups:read`.

## Query parameters

- `page` integer
- `limit` integer
- `status` 'pending' | 'scheduled' | 'awaiting_confirmation' | 'failed' | 'cancelled'

## Headers

- `X-PDV-ID` string

## Response `200`

Página de solicitudes de recolección.

- object
  - `success` unknown, required
  - `data` object, required
    - `pickups` Pickup[], required
      - `id` integer, required: Id numérico de la recolección.
      - `display_id` string, required: Live: formato `PR%08d`. Sandbox: `SBX-PU-<id>`.
      - `shipment_id` string, nullable, required
      - `status` 'pending' | 'scheduled' | 'awaiting_confirmation' | 'failed' | 'cancelled', required: Una solicitud SIEMPRE nace en `awaiting_confirmation` (se está gestionando; NO la presentes como confirmada). Pasa a `scheduled` cuando el equipo la confirma con la paquetería — ahí llegan `confirmed_window_*` y `confirmation_number`, y se envía el correo al solicitante. `failed` = no se pudo agendar (entregar en sucursal). `cancelled` = la canceló quien la pidió. `pending` no se usa. El sandbox devuelve `awaiting_confirmation`, igual que producción.
      - `carrier` string, nullable: Paquetería física que hará la recolección.
      - `requested_window_start` string, nullable: ISO-8601 UTC (Z). Inicio de la ventana solicitada.
      - `requested_window_end` string, nullable: ISO-8601 UTC (Z). Fin de la ventana solicitada.
      - `confirmed_window_start` string, nullable: ISO-8601 UTC (Z). Ventana confirmada por la paquetería, cuando la devuelve.
      - `confirmed_window_end` string, nullable: ISO-8601 UTC (Z).
      - `confirmation_number` string, nullable: Folio/referencia de recolección de la paquetería.
      - `created_at` string, nullable
      - `updated_at` string, nullable
    - `pagination` Pagination, required
      - `page` integer, required
      - `limit` integer, required
      - `total` integer, required
  - `requestId` string, required: Correlación de logs; también en el header `X-Request-Id`.

## Other responses

- `401`: `UNAUTHORIZED` — credencial Bearer ausente/mal formada o llave desconocida/revocada (respuesta idéntica en ambos casos).
- `403`: `INSUFFICIENT_SCOPE` — a la llave le falta el scope requerido · `PDV_NOT_ALLOWED` — violación del carril X-PDV-ID. Nota de orden: el limitador por llave corre ANTES del gate de scope, así que una petición con scope incorrecto y el bucket agotado responde `429 RATE_LIMITED` (el 429 tiene precedencia sobre este 403).
- `404`: `NOT_FOUND` — ruta desconocida, recurso ajeno/inexistente, o la API pública no está habilitada (respuestas indistinguibles por diseño).
- `422`: `VALIDATION_ERROR` — `status` fuera del enum o paginación inválida (campos en `details.fields`).
- `429`: `RATE_LIMITED` — bucket de la llave agotado. Espera `Retry-After` s (`details.retry_after_ms` para el hint fino). El limitador corre antes del gate de scope, por lo que un 429 tiene precedencia sobre un 403 `INSUFFICIENT_SCOPE`.
- `500`: `GET_ERROR`.

---

[API](https://skmtc.dev/enviadores/apis/enviadores-public-api.md) · [All operations](https://skmtc.dev/enviadores/apis/enviadores-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/enviadores/apis/enviadores-public-api/revisions/3633f08c889c?raw)