Como funciona


O ciclo do seu PDV: token, polling, detalhes, confirmação e acknowledgment
- Evento é só um aviso. O polling diz o que mudou (
CREATED,CANCELLED…). Os dados do pedido vêm de uma segunda chamada, naorderURLdo evento. - Acknowledgment é obrigatório. Enquanto você não confirmar o recebimento, a API devolve os mesmos eventos em toda chamada.
- O mesmo evento pode chegar duas vezes. Guarde o
eventIddos eventos processados e ignore repetidos, mas confirme o recebimento deles mesmo assim.
Antes de começar
Um app com scope od.all
Com
client_id e client_secret em mãos.Uma loja com o app instalado
Peça uma loja de teste no Discord.
Node.js 18+ ou Python 3.9+
O exemplo existe nas duas linguagens.
Passo a passo
1
Obtenha o token de acesso
O token vale 24 horas e atende todas as lojas que instalaram o seu app.
2
Consulte os novos eventos
Chame o polling com o token. A resposta é 200 com uma lista de até 100 eventos, do mais antigo para o mais recente, ou 204 sem corpo quando não há nada novo.
Evento CREATED
3
Busque os detalhes do pedido
Para cada evento
CREATED, faça um GET na orderURL. A resposta traz itens, cliente, endereço, pagamento e totais. Veja todos os campos em Obter detalhes do pedido.4
Confirme o pedido
Confirmar diz à loja e ao cliente que o pedido foi aceito pelo PDV. A resposta é 202 com o
id do pedido.Neste guia o script confirma todo pedido automaticamente. No seu PDV, confirme quando a loja aceitar o pedido, ou solicite o cancelamento se ela recusar.
5
Confirme o recebimento dos eventos
Envie um array com o
eventId de todos os eventos recebidos, no campo id. Inclua os repetidos e os que o seu sistema ainda não trata: só assim eles saem da fila.Resposta (202)
O script completo
Junte os passos em um loop. Ele roda a cada 30 segundos e, quando recebe um lote cheio (100 eventos), chama o polling de novo sem esperar, até esvaziar a fila.Saída esperada
O pedido aparece como confirmado no painel da loja. A partir daqui, o seu PDV acompanha o preparo e a entrega pelas ações do pedido.
Erros comuns
Próximos passos
Webhooks
Receba os eventos na hora, sem polling. Use o polling como reconciliação.
Ações do pedido
Preparo, pronto para retirada, despacho, entrega e cancelamento.
Eventos de pedidos
Todos os tipos de evento e quando cada um acontece.
Visão completa do fluxo
Tipos de pedido, agendamento e o ciclo de vida por tipo.