API atual/Referência completa/Expedição e retirada

GETRetiradas

Lista a fila de pedidos que os clientes vão retirar na loja do seller.

Quando o cliente escolhe uma forma de envio de retirada na loja, o pedido gera uma retirada. Esta rota é a fila de trabalho do seller: o que precisa ser separado, o que já está pronto esperando o cliente e o que já foi retirado. As ações sobre cada retirada estão em Ações da retirada.

GET/api/v1/vendor/pickupsSeller

Lista as retiradas do seller

Parâmetros de consulta

statusstring

awaiting_preparationreadypicked_upexpiredcancelled

Filtra por etapa. Um valor desconhecido não dá erro: simplesmente não casa com nada e a lista vem vazia.

warehouse_iduuid

Só as retiradas deste ponto de retirada.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/pickups?status=awaiting_preparation" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Fila de retiradas

json

{
  "pickups": [
    {
      "id": "c0ffee00-1234-4abc-9def-0123456789ab",
      "order_id": "b4d2f0a8-6c1e-4b3d-9a7f-2e5c8d1b0a96",
      "warehouse_id": "d3b07384-d9a0-4c1b-8d0e-7a1b2c3d4e5f",
      "vendor_id": "5f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "status": "ready",
      "code_attempts": 0,
      "ready_at": "2026-10-02T11:00:00Z",
      "expires_at": "2026-10-09T11:00:00Z",
      "created_at": "2026-10-01T14:20:11Z",
      "updated_at": "2026-10-02T11:00:00Z",
      "warehouse_name": "Loja Centro",
      "warehouse_address": "Rua das Flores, 120, Centro",
      "warehouse_city": "São Paulo",
      "warehouse_state": "SP",
      "warehouse_zipcode": "01310-100",
      "order_number": "VD-20261001-0042"
    }
  ]
}

Campos da resposta

pickupsarray

Retiradas do seller, da mais nova para a mais antiga. Sem paginação.

iduuid

Id da retirada.

order_iduuid

Pedido a retirar. Em carrinho com vários sellers é o pedido pai.

warehouse_iduuid

Ponto de retirada escolhido pelo cliente.

vendor_iduuid

Seller da retirada, quando conhecido.

statusstring

awaiting_preparationreadypicked_upexpiredcancelled

awaiting_preparation, ready, picked_up, expired ou cancelled.

code_attemptsinteger

Erros de código seguidos (0 a 4). Volta a 0 ao travar ou acertar.

code_locked_untilstring

Até quando a confirmação está travada. Ausente se não está.

delivery_schedule_iduuid

Horário de retirada agendado, quando o cliente escolheu um. Ausente se não.

ready_atstring

Quando foi marcada como pronta. Ausente antes.

picked_up_atstring

Quando foi retirada. Ausente antes.

expires_atstring

Prazo para o cliente retirar. Ausente se não definido.

created_at, updated_atstring

Criação e última alteração, RFC 3339.

warehouse_name, warehouse_address, warehouse_city, warehouse_state, warehouse_zipcodestring

Dados do ponto de retirada, para mostrar na fila.

order_numberstring

Número do pedido, o mesmo da lista de pedidos.

Erros

Status	Quando	Corpo de exemplo
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	O usuário não tem um dos privilégios de pedidos (veja a visão geral).	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_manage_orders","..."]}`
403	O usuário não tem conta de seller.	`{"error":"no vendor account associated with this user"}`
500	Falha ao consultar (por exemplo, `warehouse_id` que não é UUID).	`{"error":"failed to list pickups"}`

Veja também

GETRetiradas

Lista a fila de pedidos que os clientes vão retirar na loja do seller.

GET/api/v1/vendor/pickupsSeller

Lista as retiradas do seller

Parâmetros de consulta

statusstring

awaiting_preparationreadypicked_upexpiredcancelled

Filtra por etapa. Um valor desconhecido não dá erro: simplesmente não casa com nada e a lista vem vazia.

warehouse_iduuid

Só as retiradas deste ponto de retirada.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/pickups?status=awaiting_preparation" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Fila de retiradas

json

{
  "pickups": [
    {
      "id": "c0ffee00-1234-4abc-9def-0123456789ab",
      "order_id": "b4d2f0a8-6c1e-4b3d-9a7f-2e5c8d1b0a96",
      "warehouse_id": "d3b07384-d9a0-4c1b-8d0e-7a1b2c3d4e5f",
      "vendor_id": "5f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "status": "ready",
      "code_attempts": 0,
      "ready_at": "2026-10-02T11:00:00Z",
      "expires_at": "2026-10-09T11:00:00Z",
      "created_at": "2026-10-01T14:20:11Z",
      "updated_at": "2026-10-02T11:00:00Z",
      "warehouse_name": "Loja Centro",
      "warehouse_address": "Rua das Flores, 120, Centro",
      "warehouse_city": "São Paulo",
      "warehouse_state": "SP",
      "warehouse_zipcode": "01310-100",
      "order_number": "VD-20261001-0042"
    }
  ]
}

Campos da resposta

pickupsarray

Retiradas do seller, da mais nova para a mais antiga. Sem paginação.

iduuid

Id da retirada.

order_iduuid

Pedido a retirar. Em carrinho com vários sellers é o pedido pai.

warehouse_iduuid

Ponto de retirada escolhido pelo cliente.

vendor_iduuid

Seller da retirada, quando conhecido.

statusstring

awaiting_preparationreadypicked_upexpiredcancelled

awaiting_preparation, ready, picked_up, expired ou cancelled.

code_attemptsinteger

Erros de código seguidos (0 a 4). Volta a 0 ao travar ou acertar.

code_locked_untilstring

Até quando a confirmação está travada. Ausente se não está.

delivery_schedule_iduuid

Horário de retirada agendado, quando o cliente escolheu um. Ausente se não.

ready_atstring

Quando foi marcada como pronta. Ausente antes.

picked_up_atstring

Quando foi retirada. Ausente antes.

expires_atstring

Prazo para o cliente retirar. Ausente se não definido.

created_at, updated_atstring

Criação e última alteração, RFC 3339.

warehouse_name, warehouse_address, warehouse_city, warehouse_state, warehouse_zipcodestring

Dados do ponto de retirada, para mostrar na fila.

order_numberstring

Número do pedido, o mesmo da lista de pedidos.

Erros

Status	Quando	Corpo de exemplo
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	O usuário não tem um dos privilégios de pedidos (veja a visão geral).	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_manage_orders","..."]}`
403	O usuário não tem conta de seller.	`{"error":"no vendor account associated with this user"}`
500	Falha ao consultar (por exemplo, `warehouse_id` que não é UUID).	`{"error":"failed to list pickups"}`