Millennium ERP — Fonte de Dados

O Millennium é o ERP utilizado pelas lojas. É a fonte de verdade para clientes, vendas, vendedores e produtos.

Papel no sistema

O CRM puxa dados do Millennium periodicamente. Nunca escreve de volta no ERP.

Dados sincronizados:

• Lojas (filiais)
• Vendedores (funcionários)
• Clientes (com CPF, telefone, endereço)
• Transações (vendas)
• Produtos (catálogo)

Configuração

Variáveis de ambiente:

Variável	Descrição
MILLENNIUM_BASE_URL	URL base da API do Millennium
MILLENNIUM_USERNAME	Usuário de acesso
MILLENNIUM_PASSWORD	Senha
MILLENNIUM_FILIAL	Código da filial padrão (se aplicável)

Fluxo de sync

Sync completo (inicial ou reset)

POST /erp/sync/trigger (sem datas)
  → Busca todas as filiais ativas
  → Para cada filial: busca vendedores, clientes, transações
  → Para cada cliente: normaliza telefone, hasheia CPF, calcula store
  → Atualiza banco CRM

Sync incremental (diário)

POST /erp/sync/trigger { startDate, endDate }
  → Filtra por trans_id > Organization.lastCustomerTransId
  → Só sincroniza registros novos/alterados
  → Atualiza Organization.lastCustomerTransId ao final

Normalização de telefone

DDD + 9 dígitos → "11999999999"
Remove caracteres não-numéricos
Se 8 dígitos: insere "9" na posição DDD+1 (número fixo → celular)
Valida comprimento: 10 ou 11 dígitos

Deduplicação de clientes

Ordem de precedência:

1. Mesmo cpfHash → mesmo cliente, atualiza dados
2. Mesmo [storeId, externalId] → atualiza
3. Mesmo telefone normalizado → merge
4. Novo cliente → cria

Atribuição de vendedor preferido

Ao sincronizar transações, o sistema calcula o preferredSellerId do cliente baseado em:

1. Vendedor com mais compras recentes no último ano
2. Deve estar ativo (status = ACTIVE)
3. Deve pertencer a uma loja do cliente

Endpoints de sync no CRM

# Disparar sync manual
POST /erp/sync/trigger
{ "startDate": "2026-05-01", "endDate": "2026-05-23" }

# Ver histórico de syncs
GET /erp/sync/history

# Ver status do sync atual
GET /erp/sync/status

# Sync de produtos apenas
POST /erp/sync/products

Endpoints do Millennium usados

O CRM consome os seguintes endpoints da API Millennium:

GET /api/filiais                  → lojas
GET /api/funcionarios             → vendedores
GET /api/clientes                 → clientes
GET /api/transacoes               → vendas
GET /api/produtos                 → catálogo

Os endpoints exatos e parâmetros dependem da versão e configuração do Millennium da organização.

Campos mapeados

Cliente Millennium → CRM

Millennium	CRM (Customer)
nome	name
email	email
ddd + celular	phone (normalizado)
cpf	cpfHash + cpfEncrypted + cpfMasked
dt_nascimento	birthDate
cep	zipCode
cidade	city
uf	state
id_cliente	externalId
trans_id	transId (para sync incremental)

Produto Millennium → CRM

Millennium	CRM (Product)
produto (id numérico)	externalId
cod_produto	productCode
descricao1	name
descricao2	shortName
desc_colecao	collection
desc_departamento	department
desc_marca	brand
preco1	price
cores[*].descricao	colors[]
tamanhos[*].tamanho	sizes[]

Cron schedule

O sync automático roda diariamente via cron do NestJS:

0 3 * * *  → Sync incremental (últimas 24h)
0 7 * * *  → RFM recompute (pós-sync)

Tratamento de erros

• Erros de HTTP no Millennium são logados em JobRun com status = 'failed'
• Sync parcial: em caso de falha, o progresso não é revertido — na próxima execução, começa do último trans_id salvo
• Se o Millennium estiver fora do ar: dados ficam desatualizados mas o CRM continua funcionando com os dados existentes