0001 — MVP entra em produção só capturando raw¶
Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-07-10 · Decidido em: 2026-07-10
Contexto¶
O caminho robusto da integração PIED → X-Adm prevê webhook + poll + transform + entrega via
PowerSync. A documentação da PIED já se mostrou imprecisa uma vez: o pré-projeto descrevia um
delta implícito (apiSent/apiSentUpdated) que não existe na API real — só a validação com
token de produção revelou o mecanismo que funciona (?lastUpdateAfter, ADR 0002 do
poc-pied-simples). Para o webhook a situação é pior: os eventos, formas de payload e autenticação
estão descritos, mas nunca foram observados em produção.
Escrever o transform em cima de contrato não observado repetiria o erro do pré-projeto — com custo maior, porque transform errado suja o staging e o ERP.
Decisão¶
O MVP entra em produção apenas capturando dados brutos: recepção de webhook em
pied_webhook e poll REST em pied_rest, sem nenhuma transformação. A integração com o X-Adm
(fase 2) nasce desligada por toggle (pied.integracao.habilitada=false /
PIED_INTEGRACAO_HABILITADA) — hoje só o esqueleto do toggle existe no código.
Prioridade máxima é o tempo até produção: quanto antes o serviço estiver no ar, mais cedo há payloads reais acumulados para projetar a fase 2 com evidência.
Consequências¶
- A análise da API (volumes, eventos que chegam de fato, campos por payload) é feita com SQL nas tabelas landing, com dados reais.
- O webhook não rejeita payload inesperado — evento desconhecido é dado capturado (e a PIED não fica reentregando por erro nosso). Corpo não-JSON é envelopado como string JSON.
- Nenhuma escrita no ERP ou no staging do Integrador nesta fase; risco operacional é mínimo.
- O transform da fase 2 poderá reprocessar todo o histórico capturado desde o dia 1 (o raw é persistido antes de qualquer processamento — blueprint do poc-pied).
- Custo aceito: dados ficam "parados" no landing até a fase 2; a redigitação manual continua nesse meio-tempo.
Alternativas consideradas¶
- Entregar já com transform (MVP completo): rejeitado — contrato do webhook não observado; retrabalho quase certo e prazo maior até produção.
- Capturar só via poll (sem webhook): rejeitado — o webhook é exatamente a parte que precisa de observação em produção, e recebê-lo não custa quase nada.