Clique e Retire — material de retirada por filial

Como gerar e usar o QR Code estático e as instruções de retirada de cada filial, e como funciona a jornada de autoatendimento de Clique e Retire ponta a ponta.

O Clique e Retire é a modalidade em que o cliente retira o pedido na loja por autoatendimento, sem depender do balcão para localizar o pacote. Cada filial expõe um cartaz com um QR Code estático; o cliente escaneia, informa o código de rastreio do pedido e confirma a retirada presencialmente.

Este guia cobre as duas pontas:

Montar o material da filial — o QR Code estático e o PDF de instruções que vão no ponto de venda (um QR por filial, fixo).
A jornada do pedido — como o pedido nasce como retirada, gera o token de retirada e é fechado como retirado.

Para o contrato cru de cada endpoint (parâmetros, respostas, playground), vá direto à seção Retirada (Clique e Retire) na API Reference.

Quem faz o quê

Ator	Responsabilidade
Embarcador	Gera o material de cada filial (QR + instruções) uma vez e o imprime/expõe no ponto de venda. Cria os pedidos do tipo `TAKEOUT`.
Abbiamo	Entrega o QR estático e o PDF de instruções por filial; gera o token de retirada por pedido; registra a confirmação da retirada.
Operador da loja	Mantém o cartaz visível no balcão e dá suporte ao cliente no autoatendimento.
Cliente	Escaneia o QR exposto na loja, informa o código de rastreio, preenche o código de confirmação e conclui a retirada.

Parte 1 — Montar o material da filial

O material é fixo por filial: gere uma vez por loja e reutilize em todos os cartazes e adesivos daquela unidade. A filial é identificada pelo identifier (o mesmo seller_identifier usado na criação de pedidos) e precisa pertencer ao seller group autenticado.

Passo a passo

Pegue o QR Code estático da filial. Chame o endpoint QR Code estático de retirada. A resposta é uma imagem PNG — salve direto como .png.

curl -X GET \
  "https://api.abbiamo.io/v1/takeout/seller/{identifier}/static-qrcode" \
  -H "x-abbiamo-seller-group-key: SUA_CHAVE" \
  --output retirada-qrcode.png

Pegue o PDF de instruções da filial. Chame o endpoint Instruções de retirada (PDF). A resposta é um PDF — salve direto como .pdf.

curl -X GET \
  "https://api.abbiamo.io/v1/takeout/seller/{identifier}/instructions" \
  -H "x-abbiamo-seller-group-key: SUA_CHAVE" \
  --output retirada-instrucoes.pdf

Monte o cartaz e exponha no balcão. Junte o QR e as instruções no seu material de ponto de venda e deixe visível na loja.

Os dois endpoints retornam conteúdo binário (image/png e application/pdf). Salve o corpo da resposta direto em arquivo — não tente fazer parse como JSON.

Tem mais de uma filial/bandeira? Repita os dois passos para cada identifier. Cada filial tem seu próprio QR e PDF.

A busca de retirada é escopada pela filial. O QR de uma filial só encontra pedidos de retirada (TAKEOUT) daquela filial, criados nos últimos 3 meses. Um QR único para a bandeira inteira só acharia os pedidos de uma única filial — para bandeiras com mais de uma filial, gere um QR por filial (um identifier por loja).

Parte 2 — A jornada do pedido

Pedido de retirada. Crie o pedido como TAKEOUT (campo type na criação de pedido). É o que sinaliza que o cliente vai retirar na loja em vez de receber em casa.
Pedido fica pronto para retirada. Quando o pacote está disponível na loja, o pedido entra em DISPATCHED (pronto para retirada). O cliente é avisado por e-mail e SMS com o código de rastreio.
Cliente escaneia o QR na loja. Pelo QR estático do cartaz, o cliente abre a jornada de retirada e informa o código de rastreio para localizar o pedido. A busca é feita dentro daquela filial — apenas pedidos TAKEOUT da filial do QR, criados nos últimos 3 meses.
Token de retirada. O pedido tem um token único de retirada — disponível via Obter token de retirada. O cliente apresenta/confirma esse código para validar que é o dono do pedido.
Retirada confirmada. Com a retirada validada, o pedido é movido para SUCCESSFUL.WITHDRAWN — manualmente via Marcar pedido como retirado ou pelo próprio fluxo de autoatendimento. Esse é o fim do ciclo de vida do pedido.

Os endpoints da jornada do pedido falham se o pedido não for do tipo TAKEOUT ou ainda não estiver pronto para retirada (DISPATCHED).

Erros comuns

Tratar a resposta binária como JSON. Os endpoints de QR e instruções devolvem PNG/PDF. Use --output arquivo (curl) ou salve o buffer da resposta; não dê parse em JSON.
Gerar o QR por pedido. O QR de Clique e Retire é por filial, não por pedido — é o mesmo cartaz para todos os pedidos daquela loja. Quem é único por pedido é o token de retirada.
Um QR único para uma bandeira com várias filiais. A busca é escopada por filial: o QR de uma filial não encontra pedidos de outra. Se a bandeira tem mais de uma loja, gere um QR por filial.
403 ao buscar o material. O identifier da filial precisa pertencer ao seller group da chave usada. Filial de outro grupo retorna 403; identifier inexistente retorna 404.
Pedido criado sem type: "TAKEOUT". Sem isso o pedido segue como entrega normal e a jornada de retirada não se aplica.