Retirada na loja

Na retirada na loja, o cliente faz o pedido e busca a compra em um local definido pela loja. Não há entrega por transportadora nem código de rastreio. Para confirmar a retirada, a loja informa na API o código apresentado pelo cliente.

Esse fluxo é identificado por delivery_method=pickup.

Como identificar um pedido de retirada

delivery_method informa como o cliente receberá o pedido. Já workflow_type informa o processo comercial pelo qual o pedido passa. A retirada pode aparecer em diferentes workflows; em pedidos antigos, você ainda pode encontrar workflow_type=in_store_pickup.

{
  "order_number": "ORD-000456",            // identificador público do pedido
  "delivery_method": "pickup",             // retirada na loja
  "workflow_type": "in_store_pickup",
  "status": "ready_for_pickup",
  "picked_up_at": null,                     // preenchido após a confirmação
  "metadata": {
    "pickup": {
      "physical_store_id": 7,
      "pickup_expires_at": "2026-04-30T15:00:00-03:00"
    }
  }
}

Em um pedido de retirada, os status de envio não se aplicam: o pedido não passa por ready_to_ship nem por shipped. Antes de cada mudança, consulte possible-statuses; a API informa as transições válidas para o estado atual.

O enum pode listar o status reserved, mas ele não deve ser tratado como uma ação disponível para o seller. Use as transições retornadas por possible-statuses.

Fluxo do pedido

Até preparing, o fluxo é igual ao de um pedido com envio. A diferença aparece na próxima etapa: um pedido com envio segue para ready_to_ship; um pedido de retirada segue para ready_for_pickup.

Etapa a etapa

Use estas duas rotas para consultar e avançar o pedido:

GET/api/v1/sellers/orders/{id}/possible-statuses

POST/api/v1/sellers/orders/{id}/status

A consulta a possible-statuses deve acontecer antes da transição. Isso evita usar um status que já deixou de ser válido porque outra operação avançou o pedido.

Confirmar a retirada

O código de confirmação é informado pelo cliente no balcão. A loja não deve tentar obtê-lo no detalhe do pedido nem consultar um código armazenado em metadata: a integração apenas envia o valor apresentado pelo cliente.

O contrato trata confirmation_code como uma string de até 50 caracteres. Não presuma que ele seja numérico ou tenha sempre quatro dígitos.

POST /api/v1/sellers/orders/ORD-000456/status
Content-Type: application/json

{ "status": "picked_up", "data": { "confirmation_code": "A1B2C3" } }

O campo confirmation_code é obrigatório nessa transição. Depois de uma confirmação válida, a API preenche picked_up_at e conclui automaticamente o pedido como delivered. Não envie uma segunda requisição para delivered.

Possíveis erros

Se o prazo já tiver terminado, não confirme a retirada. Consulte o estado retornado pela API e siga o fluxo de expiração.

Prazo de retirada e expiração

Use o prazo retornado pela API, como pickup_expires_at, em vez de fixar uma quantidade de dias na integração. O prazo pode variar conforme a configuração da loja ou da plataforma.

Quando o prazo termina:

• o pedido não deve mais ser confirmado como retirado;
• a loja pode registrar pickup_expired manualmente, quando essa transição aparecer em possible-statuses;
• essa transição exige um motivo em data.reason, com entre 10 e 500 caracteres;
• depois de pickup_expired, o sistema cancela o pedido automaticamente.

Exemplo:

{
  "status": "pickup_expired",
  "data": {
    "reason": "Prazo de retirada expirado."
  }
}

Não envie cancelled depois de pickup_expired: o cancelamento faz parte da sequência automática. Para acompanhar quem realizou cada mudança, consulte o histórico em GET /orders/{id}/events.

Se o cliente desistir antes do prazo, use o cancelamento normal do pedido.

Cancelamento

O seller pode cancelar o pedido enquanto ele ainda está em paid. O motivo é obrigatório e deve ter entre 10 e 500 caracteres:

{
  "status": "cancelled",
  "data": {
    "reason": "Cliente solicitou o cancelamento."
  }
}

A partir de preparing, o cancelamento deixa de aparecer em possible-statuses para o seller e a API recusa a tentativa. Nessa situação, o cancelamento deve ser tratado com a operação da plataforma.

A exceção é pickup_expired: nesse caso, a transição para cancelled é feita automaticamente pelo sistema.

Emissão fiscal e etiqueta

A retirada presencial não dispensa o documento fiscal. A loja deve emitir a NF-e ou a Declaração de Conteúdo antes de mudar o pedido de preparing para ready_for_pickup. Sem um documento válido, a API recusa a transição com 422 no campo fiscal.

A ordem recomendada é:

1. separar o pedido;
2. emitir o documento fiscal;
3. gerar a etiqueta, se necessário;
4. marcar o pedido como ready_for_pickup;
5. aguardar o cliente.

A retirada também gera um shipment, mas ele não tem transportadora nem código de rastreio. O shipment serve para identificar o pacote no balcão e gerar a etiqueta de identificação. A geração é assíncrona e usa a mesma rota do fluxo logístico:

POST/api/v1/sellers/orders/{id}/shipment-labels/generate

Essa rota retorna 202 Accepted. Depois, consulte os shipments até a etiqueta estar disponível. Veja o guia de logística para o fluxo completo de geração e download.