Entrada em produção

A loja de teste e a loja real usam a mesma API. Entrar em produção é trocar a credencial e ter certeza de que o seu sistema aguenta o que acontece fora do caminho feliz. Percorra a lista antes de pedir a credencial da primeira loja real.

Credenciais e segredos

• Uma credencial por loja, com o mínimo de escopos que a integração usa.
• client_secret guardado em cofre de segredos ou variável de ambiente. Nunca em código, repositório, log ou mensagem de erro.
• O token é reaproveitado até perto de expirar (3600 s), não pedido a cada chamada. O endpoint de token tem limite por IP e por credencial.
• Um 401 invalid_token fora do horário de expiração é tratado como credencial pausada ou revogada: a integração avisa o operador em vez de tentar em loop.

Eventos

• Eventos são deduplicados por eventId antes de qualquer efeito colateral. O mesmo evento pode chegar mais de uma vez, por polling ou por webhook.
• O ack é enviado depois de gravar o pedido, nunca antes. Se o processo cair no meio, o evento volta.
• Todo evento recebido é confirmado, inclusive os que chegaram por webhook e os eventType que a integração não usa. Evento sem ack fica no feed para sempre.
• O eventType desconhecido é ignorado e confirmado, não derruba o consumidor. O MeuPedido emite extensões (PREPARING, MODIFIED, COURIER_*) além do padrão.
• O pedido é sempre buscado em orderURL; nada é inferido a partir do envelope além de eventType e orderId.
• Em polling, o intervalo é fixo e razoável (poucos segundos) e o limit é o maior que o seu consumidor processa com folga, até 200.

Webhooks (se usados)

• A URL é HTTPS com certificado válido e responde 2xx em menos de 10 s. Processamento pesado fica para depois da resposta.
• A assinatura em X-MeuPedido-Signature é verificada em tempo constante, e requisições com X-MeuPedido-Timestamp a mais de 5 minutos do relógio são rejeitadas.
• O segredo do webhook está guardado como o client_secret, e existe um procedimento para rotacioná-lo.
• O polling continua ativo (modo BOTH) para pegar o que o webhook não conseguir entregar após as retentativas.

Ações no pedido

• Cada ação envia um Idempotency-Key único por intenção (por exemplo, confirm do pedido X), para que reenvios não sejam processados duas vezes.
• 422 invalid_transition é tratado como conflito de estado, não como erro transitório: a integração relê o estado do pedido em vez de tentar de novo.
• already_applied é tratado como sucesso.
• Pedidos INDOOR (mesa) nunca recebem dispatch.

Resiliência

• 429 rate_limit_exceeded respeita o header Retry-After (60 s). O limite é de 600 requisições por minuto por credencial.
• 5xx e falhas de rede usam backoff exponencial com jitter, com um teto.
• O traceId das respostas 500 é registrado no log, para enviar ao suporte.
• Datas são lidas como UTC (todas terminam em Z) e convertidas para o fuso da loja só na exibição.
• Valores monetários (value) são tratados como decimais, nunca como ponto flutuante binário em cálculos fiscais.

Operação

• O campo test do pedido tem um comportamento definido em produção.
• Existe um alerta para feed parado: se a loja está aberta e nenhum evento chega por um período incomum, alguém é avisado.
• O time de operação sabe como pedir ao lojista para pausar, retomar ou revogar a credencial, e como reenviar um evento pelo painel.
• O contato do suporte está à mão: (11) 95502-1289, com client_id, traceId, horário e eventId do que deu errado.

Próximos passos

• Boas práticas: limites, erros, backoff e segurança em detalhe.
• Webhooks: verificação da assinatura com código.
• Suporte: o que enviar quando precisar de ajuda.