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

Ações da retirada

Marca a retirada como pronta, confirma a entrega pelo código do cliente ou cancela a retirada.

Estas três ações conduzem a retirada: pronta (avisa o cliente), confirmar (entrega no balcão) e cancelar. Todas valem apenas para retiradas dos pedidos do seller do token; qualquer outra responde 404.

Marcar como pronta

Passa a retirada de awaiting_preparation para ready, grava ready_at e dispara o aviso ao cliente com o código de 6 dígitos e o QR. É seguro repetir: numa retirada já ready a resposta continua 200, mas o aviso é enviado de novo ao cliente.

POST/api/v1/vendor/pickups/{id}/readySeller

Marca a retirada como pronta

Parâmetros de caminho

iduuidobrigatório

Id da retirada.

Exemplo de requisição: pronta

bash

curl -X POST "$BASE_URL/api/v1/vendor/pickups/c0ffee00-1234-4abc-9def-0123456789ab/ready" \
  -H "Authorization: Bearer $TOKEN"

Resposta: pronta

200Retirada pronta

json

{
  "status": "ready"
}

Campos da resposta

statusstring

Sempre ready.

Erros: pronta

Status	Quando	Corpo de exemplo
400	A retirada não está em `awaiting_preparation` nem em `ready` (por exemplo já `picked_up`).	`{"error":"cannot mark ready from status \"picked_up\""}`
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"}`
404	Não existe retirada com esse id para este seller, ou ela já está encerrada (`picked_up`, `expired`, `cancelled`) quando a ação é cancelar.	`{"error":"pickup not found"}`
403	Sem privilégio de pedidos, ou sem conta de seller.	`{"error":"insufficient vendor privileges"}`

Confirmar a retirada

O cliente chega ao balcão e diz (ou mostra no QR) o código de 6 dígitos. Você o envia aqui. Se bater, a retirada vai para picked_up (final). Se errar, a resposta é 200 com confirmed: false e o número de tentativas que restam.

POST/api/v1/vendor/pickups/{id}/confirmSeller

Confirma a retirada pelo código

Parâmetros de caminho

iduuidobrigatório

Id da retirada.

Corpo da requisição

codestringobrigatório

Código de 6 dígitos informado pelo cliente. Espaços nas pontas são removidos.

Exemplo de requisição: confirmar

bash

curl -X POST "$BASE_URL/api/v1/vendor/pickups/c0ffee00-1234-4abc-9def-0123456789ab/confirm" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "483920"
  }'

Resposta: confirmar

200Código certo

json

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

Campos da resposta

confirmedboolean

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

lockedboolean

true quando a confirmação está travada.

locked_untilstring

Fim do travamento (RFC 3339). Ausente se não travada.

attempts_leftinteger

Tentativas restantes antes do travamento (de 5). Em caso de sucesso vem 0.

200Código errado

json

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

429Travada por excesso de erros

json

{
  "confirmed": false,
  "locked": true,
  "locked_until": "2026-10-02T11:15:00Z",
  "attempts_left": 0
}

Erros: confirmar

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON.	`{"error":"invalid request body"}`
400	A retirada não está `ready`.	`{"error":"pickup not ready for confirmation (status \"awaiting_preparation\")"}`
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"}`
404	Não existe retirada com esse id para este seller.	`{"error":"pickup not found"}`
429	5 códigos errados seguidos: confirmação travada por 15 minutos (veja o exemplo acima).	`{"confirmed":false,"locked":true,"locked_until":"2026-10-02T11:15:00Z","attempts_left":0}`

Cancelar a retirada

Cancela uma retirada em awaiting_preparation ou ready. A plataforma libera o estoque reservado no ponto de retirada e devolve ao produto a quantidade baixada quando o pedido foi criado. Não cancela o pedido nem reembolsa o cliente: isso é feito nas rotas de pedidos.

POST/api/v1/vendor/pickups/{id}/cancelSeller

Cancela a retirada

Parâmetros de caminho

iduuidobrigatório

Id da retirada.

Exemplo de requisição: cancelar

bash

curl -X POST "$BASE_URL/api/v1/vendor/pickups/c0ffee00-1234-4abc-9def-0123456789ab/cancel" \
  -H "Authorization: Bearer $TOKEN"

Resposta: cancelar

200Retirada cancelada

json

{
  "status": "cancelled"
}

Campos da resposta

statusstring

Sempre cancelled.

Erros: cancelar

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"}`
404	Não existe retirada com esse id para este seller, ou ela já está encerrada (`picked_up`, `expired`, `cancelled`) quando a ação é cancelar.	`{"error":"pickup not found"}`

Veja também

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

Ações da retirada

Marca a retirada como pronta, confirma a entrega pelo código do cliente ou cancela a retirada.

Marcar como pronta

POST/api/v1/vendor/pickups/{id}/readySeller

Marca a retirada como pronta

Parâmetros de caminho

iduuidobrigatório

Id da retirada.

Exemplo de requisição: pronta

bash

curl -X POST "$BASE_URL/api/v1/vendor/pickups/c0ffee00-1234-4abc-9def-0123456789ab/ready" \
  -H "Authorization: Bearer $TOKEN"

Resposta: pronta

200Retirada pronta

json

{
  "status": "ready"
}

Campos da resposta

statusstring

Sempre ready.

Erros: pronta

Status	Quando	Corpo de exemplo
400	A retirada não está em `awaiting_preparation` nem em `ready` (por exemplo já `picked_up`).	`{"error":"cannot mark ready from status \"picked_up\""}`
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"}`
404	Não existe retirada com esse id para este seller, ou ela já está encerrada (`picked_up`, `expired`, `cancelled`) quando a ação é cancelar.	`{"error":"pickup not found"}`
403	Sem privilégio de pedidos, ou sem conta de seller.	`{"error":"insufficient vendor privileges"}`

Confirmar a retirada

POST/api/v1/vendor/pickups/{id}/confirmSeller

Confirma a retirada pelo código

Parâmetros de caminho

iduuidobrigatório

Id da retirada.

Corpo da requisição

codestringobrigatório

Código de 6 dígitos informado pelo cliente. Espaços nas pontas são removidos.

Exemplo de requisição: confirmar

bash

curl -X POST "$BASE_URL/api/v1/vendor/pickups/c0ffee00-1234-4abc-9def-0123456789ab/confirm" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "483920"
  }'

Resposta: confirmar

200Código certo

json

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

Campos da resposta

confirmedboolean

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

lockedboolean

true quando a confirmação está travada.

locked_untilstring

Fim do travamento (RFC 3339). Ausente se não travada.

attempts_leftinteger

Tentativas restantes antes do travamento (de 5). Em caso de sucesso vem 0.

200Código errado

json

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

429Travada por excesso de erros

json

{
  "confirmed": false,
  "locked": true,
  "locked_until": "2026-10-02T11:15:00Z",
  "attempts_left": 0
}

Erros: confirmar

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON.	`{"error":"invalid request body"}`
400	A retirada não está `ready`.	`{"error":"pickup not ready for confirmation (status \"awaiting_preparation\")"}`
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"}`
404	Não existe retirada com esse id para este seller.	`{"error":"pickup not found"}`
429	5 códigos errados seguidos: confirmação travada por 15 minutos (veja o exemplo acima).	`{"confirmed":false,"locked":true,"locked_until":"2026-10-02T11:15:00Z","attempts_left":0}`

Cancelar a retirada

POST/api/v1/vendor/pickups/{id}/cancelSeller

Cancela a retirada

Parâmetros de caminho

iduuidobrigatório

Id da retirada.

Exemplo de requisição: cancelar

bash

curl -X POST "$BASE_URL/api/v1/vendor/pickups/c0ffee00-1234-4abc-9def-0123456789ab/cancel" \
  -H "Authorization: Bearer $TOKEN"

Resposta: cancelar

200Retirada cancelada

json

{
  "status": "cancelled"
}

Campos da resposta

statusstring

Sempre cancelled.

Erros: cancelar

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"}`
404	Não existe retirada com esse id para este seller, ou ela já está encerrada (`picked_up`, `expired`, `cancelled`) quando a ação é cancelar.	`{"error":"pickup not found"}`