Pré-projeto — Integração PIED → X-Adm¶


Documento	Pré-projeto (avaliação de viabilidade e caminhos)
Versão	1.0 — decidido
Data	2026-06-15 (decisão registrada em 2026-07-09)
Autor	Gustavo Madruga
Status	Aprovado — Caminho 2 (Robusto)
Aprovador	Marcelo Garabeli

Para que serve este documento: avaliar a viabilidade de integrar a plataforma PIED ao ERP X-Adm, apresentar os caminhos possíveis (com prós, contras e custos) e pedir uma decisão. É propositalmente não-técnico. Aprovado este pré-projeto, segue-se o Projeto (documento técnico): endpoints, estrutura de dados, eventos, contratos e plano de testes.

::: {custom-style="Decisao"} ► DECISÃO DA DIRETORIA (2026-07-09 — Marcelo Garabeli): aprovado o Caminho 2 (Robusto) — servidor always-on na nuvem, com webhook (tempo real) + poll REST + entrega desacoplada via PowerSync. A implantação é em fases (§10): a Fase 1 (captura raw) entra em produção primeiro; a Fase 2 (transform + entrega ao X-Adm) segue com os dados reais já acumulados. O detalhamento técnico está no Projeto e na decisão 0002. :::

1. Sumário Executivo¶

A Maxsul (cliente da X-Adm) adquiriu uma empresa de painéis solares que opera na plataforma PIED. Hoje, cada venda feita na PIED é redigitada manualmente no X-Adm — produto, cliente e pedido — para só então emitir a nota fiscal. É lento, repetitivo e sujeito a erro. A Maxsul pediu à X-Adm uma integração que elimine essa redigitação.

É viável. A PIED disponibiliza todos os dados necessários por uma API, e confirmamos que conseguimos trazê-los para o X-Adm de forma automática e auditável.

Há dois caminhos: - Caminho 1 (Simples): um programa que puxa os dados da PIED periodicamente ou sob demanda. Baixo custo e risco, cobre 100% dos dados — mas sem tempo real. - Caminho 2 (Robusto): um servidor na nuvem que recebe os pedidos em tempo real e mantém tudo sincronizado automaticamente com o X-Adm. Mais robusto, com custo/esforço um pouco maiores.

Decisão solicitada: aprovar o início do projeto, definindo qual caminho seguir.

2. Contexto e problema¶

Quem é quem. A X-Adm fornece à Maxsul (nosso cliente) o ERP com toda a parte fiscal — notas, cadastros, impostos. A Maxsul adquiriu uma empresa de painéis solares, e essa empresa opera na plataforma PIED, onde cadastra produtos, clientes e registra as vendas (pedidos).

A dor. Hoje, cada venda fechada na PIED é redigitada manualmente no X-Adm — todos os cadastros (produto, cliente, pedido) — para só então emitir a nota fiscal. É lento, repetitivo, sujeito a erro e consome tempo da equipe da Maxsul.

A demanda. A própria Maxsul solicitou à X-Adm que automatize essa ponte, eliminando a redigitação. O objetivo é um fluxo automático, incremental (só o que muda) e auditável da PIED para o X-Adm.

📌 Nota de atenção — benefício ainda qualitativo. Hoje o ganho está descrito apenas de forma qualitativa ("elimina a redigitação, ganha tempo"). Seria interessante quantificar o tempo economizado, pela fórmula:

Economia (h/mês) = pedidos fechados/dia × tempo de redigitação por pedido (min) × dias úteis/mês ÷ 60

Pressuposto inicial: funil de ~5 orçamentos/dia → ~1 pedido fechado/dia; ~22 dias úteis/mês. Falta medir com a Maxsul o tempo de redigitação por pedido (cliente + produtos + pedido). Exemplo ilustrativo (a confirmar): 1 pedido/dia × 20 min × 22 dias ÷ 60 ≈ ~7 h/mês. Quanto maior o volume de pedidos, maior o retorno — vale levantar o número real antes da decisão.

3. Objetivo e escopo¶

Objetivo: trazer da PIED para o X-Adm, de forma automática e confiável, os dados de produtos, clientes e pedidos, prontos para emissão de NF e contabilidade.

3.1 Dentro do escopo¶

Importação automática, incremental e auditável de produtos, clientes e pedidos da PIED → X-Adm.
Implementar uma das duas modalidades de integração:
Integração simples — o X-Adm consome a API REST da PIED de tempos em tempos ou sob demanda (Caminho 1).
Integração robusta — servidor em nuvem com comunicação em tempo real (Caminho 2).

3.2 Fora do escopo (nesta fase)¶

Orçamentos no X-Adm (podem ser coletados para uso interno, mas não entram no ERP).
Devolver dados do X-Adm para a PIED (status/preço/estoque).
Definição técnica detalhada (endpoints, estrutura de dados, eventos) — fica para o Projeto.
Regras fiscais finais da baixa no núcleo do ERP.

3.3 Premissas¶

A PIED disponibiliza os dados via API com token de acesso.
A infraestrutura de nuvem já existe (Nuvem Wiechert).
Há pontos a confirmar com PIED/X-Adm que não impedem iniciar (§9).

4. Partes interessadas¶

Papel	Quem
Cliente / solicitante	Maxsul
Operação de origem (vendas na PIED)	Empresa de painéis solares (adquirida pela Maxsul)
Fornecedor da solução / execução	X-Adm — Equipe de Integração
Patrocínio / decisão (interno X-Adm)	Diretoria X-Adm
Fonte dos dados	PIED (plataforma / suporte)
Destino dos dados	ERP X-Adm (usado pela Maxsul)
Infraestrutura	Nuvem Wiechert

5. Viabilidade — o que já confirmamos¶

A PIED disponibiliza todos os dados necessários por API. Produtos, clientes e pedidos: viável.
Existem dois jeitos de receber os dados:
Puxar (perguntar "o que mudou?" de tempos em tempos) — cobre tudo.
Receber aviso em tempo real (a PIED avisa quando um pedido muda) — cobre só pedidos, com algumas lacunas; não cobre produtos.
Puxar já é suficiente para ter todos os dados. O tempo real é ganho de agilidade, não requisito de completude.
Pontos a confirmar com PIED/X-Adm existem, mas nenhum impede começar (§9).

As APIs da PIED foram validadas (a nível de documentação/contrato) e a viabilidade do projeto está OK. Para sacramentar restam duas verificações, que serão feitas na fase de Projeto: (1) acesso direto à API da PIED com token real (confirmar payloads e comportamento ao vivo); e (2) resolver as lacunas de mapeamento de dados (campos com regra de negócio em aberto — ../../PENDENCIAS.md). Nenhuma delas muda a conclusão de viabilidade.

Os contratos da PIED e a modelagem do X-Adm que sustentam esta viabilidade estão nos Anexos A–C (ao final do documento).

6. Caminho 1 — Simples (puxar via REST)¶

Como funciona: um programa Java enxuto (PiedRestClient) é acionado de tempos em tempos (agendado) ou sob demanda (o próprio X-Adm dispara). Conecta na PIED, baixa produtos/clientes/pedidos e grava no banco do X-Adm. Não exige nada rodando o tempo todo.

flowchart TB
    XADM["X-Adm<br/>(agendado ou sob demanda)"] -->|dispara| PRC["PiedRestClient<br/>(Java)"]
    PRC -->|puxa produtos / clientes / pedidos| PIED["PIED API"]
    PRC -->|grava| DB[("Banco do X-Adm")]

Prós - Mais simples e mais barato: não precisa de servidor ligado 24 horas. - Menos peças, menos pontos de falha; manutenção fácil. - Roda agendado ou sob demanda — só consome recurso quando executa. - Já traz 100% dos dados necessários. - Fácil de reexecutar se falhar; controle total do ritmo (respeita o limite de uso da API).

Contras - Sem tempo real: dados só atualizam quando o programa roda. - Disparo sob demanda gera uma espera (aciona e aguarda). - A frequência precisa ser calibrada (rara demais atrasa; frequente demais bate no limite da API).

Quando faz sentido: quando atualizar "de tempos em tempos" atende o negócio. Ideal para começar e validar com baixo custo e risco.

7. Caminho 2 — Robusto (servidor na nuvem + sincronização)¶

Como funciona: um servidor na nuvem ligado o tempo todo que (a) recebe avisos instantâneos da PIED quando um pedido muda (tempo real) e (b) também sabe puxar o resto via REST (reaproveitando o programa do Caminho 1). Mantém um banco na nuvem sempre atualizado. Um segundo programa Java, com sincronização automática (PowerSync), repassa as mudanças ao X-Adm — sem o X-Adm precisar perguntar.

flowchart TB
    PIED["PIED"] -->|avisa em tempo real| SRV["Servidor na nuvem<br/>(webhook + REST)"]
    SRV -->|puxa o resto| PIED
    SRV -->|grava| DBC[("Banco na nuvem")]
    DBC -->|sincronização automática| JAVA["Programa Java<br/>(PowerSync)"]
    JAVA -->|envia| XADM["X-Adm"]

Prós - Tempo real para pedidos. - O X-Adm recebe as atualizações automaticamente — não precisa puxar nem esperar. - Mais resiliente: se a conexão cair, recupera sozinho e não perde atualização. - Desacoplado: coleta (nuvem) e entrega (X-Adm) evoluem separadamente. - Cobre tudo (tempo real + puxar o resto).

Contras - Mais peças (servidor sempre no ar, banco na nuvem, sincronização) → mais a manter/monitorar. - Maior esforço inicial. - A tecnologia de sincronização exige uma pequena parte em Kotlin (detalhe técnico isolado). - Pontos em aberto com a PIED pesam mais aqui (segurança e reenvio dos avisos em tempo real).

Quando faz sentido: quando o negócio precisa dos pedidos quase em tempo real no X-Adm e/ou não se quer depender de alguém acionar a sincronização.

8. Comparativo¶

Critério	Caminho 1 — Simples (REST)	Caminho 2 — Robusto (Servidor)
Tempo real (pedidos)	❌ Periódico / sob demanda	✅ Sim
Cobertura de dados	✅ Completa	✅ Completa
Custo de infraestrutura	🟢 Baixo	🟢 Baixo (infra já existe na Nuvem Wiechert)
Esforço de desenvolvimento	🟢 Baixo	🟡 Médio
Manutenção / nº de peças	🟢 Simples	🟡 Médio (simples, porém com mais peças)
Resiliência	🟢 Boa (reexecuta)	🟢 Alta (auto-recuperação)
X-Adm precisa "puxar"?	Sim (agendado/sob demanda)	Não (recebe automático)
Dependências externas em aberto	🟢 Poucas	🟡 Mais (segurança do webhook)

9. Riscos e pontos a confirmar¶

Com a PIED: segurança e política de reenvio dos avisos em tempo real; limites de uso da API; existência de ambiente de testes.
Com a X-Adm: algumas regras fiscais/de negócio (ex.: classificação fiscal do pedido, condição de pagamento).
Mitigação: o Caminho 1 depende de poucos desses pontos; nenhum impede iniciar a Fase 1. O detalhamento técnico e as prioridades estão em ../../PENDENCIAS.md.

10. Recomendação — caminho em fases¶

Os dois caminhos compartilham o mesmo núcleo (o cliente REST do Caminho 1 é reaproveitado dentro do servidor do Caminho 2). Começar simples não é trabalho jogado fora.

Fase	O quê	Esforço	Estimativa¹
1 — Integração simples (Caminho 1)	Puxar tudo da PIED e popular o X-Adm.	🟢 Baixo	~1 semana
2 — Tempo real (Caminho 2)	Servidor na nuvem + sincronização automática; reaproveita a Fase 1.	🟡 Médio	~2 semanas

¹ Estimativas preliminares (chute de ordem de grandeza), a confirmar no Projeto (fase técnica).

Assim a diretoria decide o investimento em tempo real depois de ver a viabilidade comprovada.

Valor estratégico do Caminho 2 (além desta integração)¶

Hoje o X-Adm tem bem resolvido o fluxo de SAÍDA de dados: extração em batch para BI e em tempo real para a Nota Sul Plata. O que ainda é frágil é o X-Adm RECEBER dados de APIs externas — não há um caminho consolidado.

O Caminho 2 não serve só para a PIED: ele pavimenta e solidifica esse processo de entrada de dados externos (servidor na nuvem + sincronização confiável + idempotência). Construído uma vez, vira base reutilizável para futuras integrações de entrada (outros fornecedores, marketplaces, parceiros), reduzindo custo e risco de cada próxima integração. Parte do investimento é, portanto, infraestrutura estratégica, não custo exclusivo desta integração.

11. Critérios de sucesso¶

Os dados da PIED (produto, cliente, pedido) chegam ao X-Adm de forma automática e correta.
A sincronização não gera retrabalho nem duplicidade (atualiza só o que muda).
Elimina a redigitação manual hoje feita pela Maxsul para emitir a nota fiscal.

12. Decisão solicitada e próximos passos¶

::: {custom-style="Decisao"} ► DECISÃO SOLICITADA À DIRETORIA: aprovar uma das opções — Fase 1 (mais rápida e barata, ~1 semana) ou Fase 2 (mais robusta, pavimentando o caminho para integrações futuras, ~2 semanas). :::

Após aprovação: elaboração do Projeto (documento técnico) — define endpoints, estrutura de dados, eventos, contratos, plano de testes e de implantação. O Projeto também sacramenta a viabilidade com acesso direto à API da PIED (token real) e a resolução das lacunas de mapeamento (../../PENDENCIAS.md). Em seguida, execução da fase aprovada.

13. Glossário¶

Termo	Significado
Maxsul	Cliente da X-Adm que solicitou a integração; adquiriu a empresa de painéis solares que opera na PIED.
PIED	Plataforma B2B onde acontecem os negócios (orçamentos/pedidos de energia solar). Fonte dos dados.
API / REST	Forma de um sistema oferecer dados a outro de forma programática.
Webhook	Aviso automático que a PIED envia quando algo muda (base do "tempo real").
PowerSync	Tecnologia que mantém dados sincronizados automaticamente entre um banco na nuvem e um programa.
Idempotência	Garantia de que reprocessar o mesmo dado não cria duplicidade.
Nuvem Wiechert	Infraestrutura de nuvem já existente onde os serviços rodam.

Anexos¶

Documentos-base que fundamentam o escopo (anexados na sequência):

Anexo A — Contrato da API REST da PIED (001-pied-rest-api.md) — endpoints, autenticação e JSON de request/reply das principais chamadas.
Anexo B — Contrato de Webhook da PIED (002-pied-webhook.md) — eventos, JSON do POST recebido, lacunas e segurança.
Anexo C — Modelagem do envio ao X-Adm (003-xadm-modelagem.md) — JSON que o X-Adm espera (cliente, produto, pedido).