---

📑 Sumário

• Sobre o Projeto
• Por que esse projeto existe
• Arquitetura
• Stack Tecnológica
• Pontos Altos do Projeto
• Fases do Projeto
• Como Funciona — O Padrão Propor-Aprovar-Aplicar
• Estrutura de Arquivos
• Segurança & Boas Práticas
• Variáveis de Ambiente
• Como Rodar Localmente
• Conectando ao Claude
• Roadmap
• Autor
• Licença

---

🎯 Sobre o Projeto

EcommAPI é uma plataforma de automação de operações de e-commerce que conecta três sistemas que normalmente vivem isolados:

• A API do fornecedor (origem do catálogo e do estoque real)
• O ERP Bling (sistema de gestão central e fonte para o e-commerce)
• Uma camada de IA (Claude e Gemini, intercambiáveis) que analisa vendas e propõe otimizações

O sistema é construído sobre uma filosofia central: a IA propõe, o humano aprova, e só então a mudança é aplicada. Nada de auto-pilot irresponsável — toda alteração de preço, descrição ou estoque passa por uma camada explícita de aprovação humana antes de tocar o Bling.

---

💡 Por que esse projeto existe

A motivação é concreta e mensurável: substituir uma integração paga de terceiros que conectava a API do fornecedor ao Bling de forma limitada, custosa e sem visibilidade.

Construir a própria integração trouxe três ganhos:

Benefício	Impacto
💰 Economia direta	Eliminação do custo mensal recorrente do serviço externo
🔧 Controle total	Lógica de sincronização ajustada à realidade do negócio, sem caixa-preta
🤖 Extensibilidade com IA	Camada de inteligência para análise de vendas e sugestões de preço — impossível com a ferramenta paga

---

🏛 Arquitetura

flowchart LR
    Supplier[("🏭 API do<br/>Fornecedor")] -->|estoque / preço| Sync["⚙️ sync_worker.py<br/>(loop 24/7)"]
    Sync -->|diff incremental| State[("🗄️ SQLite<br/>state.db")]
    Sync -->|2 req/s + backoff| Bling[("🛒 Bling ERP<br/>(API v3)")]

    User([👤 Operador]) <-->|conversa| Claude["🧠 Claude / Gemini<br/>(brain.py)"]
    Claude -->|MCP tools| Server["🔌 server.py<br/>(MCP Server)"]
    Server -->|propostas| Pending[("📋 pending_<br/>changes.json")]
    User -->|aprovação| Pending
    Pending -->|aplicar| Bling

    Bling -.->|webhook Fase 3| Future["🚀 fulfillment<br/>futuro"]

Princípios de arquitetura:

Princípio	Implementação
Human-in-the-loop	Toda mudança passa por aprovação humana antes de ser aplicada
Separação leitura/escrita	Ferramentas de análise são livres; só uma ferramenta escreve no Bling
Respeito a rate limits	2 req/s contra o Bling com exponential backoff em erros 429/5xx
Diff incremental	SQLite local armazena estado; só itens que mudaram são enviados
AI provider-agnostic	LLMProvider abstrai Claude e Gemini — troca-se um pelo outro sem mexer no resto
Audit trail completo	Toda alteração aplicada fica registrada em applied_log.jsonl

---

🛠 Stack Tecnológica

Camada	Tecnologia	Uso
Linguagem	Python 3.11+	Toda a base do projeto
IA	Anthropic Claude (SDK anthropic)	Provedor de LLM padrão
IA	Google Gemini (SDK google-genai)	Provedor de LLM alternativo (intercambiável)
Protocolo	MCP — Model Context Protocol	Conecta a IA ao Bling via ferramentas padronizadas
ERP	Bling API v3	Sistema central (produtos, estoque, vendas, preços)
Persistência	SQLite	Estado local para diff incremental do sync
Auth	OAuth 2.0	Autorização do Bling com refresh automático de token
HTTP	requests	Cliente HTTP com retry e backoff
Config	python-dotenv	Variáveis de ambiente

---

⭐ Pontos Altos do Projeto

🛡 Padrão Propor → Aprovar → Aplicar

A IA nunca altera dados diretamente. Toda sugestão entra numa fila explícita (pending_changes.json) e só é aplicada quando o operador aprova por ID. É um design pattern de segurança que evita o pesadelo clássico de "IA mudou o preço de mil produtos sozinha".

🔄 AI Provider-Agnostic

A camada brain.py define uma interface LLMProvider que abstrai Claude e Gemini. Trocar de provedor é uma linha de configuração — não uma refatoração. Isso protege o projeto de vendor lock-in e permite escolher o melhor modelo para cada tipo de tarefa.

⚙️ Rate Limiting com Exponential Backoff

A API do Bling tem limites estritos (3 req/s, 120k/dia). O sync_worker.py opera deliberadamente abaixo do limite (2 req/s) e implementa backoff exponencial em erros 429 e 5xx — uma demonstração de respeito a constraints externas e de robustez operacional.

📊 Diff Incremental Contra SQLite

Em vez de empurrar o catálogo inteiro do fornecedor para o Bling a cada ciclo, o worker mantém o estado anterior em SQLite e envia apenas o que mudou. Resultado: ordens de magnitude a menos de requisições, e respeito automático ao rate limit.

🔒 Trava de Variação Máxima

Mesmo com aprovação humana, uma trava de segurança (MAX_VARIACAO_PCT) impede mudanças bruscas de preço. Se a proposta exceder o limite configurado, ela é bloqueada antes mesmo de chegar na fila — proteção contra erros de digitação e respostas anômalas da IA.

---

🚦 Fases do Projeto

O projeto é organizado em três fases evolutivas, cada uma agregando capacidades à anterior.

✅ Fase 1 — Sincronização de Estoque (em produção)

Worker 24/7 que mantém o estoque do Bling em paridade com o catálogo do fornecedor. Operações de estoque seguem o modelo v3 do Bling (POST /estoques com tipo B para saldo absoluto), com matching por campo codigo (SKU).

🔧 Fase 2 — Aprovação de Preços e Métricas via MCP (código completo)

Servidor MCP (server.py) que expõe ao Claude (ou outro cliente MCP) ferramentas de análise e proposta:

• Análise (livre): listar_produtos, analisar_vendas, produtos_sem_giro
• Proposta (registra, não aplica): propor_alteracao_preco, propor_alteracao_descricao
• Revisão (somente leitura): listar_alteracoes_pendentes, cancelar_proposta
• Aplicação (a única que escreve): aplicar_alteracoes_aprovadas

Alterações de preço vindas do fornecedor também caem nessa fila — nada é aplicado automaticamente.

📋 Fase 3 — Fulfillment Automatizado via Webhooks (planejado)

Recebimento de eventos de pedido do Bling via webhook e criação automática do pedido na API do fornecedor. Requer:

• Endpoint público HTTPS (FastAPI)
• Idempotência por ID do evento (proteção contra retries duplicados)
• Fila inicial de aprovação manual antes de habilitar automação completa
• API do fornecedor com endpoint de criação de pedido

🌐 Integração Futura — Mercado Livre

O brain.py já é arquiteturalmente preparado para gerar sugestões de listings do Mercado Livre via API pública de sellers, mantendo o mesmo padrão de aprovação humana antes de aplicar qualquer mudança em anúncios.

---

🔄 Como Funciona — O Padrão Propor-Aprovar-Aplicar

1. Claude analisa vendas    ─►  propor_alteracao_preco  ─►  [proposta fica pendente]
                                                                      │
                                                                      ▼
2. Você revisa o diff       ◄────────────────────────────  pending_changes.json
                            │
                            ▼
3. Aplicar IDs aprovados    ─►  aplicar_alteracoes_aprovadas  ─►  escreve no Bling
                                                                      │
                                                                      ▼
                                                              applied_log.jsonl

Exemplo de uso conversacional:

"Liste as vendas dos últimos 30 dias, identifique os 5 produtos com menor giro e proponha um desconto de 10% em cada um."

O Claude chama as ferramentas de análise, raciocina sobre os dados, e cria propostas — sem tocar no Bling. Você revisa:

"Aplique apenas as propostas abc123 e def456."

Só então os dois preços específicos são alterados no ERP.

---

📂 Estrutura de Arquivos

EcommAPI/
├── sync_worker.py           # Worker 24/7 de sincronização de estoque (Fase 1)
├── server.py                # Servidor MCP para preços e métricas (Fase 2)
├── brain.py                 # Camada AI provider-agnostic (Claude / Gemini)
├── bling_client.py          # Cliente da API Bling v3 com OAuth + refresh
├── supplier_client.py       # Cliente da API do fornecedor
├── pricing.py               # Lógica de precificação e validações
├── state.py                 # Estado local em SQLite (diff incremental)
├── autorizar.py             # Script de autorização OAuth inicial
├── pricing_rules.example.json   # Template de regras de precificação
├── requirements.txt         # Dependências Python
├── SETUP-sync.md            # Guia detalhado de setup do worker
├── .env.example             # Template de variáveis de ambiente
└── .gitignore               # Proteção contra commits acidentais de segredos

---

🔒 Segurança & Boas Práticas

A segurança foi tratada como requisito de primeira classe, com múltiplas camadas:

• ✅ Nenhuma credencial versionada — .env e bling_tokens.json no .gitignore desde o primeiro commit
• ✅ Aprovação humana obrigatória — IA nunca escreve no Bling sem confirmação explícita por ID
• ✅ Separação leitura/escrita — apenas uma ferramenta tem permissão de escrita
• ✅ Trava de variação máxima — MAX_VARIACAO_PCT bloqueia mudanças bruscas mesmo se aprovadas
• ✅ Audit trail completo — toda alteração aplicada registrada em applied_log.jsonl com antes/depois
• ✅ OAuth com refresh automático — tokens nunca expostos no código, renovação transparente
• ✅ Rate limiting respeitoso — operação deliberadamente abaixo do limite com backoff exponencial
• ✅ Modo dry-run — SYNC_DRY_RUN=1 permite validar lógica sem tocar dados reais
• ✅ Homologação primeiro — BLING_SANDBOX=1 para testes em ambiente isolado antes da produção

---

🔧 Variáveis de Ambiente

Crie um arquivo .env na raiz do projeto a partir do .env.example. Nunca commite valores reais.

# Bling — Credenciais OAuth
BLING_CLIENT_ID=<seu-client-id>
BLING_CLIENT_SECRET=<seu-client-secret>
BLING_DEPOSITO_ID=<id-do-deposito>

# Bling — Modo de operação
BLING_SANDBOX=1            # 1 = homologação, 0 = produção
MAX_VARIACAO_PCT=30        # Bloqueia variações de preço acima deste percentual
SYNC_DRY_RUN=0             # 1 = simula sem aplicar, 0 = aplica de verdade

# Fornecedor
SUPPLIER_API_URL=<url-da-api-do-fornecedor>
SUPPLIER_API_KEY=<sua-chave>

# Provedores de IA (escolha um ou ambos)
ANTHROPIC_API_KEY=<sua-chave-claude>
GEMINI_API_KEY=<sua-chave-gemini>

---

▶️ Como Rodar Localmente

Pré-requisitos: Python 3.11+ e conta no Bling com app criado.

1. Clonar e instalar dependências

git clone https://github.com/pedrofalchi-fullstack/EcommAPI.git
cd EcommAPI

# Criar e ativar ambiente virtual
python -m venv .venv
.\.venv\Scripts\activate          # Windows
# source .venv/bin/activate        # Linux/Mac

# Instalar dependências
pip install -r requirements.txt

2. Criar o app no Bling

No painel do Bling: Preferências → Integrações → API → Criar aplicativo. Anote o client_id e client_secret, e defina a redirect URI (ex.: http://localhost:8080/callback).

3. Configurar variáveis de ambiente

cp .env.example .env   # e preencha com os valores reais

4. Autorizar o acesso ao Bling (uma vez só)

python autorizar.py

O script abre o navegador, você autoriza, e o bling_tokens.json é gerado automaticamente. O cliente passa a renovar tokens sozinho a partir daí.

5. Rodar o worker de sincronização (Fase 1)

python sync_worker.py

6. Rodar o servidor MCP (Fase 2)

mcp dev server.py

---

🧠 Conectando ao Claude

Com o servidor MCP rodando, é possível conectá-lo ao Claude Desktop ou ao Claude Code.

Claude Desktop

Edite o arquivo de configuração de MCP servers e adicione (ajuste o caminho):

{
  "mcpServers": {
    "ecommapi": {
      "command": "python",
      "args": ["C:/caminho/completo/EcommAPI/server.py"]
    }
  }
}

Claude Code

claude mcp add ecommapi python /caminho/completo/EcommAPI/server.py

Depois é só conversar com o Claude pedindo análises e propostas. Ele vai chamar as ferramentas, propor mudanças, e aguardar sua aprovação.

---

🔜 Roadmap

• Fase 1 — Worker de sincronização de estoque 24/7
• Fase 2 — Servidor MCP com aprovação humana de preços
• Camada AI provider-agnostic (Claude + Gemini intercambiáveis)
• Modo dry-run para validação sem efeitos colaterais
• Audit trail completo de alterações
• Fase 3 — Fulfillment automatizado via webhooks do Bling
• Endpoint público HTTPS (FastAPI) para receber eventos
• Integração com Mercado Livre (API pública de sellers)
• Relatório semanal automático cruzando vendas + giro
• Trava de margem mínima ao propor alterações de preço

---

👤 Autor

Desenvolvido por Pedro Henrique Falchi.

GitHub LinkedIn

---

📄 Licença

Este projeto está licenciado sob a Licença MIT — consulte o arquivo LICENSE para mais detalhes.

---