DEV Community: Felipe Bufelli

Integração com o iFood: o bug escondido por semanas

Felipe Bufelli — Fri, 25 Sep 2026 20:53:03 +0000

O desafio

Hoje eu quero falar da Temperô, um SaaS multi-tenant de gestão de restaurantes: pedidos, cozinha, caixa, comandas, várias unidades por restaurante. Stack em Node/TypeScript/Express, Postgres com pg puro (sem ORM, SQL cru, migrations numeradas).

O objetivo era simples de enunciar,mas em termos de produção, bem difícil de sustentar: um pedido feito no marketplace iFood precisa entrar automaticamente no fluxo operacional do Temperô, cair na cozinha, seguir para produção e entrega, fechar o pagamento - e tudo isso com o status sincronizado nos dois sentidos. O restaurante não pode ter que operar dois sistemas em paralelo, um para o delivery do marketplace e outro para o resto.

No artigo de hoje, eu conto como implementamos isso, os bugs que apareceram no caminho, e principalmente a investigação mais longa do projeto: o por que, às vezes, o evento de confirmação de um cancelamento simplesmente não chegava nunca.

As decisões de arquitetura

Polling, não webhook. A Order API do iFood expõe GET /order/v1.0/events:polling, que devolve os eventos pendentes de um merchant, e POST /order/v1.0/events/acknowledgment, que confirma o recebimento e tira o evento da fila. A cada 15 segundos, o Temperô sempre inicia a chamada, dentro de um setInterval no próprio processo Node, sem serviço separado. Uma flag de controle simples evita sobreposição de execuções caso um tick demore mais que o intervalo:

let polling = false;

setInterval(async () => {
  if (polling) return;
  polling = true;

  try {
    await pollIfoodEvents();
  } finally {
    polling = false;
  }
}, 15_000);

Nesse sentido, é importante dizer que não escolhemos polling por preferência técnica; ela era a única opção viável no momento: o iFood nunca chama o Temperô, o Temperô sempre chama o iFood.

App "Centralizado" do iFood Developer. O iFood oferece dois modelos de credencial: "Distribuído", uma credencial OAuth2 por restaurante/unidade, e "Centralizado", uma única credencial client_credentials para toda a plataforma, filtrando o merchant específico via header x-polling-merchants em cada request. Por aqui, escolhemos Centralizado, o que exigiu refatorar no meio do projeto um cache de token que originalmente era por unidade para um cache único em memória.

Token OAuth2 com renovação proativa e reativa. O token fica em memória, com expiração baseada no expiresIn que o próprio iFood devolve. Em termos de renovação, fizemos tanto de forma proativa, com um buffer de 30 segundos antes de expirar, como de forma reativa, invalidando e tentando de novo uma vez em qualquer resposta 401.

Pedido do iFood sempre nasce com origin='ifood' e dine_type='entrega' fixo. O v1 da integração cobre só delivery. Pedidos de takeout ou dine-in que por algum motivo chegam via marketplace são recusados automaticamente, chamando requestCancellation com o primeiro motivo disponível na lista de códigos.

Sem mapeamento de cardápio. O item do pedido iFood entra com menu_item_id=null, usando nome e preço direto do payload recebido. Mapear cada item do cardápio do iFood para o cardápio interno do Temperô ficou fora do escopo do v1.

Pagamento sem operador humano. Cada unidade tem um usuário "de sistema" sintético e um caixa virtual que abre e fecha sozinho, sem depender de alguém abrindo caixa manualmente pra receber pedido de marketplace.

O bug do code vs fullCode

Ao longo da trajetória, é claro, surgiram alguns problemas.

Entre eles, estava o fato de que cada evento do polling do iFood vem com dois campos parecidos: code, um código abreviado tipo "PLC", e fullCode, o nome por extenso, tipo "PLACED". Durante semanas, o switch que processava os eventos comparava contra code:

switch (event.code) {
  case "PLACED":
    await handleOrderPlaced(event);
    break;
  case "CANCELLED":
    await handleOrderCancelled(event);
    break;
  // ...
  default:
    break;
}

O problema é que event.code nunca era "PLACED", o valor real ali era "PLC". Todo evento verdadeiro caía silenciosamente no default, um no-op sem log de erro, sem exceção, sem nada que chamasse atenção. O sistema simplesmente parecia "não fazer nada" com eventos reais, enquanto testes manuais via curl pareciam funcionar, porque testavam outras partes do fluxo, não o processamento do evento em si.

Só descobrimos isso analisando o JSON bruto de um evento capturado no log estruturado, comparando campo por campo com a documentação:

{
  "id": "b3f1...",
  "code": "PLC",
  "fullCode": "PLACED",
  "orderId": "a921...",
  "merchantId": "9f02...",
  "createdAt": "2026-09-03T14:22:10.000Z"
}

A correção foi fácil, com a troca de event.code por event.fullCode no switch, mas o aprendizado não foi, nem de perto, trivial: sempre compare contra o campo que a documentação define como canônico, não o que parece, pelo nome da propriedade, ser o identificador do evento. code parecia óbvio demais pra estar errado, e foi exatamente por isso que passou despercebido por tanto tempo.

Foi na mesma leva de correções que outro bug sutil apareceu, de filtro de data em UTC comparado contra horário local sem conversão explícita, fazendo pedidos de fim de noite sumirem da tela de "Pedidos do dia": o tipo de erro que só aparece quando alguém confere manualmente um caso de borda, não em teste automatizado com dados sintéticos.

O problema do cancelamento assíncrono

Na esteira de problemas, tivemos que o POST /requestCancellation do iFood devolve 202 Accepted. Isso não significa que o pedido foi cancelado, mas que "recebi seu pedido de cancelamento". A confirmação real chega depois, de forma assíncrona, pelo mesmo mecanismo de polling: um evento CANCELLED se o cancelamento foi aceito, ou CANCELLATION_REQUEST_FAILED se foi recusado.

A primeira versão do sistema não respeitava essa assincronia. Ela marcava o pedido como cancelado imediatamente, de forma otimista, no mesmo instante da chamada HTTP. Isso divergia do estado real da plataforma toda vez que o iFood demorava ou nunca confirmava.

A correção foi introduzir um estado intermediário, só para pedidos origin='ifood':

ALTER TABLE ifood_orders ADD COLUMN cancellation_pending boolean DEFAULT false;
ALTER TABLE ifood_orders ADD COLUMN cancellation_requested_at timestamptz;

Enquanto cancellation_pending é verdadeiro, o pedido não muda de status de verdade. Na interface, a linha de ações do pedido é substituída por um único indicador, "Cancelamento em processamento", em vez de simplesmente desabilitar o botão de cancelar ao lado dos outros (o que deixava a tela ambígua sobre o que realmente estava acontecendo). O status só muda quando o evento de confirmação chega pelo polling.

A investigação mais longa: por que o evento de cancelamento às vezes não chegava

Trocando em miúdos, essa foi a parte que mais consumiu tempo do projeto, e a que mais ensinou. Reuni algumas hipóteses que guiaram essa trajetória.

Hipótese 1: instabilidade genérica do sandbox

A primeira suspeita foi que o ambiente de testes do iFood processava eventos em lote, às vezes com atraso de horas. Tínhamos evidência real disso em outro contexto: um pedido que foi pra DISPATCHED recebeu o evento CONCLUDED só várias horas depois, com um payload de metadata assim:

{
  "fullCode": "CONCLUDED",
  "metadata": {
    "triggerEvent": {
      "previousStatus": "DISPATCHED",
      "value": "CONCLUDED"
    }
  }
}

Isso reforçou a hipótese, mas não explicava por que, em alguns testes, o evento de cancelamento nunca chegava, nem depois de horas.

Hipótese 2: o motivo do cancelamento importava

Reparamos que testes usando o código de cancelamento "503" (item indisponível) travavam sem confirmação, enquanto "501" e "512" (problema de sistema, loja vai abrir mais tarde) resolviam na hora. Isso virou a teoria de que códigos "contestáveis" pelo consumidor final exigiriam algum fluxo de negociação separado antes da confirmação.

Hipótese 3: o Handshake Platform

Pesquisando a documentação a fundo, encontramos endpoints reais de disputa: POST /disputes/{disputeId}/accept, /reject, /alternatives/{alternativeId}. Existiam para cancelamentos contestáveis iniciados pelo consumidor, e nunca eram chamados pelo nosso sistema. Ufa, finalmente! Ela pareceu ser a explicação perfeita: estávamos deixando uma disputa aberta sem responder.

Mas como nem tudo são flores, o teste que derrubou a hipótese 3. Minutos depois, repetimos o mesmo teste, com o mesmo cancellationCode "503". Dessa vez, o evento CANCELLED chegou em cerca de 200 milissegundos, sem chamar nenhum endpoint de disputa. O payload trazia um metadado informativo, não um estado pendente de fato:

{
  "fullCode": "CANCELLED",
  "metadata": {
    "CANCELLATION_DISPUTE": {
      "IS_CONTESTABLE": "CANCELLATION_IS_CONTESTABLE"
    }
  }
}

Ou seja, o campo só indicava que aquele cancelamento poderia, em tese, ser contestado pelo consumidor. Não significava que estava, de fato, esperando handshake.

A causa raiz foi encontrada por acaso. Tínhamos duas instâncias da aplicação rodando o mesmo loop de polling contra o mesmo merchantId: o ambiente local de desenvolvimento e a produção no Railway, ambos usando a mesma credencial de teste.

A fila de eventos do iFood é por merchant, não por consumidor da API. Quem faz o poll primeiro recebe o evento e o reconhece via acknowledgment, tirando-o da fila pra sempre. Se a instância que fez a chamada de cancelamento não fosse a mesma que vencesse a corrida pelo próximo poll, ela nunca mais veria a confirmação, enquanto a outra instância recebia e descartava um evento que não tinha efeito nenhum no banco dela.

Naquele momento, tivemos um grande aprendizado, que entenderíamos só tempos depois: nunca rode dois consumidores de uma fila de webhook ou polling apontando pro mesmo recurso externo ao mesmo tempo, mesmo em ambientes nominalmente "separados", como dev local e produção, se eles compartilharem a mesma credencial e o mesmo merchant de teste.

Para corrigir o problema, isolamos de vez os ambientes: o polling contra o merchant passou a rodar exclusivamente em produção, e o ambiente local parou de consumir a fila. Um único consumidor ativo por merchant deixou de ser uma regra implícita e virou uma invariante garantida pela própria topologia do sistema, não por disciplina de quem estava testando naquele dia.

Homologação: quando "funcionar certo" não é suficiente

Fomos reprovados duas ou três vezes no processo formal de homologação do iFood, com uma mensagem genérica de "Erro ao recuperar logs da aplicação" no cenário de cancelamento. Em uma das tentativas, os logs estruturados provavam, com timestamp de cada etapa, que o fluxo inteiro (confirmação, requisição de cancelamento, CANCELLATION_REQUESTED, CANCELLED, acknowledgment) rodou em menos de dois minutos, sem erro nenhum do nosso lado.

Às vezes o "seu sistema está errado" de um avaliador automático de terceiros é, na verdade, um sintoma de um problema no próprio avaliador. A única defesa nessa situação é ter logs estruturados e cronometrados o suficiente para provar isso com uma solicitação de revisão manual, em vez de ficar tentando adivinhar o que "consertar" num sistema que já estava funcionando.

O que sustentou toda essa investigação

Nada disso teria sido reconstruível sem uma decisão tomada cedo: logar toda chamada HTTP ao iFood (path, método, unitId, merchantId, orderId, status, código de erro) e todo evento recebido, com o payload bruto completo, como uma linha JSON por evento, não só em caso de erro:

logger.info({
  event: "ifood.polling.event_received",
  merchantId,
  orderId: event.orderId,
  code: event.code,
  fullCode: event.fullCode,
  raw: event,
});

Foi isso que permitiu reconstruir cada uma das hipóteses da investigação, analisando só os logs do Railway, sem acesso direto ao painel do iFood. Numa integração assíncrona com um sistema externo que você não controla, o log estruturado deixa de ser um detalhe de observabilidade e vira a única fonte de verdade disponível quando algo não bate.

O que você precisa saber quando for integrar com marketplaces por polling

Compare sempre contra o campo canônico documentado, não o que parece ser o identificador pelo nome. Trate qualquer resposta 202 ou similar como confirmação de recebimento, nunca como confirmação de efeito. Modele o estado intermediário explicitamente no banco em vez de assumir otimisticamente que uma ação já aconteceu. E, acima de tudo, garanta que só existe um consumidor ativo por fila externa compartilhada, porque duas instâncias "separadas" brigando pela mesma fila produzem um bug que parece instabilidade de terceiro, mas é “apenas” um problema inteiramente seu.

Integração com o iFood: o problema na homologação do developer

Felipe Bufelli — Fri, 25 Sep 2026 20:48:48 +0000

O desafio

As decisões de arquitetura

let polling = false;

setInterval(async () => {
  if (polling) return;
  polling = true;

  try {
    await pollIfoodEvents();
  } finally {
    polling = false;
  }
}, 15_000);

Nesse sentido, é importante dizer que não escolhemos polling por preferência técnica; ela era a única opção viável no momento: o iFood nunca chama o Temperô, o Temperô sempre chama o iFood.

O bug do code vs fullCode

Ao longo da trajetória, é claro, surgiram alguns problemas.

switch (event.code) {
  case "PLACED":
    await handleOrderPlaced(event);
    break;
  case "CANCELLED":
    await handleOrderCancelled(event);
    break;
  // ...
  default:
    break;
}

Só descobrimos isso analisando o JSON bruto de um evento capturado no log estruturado, comparando campo por campo com a documentação:

{
  "id": "b3f1...",
  "code": "PLC",
  "fullCode": "PLACED",
  "orderId": "a921...",
  "merchantId": "9f02...",
  "createdAt": "2026-09-03T14:22:10.000Z"
}

O problema do cancelamento assíncrono

A correção foi introduzir um estado intermediário, só para pedidos origin='ifood':

ALTER TABLE ifood_orders ADD COLUMN cancellation_pending boolean DEFAULT false;
ALTER TABLE ifood_orders ADD COLUMN cancellation_requested_at timestamptz;

A investigação mais longa: por que o evento de cancelamento às vezes não chegava

Trocando em miúdos, essa foi a parte que mais consumiu tempo do projeto, e a que mais ensinou. Reuni algumas hipóteses que guiaram essa trajetória.

Hipótese 1: instabilidade genérica do sandbox

{
  "fullCode": "CONCLUDED",
  "metadata": {
    "triggerEvent": {
      "previousStatus": "DISPATCHED",
      "value": "CONCLUDED"
    }
  }
}

Isso reforçou a hipótese, mas não explicava por que, em alguns testes, o evento de cancelamento nunca chegava, nem depois de horas.

Hipótese 2: o motivo do cancelamento importava

Hipótese 3: o Handshake Platform

{
  "fullCode": "CANCELLED",
  "metadata": {
    "CANCELLATION_DISPUTE": {
      "IS_CONTESTABLE": "CANCELLATION_IS_CONTESTABLE"
    }
  }
}

Ou seja, o campo só indicava que aquele cancelamento poderia, em tese, ser contestado pelo consumidor. Não significava que estava, de fato, esperando handshake.

Homologação: quando "funcionar certo" não é suficiente

O que sustentou toda essa investigação

logger.info({
  event: "ifood.polling.event_received",
  merchantId,
  orderId: event.orderId,
  code: event.code,
  fullCode: event.fullCode,
  raw: event,
});

O que você precisa saber quando for integrar com marketplaces por polling

Como estruturei uma esteira de desenvolvimento acelerada por IA

Felipe Bufelli — Wed, 16 Sep 2026 18:27:31 +0000

Spec-Driven Development + GitHub Actions + Claude Code

O problema que eu tinha em mãos

Toda esteira de desenvolvimento passa pelos mesmos gargalos manuais. Alguém escreve uma spec, alguém revisa, alguém implementa, alguém abre uma Pull Request (PR), alguém revisa de novo. Cada troca de mão é uma pausa, um contexto perdido, um "deixa eu ver isso amanhã".
No entanto, na squad em que atuo, decidimos atacar isso de um jeito diferente. Transformamos boa parte desse fluxo em uma esteira automatizada, em que um agente de IA (Claude Code) executa as etapas repetíveis do processo, e um humano só entra nos pontos que realmente exigem análise.
O resultado é uma pipeline rodando dentro do GitHub, dirigida inteiramente por labels em Issues, seguindo o modelo de Spec-Driven Development (Spec Kit).
E eu pensei: porque não falar sobre essa transformação? Assim, esse artigo é o "como" por trás disso, incluindo os erros que travaram o piloto e o que ainda estamos ajustando.

O conceito central

A regra de ouro do design é simples de enunciar e poderosa na prática: A label sdd:* do Issue é a fonte da verdade. O board do GitHub Project é apenas a visão.
Isso resolve um problema clássico de automação. Quando o estado "real" mora em um lugar editável (o board) por qualquer um, a qualquer momento, e a automação tenta inferir o que fazer a partir dele, criam-se condições de corrida e estados inconsistentes. Ao colocar a label como única fonte de verdade, o board vira só uma janela: bonita, útil, mas descartável.
O mapeamento fundamental é 1 card = 1 spec = 1 branch:
Card: um Issue aberto por um template específico ("Spec card").
Spec: a pasta specs/NNN-slug/ gerada pelo agente.
Branch: NNN-slug, nascida de staging, com PR de volta pra staging.
Mover o card de coluna é, na prática, trocar a label. Cada troca dispara os workflows via evento issues: labeled.

A máquina de estados

O ponto mais importante do design é que nem toda etapa é automática. Cada label carrega um type que decide o comportamento:

Type	Significado	O agente executa?
gate	Etapas de validação humana	Não, só espera
auto	Etapa do agente	Sim, roda, commita, avança
external	Delegado a outro workflow (deploy)	Não
terminal	Fim (done)	Não
failure	Bloqueado	Não

Na prática, o fluxo intercala etapas automáticas com etapas de validação humana. O agente gera a spec, mas um humano valida antes do plano ser gerado. O agente gera o plano e as tasks, mas um humano aprova antes da implementação rodar. O agente implementa, mas um humano revisa o PR antes do deploy.
Essa alternância responde direto a uma pergunta que qualquer engenheiro sênior faz antes de aprovar esse tipo de sistema: e se o agente decidir algo errado? Bem, a resposta é que ele nunca decide sozinho o suficiente para causar dano sem alguém ter validado o passo anterior.

Anatomia de uma execução automática

Quando uma label do tipo auto é aplicada, o workflow principal roda uma sequência bem definida:

Resolve o estágio, lendo a configuração da label e exportando os atributos necessários.
Garante que a branch do card existe, criando-a a partir de staging de forma idempotente.
Faz checkout da branch.
Monta o prompt para o agente, concatenando instruções base com a instrução específica da etapa.
Executa o agente (Claude Code) via GitHub Action.
Se houve mudança de arquivos, commita e faz push.
Se a etapa abre PR, abre como rascunho, por convenção de título.
Comenta um resumo no card.
Avança a label automaticamente, disparando a próxima etapa da cascata.
Em caso de falha, bloqueia o card e comenta o link da execução com erro. E um detalhe fez diferença na prática: algumas etapas declaram que precisam gerar artefatos, arquivos novos ou modificados. Se a etapa roda e nada muda no repositório, o job falha de propósito, porque um agente pode ter um falso positivo sem ter escrito nada - o que entendemos como uma falha silenciosa.

Os erros que travaram o piloto

1. Workflows disparados por eventos de Issue só funcionam a partir do branch default

Se você edita o workflow numa branch de feature, ele não dispara. Todo ajuste nos workflows da esteira precisa chegar na branch principal para valer. Essa foi a causa número um de "por que isso não rodou".

2. Falso-sucesso silencioso

Sem configurar o modo de permissão correto na execução do agente, ele roda com permissões restritas: o comando não escreve nenhum arquivo, mas a execução retorna sucesso mesmo assim. CI verde, board avançando, e nada de fato foi feito. A defesa foi o mecanismo de exigir artefatos: se a etapa deveria gerar arquivos e não gerou, o job falha explicitamente em vez de deixar passar.

3. A autenticação do git quebra depois da execução do agente

A ação que executa o agente reconfigura a autenticação do git no runner, o que faz o git push seguinte falhar com erro de autenticação. Por aqui, a correção consistiu em fazer o push usando uma URL autenticada explicitamente, em vez de depender da configuração padrão do runner.

4. O token padrão do GitHub Actions não dispara outros workflows

Essa é uma proteção anti-loop intencional do GitHub. Se você troca uma label usando o token padrão, isso não dispara os workflows que escutam esse evento. Na prática, o board para de sincronizar e a cascata de etapas é simplesmente interrompida, sem erro nenhum aparente. Nesse caso, a solução foi usar um token de acesso pessoal dedicado para as operações que precisam dessa cascata.

5. O token padrão também não pode abrir Pull Requests

Restrição direta do GitHub Actions em repositórios: por padrão, ele não tem permissão para criar ou aprovar PRs. De novo, resolvido com o token dedicado.

6. Comandos de GraphQL pra listar ou ver PRs exigem escopo de organização que o token não tinha

A solução foi trocar esses comandos específicos por chamadas REST equivalentes, que exigem um escopo mais simples.
Nenhum desses é complexo isoladamente. Juntos, formam o tipo de fricção que trava um piloto promissor na primeira semana se você não souber que eles existem.

Segurança: tratando o conteúdo do Issue como dado não confiável

O corpo e o título do Issue são editáveis por qualquer pessoa com acesso ao repositório, e esse conteúdo entra no prompt do agente. Isso é, por definição, uma superfície de prompt injection.
Assim, as mitigações aplicadas foram:
Repositório privado, com controle de quem pode aplicar labels.
Instrução explícita ao agente para tratar o conteúdo do card como dado, nunca como comando: sem perguntas interativas, sem trocar de branch, sem ações fora do escopo da etapa.
Um delimitador aleatório, gerado a cada execução, para evitar injeção de comandos via variáveis de ambiente do workflow.
Isso não elimina o risco por completo. Qualquer label pode, em tese, disparar um job com permissão de escrita. Para o estágio atual, de uso interno, esse risco residual foi aceito conscientemente. E com isso, chegamos ao próximo passo de hardening, que é uma lista de permissão mais granular de quem pode acionar cada etapa.

Onde estamos hoje

A esteira está rodando há um mês e meio, processando de 4 a 6 specs por semana de forma contínua. E aqui é importante dizer que não é prova de conceito, é uso real e recorrente.
Ao escrever esse artigo, tem um aprendizado que vale a pena compartilhar: no começo, as specs estavam sendo escritas com escopo grande demais. O efeito prático disso é que a implementação gerada pelo agente frequentemente não cobria 100% do que tinha sido especificado - o escopo era grande demais para uma única execução guiada capturar por completo.
Nesse contexto, para corrigir, não mexemos no motor da esteira, mas, sim,no início do processo, com specs menores e mais enxutas, delimitando melhor o escopo. Granularidade da unidade de trabalho importa tanto para um agente quanto importa para um time humano dividir uma sprint - algo que ainda estamos refinando.

Se eu fosse começar de novo

Bom, e aí você me pergunta: e se fosse necessário fazer tudo novamente? Primeiro, eu desenharia a validação de granularidade das specs desde o primeiro dia, em vez de descobrir na prática que specs grandes geram implementações incompletas. E manteria exatamente como está a decisão de intercalar as etapas de validação humana com etapas automáticas: foi essa escolha que tornou possível confiar na esteira sem abrir mão de controle nos pontos que realmente importam.
Se você está pensando em estruturar algo parecido, o conselho mais prático que eu tenho é: comece assumindo que o agente vai retornar sucesso em situações que não são sucesso nenhum, e construa suas próprias redes de segurança para isso. Se há algum segredo, é não confiar só no código de saída da execução.