API atual/Referência completa/Frete: áreas e retirada

Retirada em loja

Lista as retiradas em loja e conduz cada uma de aguardando preparo até pronta, retirada ou cancelada.

Na retirada em loja (BOPIS, "buy online, pick up in store") o cliente compra pelo site e busca o pedido num ponto da loja, em vez de receber em casa. Para cada pedido assim a plataforma abre uma retirada ligada a um depósito. O fluxo do balcão tem três passos: separar o pedido e marcar como pronto, receber o cliente e confirmar com o código que só ele tem, ou cancelar.

Ler exige view_shipping ou manage_shipping; as três ações exigem manage_shipping. Os estados e a regra de bloqueio do código estão na visão geral.

Listar retiradas

Devolve as retiradas da mais nova para a mais antiga, sem paginação, com o nome e o endereço do depósito e o número do pedido. O código de retirada não vem: ele só é visto pelo cliente.

GET/api/v1/admin/pickupsAdmin

Lista as retiradas em loja

Parâmetros de consulta

statusstring

awaiting_preparationreadypicked_upexpiredcancelled

Filtra por estado. Ausente lista todos.

warehouse_iduuid

Só as retiradas deste depósito. Um valor que não é UUID dá 500.

Exemplo de requisição

bash

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

Resposta

200Retiradas retornadas

json

{
  "pickups": [
    {
      "id": "c3a1f0de-5b2e-4a77-9c41-0d6e8f1b2a33",
      "order_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
      "warehouse_id": "5e0a9c1d-7b3f-4d2a-8e6c-1f4b9a0c7d52",
      "status": "awaiting_preparation",
      "code_attempts": 0,
      "expires_at": "2026-10-18T12:00:00Z",
      "created_at": "2026-10-11T12:00:00Z",
      "updated_at": "2026-10-11T12:00:00Z",
      "warehouse_name": "Loja Centro",
      "warehouse_address": "Rua das Flores, 100",
      "warehouse_city": "São Paulo",
      "warehouse_state": "SP",
      "warehouse_zipcode": "01310100",
      "order_number": "PEDIDO-20261011-0004"
    }
  ]
}

Sem retiradas, pickups vem [].

Campos da resposta

pickups[].iduuid

Id da retirada.

pickups[].order_iduuid

Pedido a retirar.

pickups[].warehouse_iduuid

Depósito (ponto de retirada).

pickups[].vendor_iduuid

Seller dono do ponto, quando é de um seller.

pickups[].statusstring

awaiting_preparationreadypicked_upexpiredcancelled

Estado da retirada.

pickups[].code_attemptsinteger

Tentativas erradas de código desde o último acerto ou bloqueio.

pickups[].code_locked_untilstring

Se o código está bloqueado, até quando (RFC 3339). Ausente se não está.

pickups[].delivery_schedule_iduuid

Janela de retirada agendada, quando há.

pickups[].ready_atstring

Quando foi marcada como pronta.

pickups[].picked_up_atstring

Quando foi retirada.

pickups[].expires_atstring

Prazo para retirar. Passado o prazo, a plataforma marca como expired.

pickups[].created_atstring

Criação, RFC 3339 em UTC.

pickups[].updated_atstring

Última alteração, RFC 3339 em UTC.

pickups[].warehouse_namestring

Nome do depósito.

pickups[].warehouse_addressstring

Endereço do depósito.

pickups[].warehouse_citystring

Cidade do depósito.

pickups[].warehouse_statestring

Estado do depósito.

pickups[].warehouse_zipcodestring

CEP do depósito.

pickups[].order_numberstring

Número do pedido, como o cliente vê.

Erros

Status	Quando	Corpo
401 / 403	Sem token ou sem privilégio	`{"error":"insufficient privileges", ...}`
500	`warehouse_id` que não é UUID, ou falha interna	`{"error":"failed to list pickups","detail":"..."}`

Marcar como pronta

Avisa que o pedido está separado. O estado passa de awaiting_preparation para ready, a data fica registrada e a plataforma publica o evento de retirada pronta, com o código, que alimenta o aviso ao cliente. É idempotente: repetir numa retirada já ready responde sucesso sem mudar nada.

POST/api/v1/admin/pickups/{id}/readyAdmin

Marca a retirada como pronta

Parâmetros de caminho

iduuidobrigatório

Id da retirada.

Sem corpo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/pickups/c3a1f0de-5b2e-4a77-9c41-0d6e8f1b2a33/ready" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Retirada pronta

json

{ "status": "ready" }

Erros

Status	Quando	Corpo
400	Retirada inexistente	`{"error":"pickup not found"}`
400	Estado que não permite (por exemplo, já retirada ou cancelada)	`{"error":"cannot mark ready from status \"picked_up\""}`
400	`id` que não é UUID	`{"error":"o valor \"abc\" não é um uuid válido. ..."}`

Confirmar a retirada

Registra que o cliente retirou o pedido. Você informa o código de 6 dígitos que o cliente mostra; se bate, a retirada vai para picked_up e o usuário que confirmou fica registrado. Um código errado não é um erro HTTP: volta 200 com confirmed: false e quantas tentativas restam.

Depois de 5 códigos errados seguidos, a retirada é bloqueada por 15 minutos: a resposta passa a ser 429, e qualquer tentativa nesse período, mesmo com o código certo, também.

POST/api/v1/admin/pickups/{id}/confirmAdmin

Confirma a retirada com o código do cliente

Parâmetros de caminho

iduuidobrigatório

Id da retirada.

Corpo da requisição

codestringobrigatório

Código de retirada informado pelo cliente. Espaços nas pontas são removidos.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/pickups/c3a1f0de-5b2e-4a77-9c41-0d6e8f1b2a33/confirm" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "483920"}'

Resposta

200Retirada confirmada

json

{ "confirmed": true, "locked": false, "attempts_left": 0 }

200Código errado

json

{ "confirmed": false, "locked": false, "attempts_left": 4 }

429Código bloqueado

json

{
  "confirmed": false,
  "locked": true,
  "locked_until": "2026-10-11T12:30:00Z",
  "attempts_left": 0
}

Campos da resposta

confirmedboolean

true quando o código bateu e a retirada foi concluída.

lockedboolean

true quando a retirada está bloqueada para novas tentativas.

locked_untilstring

Até quando está bloqueada (RFC 3339). Só aparece com locked: true.

attempts_leftinteger

Tentativas restantes antes do bloqueio. Em acerto vem 0, e esse número não indica falta de tentativas.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	Retirada inexistente	`{"error":"pickup not found"}`
400	Retirada que não está `ready`	`{"error":"pickup not ready for confirmation (status \"awaiting_preparation\")"}`
429	Código bloqueado por excesso de tentativas	o corpo de bloqueio acima

Cancelar a retirada

Cancela uma retirada que ainda está em awaiting_preparation ou ready. A plataforma libera o estoque reservado no depósito e devolve ao estoque as unidades baixadas quando o pedido foi criado. Se uma dessas devoluções de estoque falhar, o cancelamento da retirada continua valendo e a falha é apenas registrada.

POST/api/v1/admin/pickups/{id}/cancelAdmin

Cancela a retirada e devolve o estoque

Parâmetros de caminho

iduuidobrigatório

Id da retirada.

Sem corpo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/pickups/c3a1f0de-5b2e-4a77-9c41-0d6e8f1b2a33/cancel" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Retirada cancelada

json

{ "status": "cancelled" }

Erros

Status	Quando	Corpo
400	Retirada inexistente, ou em estado que não permite cancelar (`picked_up`, `expired`, `cancelled`)	`{"error":"pickup not found"}`
400	`id` que não é UUID	`{"error":"o valor \"abc\" não é um uuid válido. ..."}`

Veja também

API atual/Referência completa/Frete: áreas e retirada

Retirada em loja

Lista as retiradas em loja e conduz cada uma de aguardando preparo até pronta, retirada ou cancelada.

Ler exige view_shipping ou manage_shipping; as três ações exigem manage_shipping. Os estados e a regra de bloqueio do código estão na visão geral.

Listar retiradas

Devolve as retiradas da mais nova para a mais antiga, sem paginação, com o nome e o endereço do depósito e o número do pedido. O código de retirada não vem: ele só é visto pelo cliente.

GET/api/v1/admin/pickupsAdmin

Lista as retiradas em loja

Parâmetros de consulta

statusstring

awaiting_preparationreadypicked_upexpiredcancelled

Filtra por estado. Ausente lista todos.

warehouse_iduuid

Só as retiradas deste depósito. Um valor que não é UUID dá 500.

Exemplo de requisição

bash

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

Resposta

200Retiradas retornadas

json

{
  "pickups": [
    {
      "id": "c3a1f0de-5b2e-4a77-9c41-0d6e8f1b2a33",
      "order_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
      "warehouse_id": "5e0a9c1d-7b3f-4d2a-8e6c-1f4b9a0c7d52",
      "status": "awaiting_preparation",
      "code_attempts": 0,
      "expires_at": "2026-10-18T12:00:00Z",
      "created_at": "2026-10-11T12:00:00Z",
      "updated_at": "2026-10-11T12:00:00Z",
      "warehouse_name": "Loja Centro",
      "warehouse_address": "Rua das Flores, 100",
      "warehouse_city": "São Paulo",
      "warehouse_state": "SP",
      "warehouse_zipcode": "01310100",
      "order_number": "PEDIDO-20261011-0004"
    }
  ]
}

Sem retiradas, pickups vem [].

Campos da resposta

pickups[].iduuid

Id da retirada.

pickups[].order_iduuid

Pedido a retirar.

pickups[].warehouse_iduuid

Depósito (ponto de retirada).

pickups[].vendor_iduuid

Seller dono do ponto, quando é de um seller.

pickups[].statusstring

awaiting_preparationreadypicked_upexpiredcancelled

Estado da retirada.

pickups[].code_attemptsinteger

Tentativas erradas de código desde o último acerto ou bloqueio.

pickups[].code_locked_untilstring

Se o código está bloqueado, até quando (RFC 3339). Ausente se não está.

pickups[].delivery_schedule_iduuid

Janela de retirada agendada, quando há.

pickups[].ready_atstring

Quando foi marcada como pronta.

pickups[].picked_up_atstring

Quando foi retirada.

pickups[].expires_atstring

Prazo para retirar. Passado o prazo, a plataforma marca como expired.

pickups[].created_atstring

Criação, RFC 3339 em UTC.

pickups[].updated_atstring

Última alteração, RFC 3339 em UTC.

pickups[].warehouse_namestring

Nome do depósito.

pickups[].warehouse_addressstring

Endereço do depósito.

pickups[].warehouse_citystring

Cidade do depósito.

pickups[].warehouse_statestring

Estado do depósito.

pickups[].warehouse_zipcodestring

CEP do depósito.

pickups[].order_numberstring

Número do pedido, como o cliente vê.

Erros

Status	Quando	Corpo
401 / 403	Sem token ou sem privilégio	`{"error":"insufficient privileges", ...}`
500	`warehouse_id` que não é UUID, ou falha interna	`{"error":"failed to list pickups","detail":"..."}`

Marcar como pronta

POST/api/v1/admin/pickups/{id}/readyAdmin

Marca a retirada como pronta

Parâmetros de caminho

iduuidobrigatório

Id da retirada.

Sem corpo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/pickups/c3a1f0de-5b2e-4a77-9c41-0d6e8f1b2a33/ready" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Retirada pronta

json

{ "status": "ready" }

Erros

Status	Quando	Corpo
400	Retirada inexistente	`{"error":"pickup not found"}`
400	Estado que não permite (por exemplo, já retirada ou cancelada)	`{"error":"cannot mark ready from status \"picked_up\""}`
400	`id` que não é UUID	`{"error":"o valor \"abc\" não é um uuid válido. ..."}`

Confirmar a retirada

Depois de 5 códigos errados seguidos, a retirada é bloqueada por 15 minutos: a resposta passa a ser 429, e qualquer tentativa nesse período, mesmo com o código certo, também.

POST/api/v1/admin/pickups/{id}/confirmAdmin

Confirma a retirada com o código do cliente

Parâmetros de caminho

iduuidobrigatório

Id da retirada.

Corpo da requisição

codestringobrigatório

Código de retirada informado pelo cliente. Espaços nas pontas são removidos.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/pickups/c3a1f0de-5b2e-4a77-9c41-0d6e8f1b2a33/confirm" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "483920"}'

Resposta

200Retirada confirmada

json

{ "confirmed": true, "locked": false, "attempts_left": 0 }

200Código errado

json

{ "confirmed": false, "locked": false, "attempts_left": 4 }

429Código bloqueado

json

{
  "confirmed": false,
  "locked": true,
  "locked_until": "2026-10-11T12:30:00Z",
  "attempts_left": 0
}

Campos da resposta

confirmedboolean

true quando o código bateu e a retirada foi concluída.

lockedboolean

true quando a retirada está bloqueada para novas tentativas.

locked_untilstring

Até quando está bloqueada (RFC 3339). Só aparece com locked: true.

attempts_leftinteger

Tentativas restantes antes do bloqueio. Em acerto vem 0, e esse número não indica falta de tentativas.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	Retirada inexistente	`{"error":"pickup not found"}`
400	Retirada que não está `ready`	`{"error":"pickup not ready for confirmation (status \"awaiting_preparation\")"}`
429	Código bloqueado por excesso de tentativas	o corpo de bloqueio acima

Cancelar a retirada

POST/api/v1/admin/pickups/{id}/cancelAdmin

Cancela a retirada e devolve o estoque

Parâmetros de caminho

iduuidobrigatório

Id da retirada.

Sem corpo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/pickups/c3a1f0de-5b2e-4a77-9c41-0d6e8f1b2a33/cancel" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Retirada cancelada

json

{ "status": "cancelled" }

Erros

Status	Quando	Corpo
400	Retirada inexistente, ou em estado que não permite cancelar (`picked_up`, `expired`, `cancelled`)	`{"error":"pickup not found"}`
400	`id` que não é UUID	`{"error":"o valor \"abc\" não é um uuid válido. ..."}`