API para restaurante: pedidos, cardápio e webhooks assinados

O problema do sistema fechado

Restaurante que cresce acaba com mais de uma ferramenta: um BI para o sócio, um CRM para campanhas, um parceiro de entrega, um ERP da rede. Se o sistema de pedidos não conversa com nenhum deles, alguém exporta planilha toda semana, e o dado chega velho.

Uma API aberta resolve quando é documentada, protege os dados de cada loja e avisa as mudanças por webhook em vez de obrigar o outro sistema a perguntar o tempo todo.

Como funciona a API para restaurante no Rest Food

A base é https://api.restfood.com.br/v1. Cada token pertence a uma loja e só enxerga os dados dela.

1. Em Configurações → Integrações, o dono gera um token. Ele aparece uma única vez; guarde num lugar seguro.
2. Escolha o escopo: leitura (consultas) ou leitura e escrita (também cria pedido, muda status, mexe em cupom e pede nota).
3. Envie o token no cabeçalho Authorization, no formato Bearer.
4. Para receber eventos, cadastre URLs HTTPS de webhook na mesma tela e escolha os eventos.

O que a API cobre

Pedido criado por integração

O pedido criado pela API segue as mesmas regras do cardápio: o preço é recalculado no servidor e, se o total enviado não bate, a API responde com conflito de preço em vez de aceitar um valor errado. O horário da loja é respeitado; com a loja fechada, use o agendamento. Cada criação exige o cabeçalho Idempotency-Key: repetir a mesma chave devolve o mesmo pedido, sem duplicar. O código externo do pedido é único por loja.

A mudança de status pela API respeita a mesma sequência do painel. Não dá para pular de "recebido" para "entregue".

Webhooks assinados

Os eventos disponíveis são: pedido criado, pedido atualizado, mudança de status, pedido avaliado, nota autorizada e nota rejeitada.

• Cada envio leva uma assinatura HMAC com o segredo do endpoint e o horário. Seu sistema confere a assinatura e recusa mensagens com mais de 5 minutos.
• Cada envio tem um identificador próprio, para o seu sistema ignorar repetição.
• Responda com sucesso em até 10 segundos. Se falhar, há 6 novas tentativas com espera crescente, de 30 segundos até 6 horas.
• O painel mostra as últimas entregas de cada endpoint, com o código HTTP e o tempo de resposta, botão de reenvio e botão Enviar teste.

Limites e o que depende de você

• Limite de uso: 120 requisições por minuto por token. Passou, a API responde com o tempo de espera.
• Dinheiro em centavos: todo valor é inteiro, em centavos, e as datas vêm com fuso.
• Formas de pagamento: pedidos criados pela API aceitam as formas de pagamento na entrega da loja. Fiado e pagamento online não são aceitos por essa rota.
• Escopo por loja: quem tem filiais gera um token por loja.
• Integração é desenvolvimento: a API é uma porta. Alguém do seu lado, ou um parceiro, precisa escrever o código que a usa. O suporte do Rest Food ajuda com dúvidas da API, mas não desenvolve a integração do seu sistema.

A API e os webhooks fazem parte das integrações dos planos Delivery e Completo. Compare em planos. A referência completa, com exemplos de requisição e resposta, está em desenvolvedores.

Para quem serve

Para quem já usa outras ferramentas e quer o dado de pedidos nelas: redes e franquias que consolidam vendas num BI (multi-lojas), restaurante com ERP próprio, dark kitchen que recebe pedido de canal próprio externo, distribuidora de bebidas que integra com CRM de vendas e hamburgueria que dispara campanhas a partir das avaliações. Para escolher o sistema certo pensando em integração, veja como escolher um sistema para restaurante.