De dados brutos de produtos a recomendações inteligentes e insights de sentimento — em minutos.

No e-commerce moderno, dados são abundantes, mas inteligência é escassa. Varejistas estão sentados sobre milhares de descrições de produtos, montanhas de avaliações de clientes e oportunidades de cross-sell inexploradas — mesmo assim, a maioria ainda depende de regras rígidas e mantidas manualmente para alimentar suas seções de "Você também pode gostar".

Construir uma infraestrutura de IA adequada para resolver isso — gerenciando bancos de dados vetoriais, modelos de embedding, orquestração de LLMs e isolamento de dados por cliente — é um projeto de engenharia de meses. É exatamente essa lacuna que o NeoRetailBrain (NRB) foi criado para fechar.

O NRB é uma suíte de API enterprise que transforma seu catálogo de produtos em um motor de recomendação semântico e suas avaliações de clientes em inteligência de negócio estruturada. Tudo via chamadas REST simples. Sem infraestrutura de ML necessária.

Este artigo explica o que o NRB faz, como funciona e como integrá-lo de ponta a ponta em Python.

Quais Problemas o NeoRetailBrain Resolve

1. O problema do "Você também pode gostar"

Motores de recomendação tradicionais operam por regras de associação: quem comprou X também comprou Y. Isso funciona em escala massiva (pense na Amazon), mas exige volumes enormes de transações para gerar regras confiáveis. Para a maioria dos varejistas, resulta em sugestões genéricas e pouco úteis.

O NRB usa busca vetorial semântica no lugar. Quando você faz o upload de um produto, o NRB gera uma representação de alto nível do seu significado — baseada no nome, categoria e descrição. Quando um cliente adiciona itens ao carrinho, o NRB encontra os produtos do seu catálogo semanticamente mais próximos do que ele já pretende comprar. Sem histórico de transações. Sem problema de cold-start.

Um cliente comprando fones de ouvido com cancelamento de ruído recebe como sugestão um case de transporte e um adaptador USB-C — não porque outros usuários compraram esses itens juntos, mas porque a IA entende que eles são contextualmente relacionados.

2. O problema da análise de avaliações

Notas com estrelas são um instrumento grosseiro. Um produto com média 3,8 não te diz nada sobre por que os clientes estão insatisfeitos — nem quais funcionalidades específicas eles amam. O Insight Engine do NRB processa lotes de avaliações por um LLM e retorna:

• Pontuação geral de sentimento (0.0 = muito negativo, 1.0 = muito positivo)
• Principais tópicos positivos — as funcionalidades mais elogiadas
• Principais tópicos negativos — os pontos de dor que os clientes continuam mencionando
• Resumo executivo — uma síntese de duas frases legível por humanos

Essa é a diferença entre saber que seu produto tem 3,8 e saber que "os clientes adoram a qualidade do som, mas reclamam consistentemente do conforto durante uso prolongado."

3. O problema do isolamento por cliente

Cada negócio tem um catálogo diferente. O NRB mantém todos completamente separados. Seus produtos são indexados apenas sob a sua conta — nenhum outro consumidor da API pode acessar ou influenciar suas recomendações. O isolamento é aplicado a nível de banco de dados em cada consulta.

Como Funciona: A Arquitetura Completa

O NRB expõe seis endpoints organizados em três módulos:

Gestão de Catálogo
├── POST /catalog/upsert          → Upload / atualização de produtos
├── GET  /catalog/products        → Listagem do catálogo indexado
└── DELETE /catalog/product/{id}  → Remoção de um produto

Motor de Recomendação
└── POST /cross_sell              → Sugestões de cross-sell

Motor de Insights
└── POST /analyze_reviews         → Análise de sentimento em lote

Monitoramento
└── GET  /health                  → Status do sistema

O fluxo recomendado é direto:

Upload do catálogo → Indexação e embedding → Consulta ao cross_sell com carrinho → Recomendações

Primeiros Passos

Você só precisa do Python e da biblioteca requests:

pip install requests

Configure suas credenciais uma vez e reutilize em todas as chamadas:

import requests

API_KEY = "SUA_CHAVE_RAPIDAPI_AQUI"
HOST = "neoretailbrain-api-ai-powered-e-commerce-intelligence.p.rapidapi.com"
BASE_URL = f"https://{HOST}"

HEADERS = {
    "X-RapidAPI-Key": API_KEY,
    "X-RapidAPI-Host": HOST,
    "Content-Type": "application/json"
}

Nunca deixe sua chave de API exposta no código frontend ou em repositórios públicos. Use variáveis de ambiente.

Passo 1: Verifique se a API está Online

Antes de qualquer chamada crítica para o negócio, verifique o status do sistema:

response = requests.get(f"{BASE_URL}/health", headers=HEADERS)
print(response.json())

{
  "status": "UP",
  "database": "CONNECTED",
  "ai_subsystem": "READY"
}

Passo 2: Faça o Upload do Seu Catálogo de Produtos

Este é o passo que desbloqueia tudo. Envie seus produtos para /catalog/upsert e o NRB vai gerar automaticamente uma representação semântica para cada um.

products = [
    {
        "product_id": "PROD-001",
        "name": "Fone de Ouvido Sem Fio com Cancelamento de Ruído",
        "category": "eletronicos",
        "description": "Fone over-ear com 30 horas de bateria, cancelamento ativo de ruído e qualidade de som premium. Design dobrável para viagens."
    },
    {
        "product_id": "PROD-002",
        "name": "Case de Transporte para Fone",
        "category": "acessorios",
        "description": "Case de proteção com estrutura rígida para fones over-ear. Exterior resistente à água com organizador de cabos interno."
    },
    {
        "product_id": "PROD-003",
        "name": "Adaptador USB-C para Áudio",
        "category": "acessorios",
        "description": "Adaptador de alta fidelidade USB-C para P2 (3,5mm). Compatível com as principais marcas de smartphones e notebooks."
    },
    {
        "product_id": "PROD-004",
        "name": "Almofadas de Substituição",
        "category": "acessorios",
        "description": "Almofadas de espuma memory foam para substituição, compatíveis com a maioria dos fones over-ear. Acabamento em couro proteico macio."
    }
]

response = requests.post(f"{BASE_URL}/catalog/upsert", json={"products": products}, headers=HEADERS)
print(response.json())

{
  "processed": 4,
  "inserted": 4,
  "updated": 0,
  "errors": []
}

O endpoint é idempotente — chame novamente com o mesmo product_id e ele atualiza o registro existente. Isso significa que você pode executá-lo a cada deploy ou sincronização de catálogo sem efeitos colaterais.

Uma observação sobre qualidade das descrições: O campo description é o que impulsiona a precisão das recomendações. Quanto mais contexto você fornecer — materiais, compatibilidade, caso de uso, público-alvo — melhor será o matching semântico. Uma descrição como "Case para fone" vai produzir resultados significativamente mais fracos do que "Case de proteção com estrutura rígida para fones over-ear, exterior resistente à água e organizador de cabos interno."

Limite por lote: até 500 produtos por requisição. Para catálogos maiores, divida em lotes sequenciais de 500.

Passo 3: Audite Seu Catálogo

Antes de ir para produção, verifique o que foi indexado:

response = requests.get(f"{BASE_URL}/catalog/products", headers=HEADERS)
data = response.json()

print(f"Total de produtos indexados: {data['total']}")
for product in data['products']:
    print(f"  [{product['product_id']}] {product['name']} — {product['category']}")

Total de produtos indexados: 4
  [PROD-001] Fone de Ouvido Sem Fio com Cancelamento de Ruído — eletronicos
  [PROD-002] Case de Transporte para Fone — acessorios
  [PROD-003] Adaptador USB-C para Áudio — acessorios
  [PROD-004] Almofadas de Substituição — acessorios

Para remover um produto descontinuado:

response = requests.delete(f"{BASE_URL}/catalog/product/PROD-003", headers=HEADERS)
print(response.json())
# {"message": "Product 'PROD-003' removed successfully."}

Passo 4: Obtenha Recomendações de Cross-Sell

Com o catálogo indexado, o motor de recomendação está pronto. Passe os itens que estão no carrinho do cliente:

cart = [
    {"product_id": "PROD-001", "category": "eletronicos"}
]

response = requests.post(
    f"{BASE_URL}/cross_sell",
    json={"cart_items": cart, "top_k": 3},
    headers=HEADERS
)
print(response.json())

{
  "recommended_product_ids": ["PROD-004", "PROD-002"],
  "confidence_score": 0.8912,
  "message": "Recomendações geradas com sucesso."
}

O motor identificou que um cliente comprando fones de ouvido provavelmente vai querer almofadas de substituição e um case de transporte — sem uma única regra escrita manualmente.

Entendendo o confidence score

Scores acima de 0.80 significam que o motor encontrou produtos genuinamente relevantes no seu catálogo. Scores abaixo de 0.80 indicam que o fallback foi acionado (mais sobre isso a seguir).

O Fallback: Nunca uma Resposta Vazia

O NRB foi projetado para sempre retornar algo útil, mesmo quando o catálogo está vazio, o banco de dados está temporariamente inacessível ou nenhum produto semanticamente próximo é encontrado.

Nesses casos, o motor ativa um fallback baseado em regras:

Seu front-end deve ser construído para exibir recomendações independentemente de virem do seu catálogo ou do fallback — sua seção de "Você também pode gostar" nunca deve ficar em branco.

Passo 5: Analise as Avaliações dos Clientes

O Insight Engine funciona de forma independente do catálogo. Envie qualquer lote de avaliações e receba inteligência estruturada:

reviews = [
    {"review_id": "rev_001", "text": "O cancelamento de ruído é incrível. Uso em todas as viagens de avião e bloqueia tudo."},
    {"review_id": "rev_002", "text": "Qualidade de som excelente, mas fica desconfortável depois de umas duas horas de uso contínuo."},
    {"review_id": "rev_003", "text": "A bateria durou exatamente o que prometia. Usei por 12 horas viajando sem precisar carregar."},
    {"review_id": "rev_004", "text": "O case parece barato pelo preço cobrado. Esperava qualidade melhor nos acessórios."},
    {"review_id": "rev_005", "text": "Melhor fone que já tive. O suporte me ajudou com a configuração em minutos."}
]

response = requests.post(f"{BASE_URL}/analyze_reviews", json={"reviews": reviews}, headers=HEADERS)
data = response.json()['data']

print(f"Score de sentimento: {data['overall_sentiment']}")
print(f"Tópicos positivos:   {data['positive_topics']}")
print(f"Tópicos negativos:   {data['negative_topics']}")
print(f"Resumo:              {data['executive_summary']}")

{
  "processed_count": 5,
  "overall_sentiment": 0.76,
  "positive_topics": [
    "Eficácia do cancelamento de ruído",
    "Precisão da duração da bateria",
    "Qualidade do som",
    "Agilidade do suporte ao cliente"
  ],
  "negative_topics": [
    "Conforto em uso prolongado",
    "Qualidade dos acessórios pelo preço"
  ],
  "executive_summary": "Os clientes estão muito satisfeitos com o desempenho de áudio e a duração da bateria, mas apontam consistentemente desconforto em uso prolongado e decepção com a qualidade dos acessórios em relação ao preço."
}

Isso é inteligência acionável. Em vez de ver uma média de 3,8 estrelas e tentar adivinhar o problema, seu time de produto agora sabe exatamente o que melhorar.

Limite por lote: até 100 avaliações por requisição. Para volumes maiores, divida em lotes sequenciais.

Script Completo de Ponta a Ponta

Aqui está tudo junto em um único script — uma integração completa que você pode rodar hoje:

import requests

API_KEY = "SUA_CHAVE_RAPIDAPI_AQUI"
HOST = "neoretailbrain-api-ai-powered-e-commerce-intelligence.p.rapidapi.com"
BASE_URL = f"https://{HOST}"
HEADERS = {
    "X-RapidAPI-Key": API_KEY,
    "X-RapidAPI-Host": HOST,
    "Content-Type": "application/json"
}

# 1. Health check
health = requests.get(f"{BASE_URL}/health", headers=HEADERS).json()
print(f"[1] API: {health['status']} | DB: {health['database']}")

# 2. Upload do catálogo
products = [
    {"product_id": "PROD-001", "name": "Fone de Ouvido Sem Fio", "category": "eletronicos",
     "description": "Fone over-ear premium com cancelamento de ruído ativo e 30h de bateria."},
    {"product_id": "PROD-002", "name": "Case de Transporte", "category": "acessorios",
     "description": "Case rígido resistente à água para fones over-ear."},
    {"product_id": "PROD-003", "name": "Almofadas de Substituição", "category": "acessorios",
     "description": "Almofadas de memory foam compatíveis com a maioria dos fones over-ear."},
]
upsert = requests.post(f"{BASE_URL}/catalog/upsert", json={"products": products}, headers=HEADERS).json()
print(f"[2] Catálogo: {upsert['inserted']} inseridos, {upsert['updated']} atualizados")

# 3. Auditoria do catálogo
catalog = requests.get(f"{BASE_URL}/catalog/products", headers=HEADERS).json()
print(f"[3] {catalog['total']} produtos indexados")

# 4. Recomendação de cross-sell
cart = [{"product_id": "PROD-001", "category": "eletronicos"}]
recs = requests.post(f"{BASE_URL}/cross_sell", json={"cart_items": cart, "top_k": 2}, headers=HEADERS).json()
print(f"[4] Recomendados: {recs['recommended_product_ids']} (confiança: {recs['confidence_score']})")

# 5. Análise de avaliações
reviews = [
    {"review_id": "r1", "text": "Cancelamento de ruído incrível, perfeito para viagens."},
    {"review_id": "r2", "text": "Som ótimo mas fica desconfortável depois de duas horas de uso."},
    {"review_id": "r3", "text": "Bateria durou exatamente 30 horas conforme anunciado. Muito impressionado."},
]
insights = requests.post(f"{BASE_URL}/analyze_reviews", json={"reviews": reviews}, headers=HEADERS).json()['data']
print(f"[5] Sentimento: {insights['overall_sentiment']} — {insights['executive_summary']}")

Limitações Para Conhecer Antes de Ir a Produção

Transparência é fundamental. Aqui está o que você deve considerar ao integrar o NRB em produção:

A qualidade das recomendações depende da qualidade do catálogo. Descrições rasas como "Camiseta azul, tamanho M" vão produzir recomendações fracas. Descrições ricas, cobrindo materiais, casos de uso, compatibilidade e público-alvo, vão produzir resultados fortes. Vale investir tempo nos dados dos seus produtos.

100 avaliações por lote, 500 produtos por lote. Projete seus pipelines em torno desses limites. Para ingestão de alto volume, processe em lotes paralelos.

O fallback é automático, mas genérico. Se o seu catálogo estiver vazio, o motor de cross-sell vai retornar sugestões baseadas em regras com IDs de produto genéricos. Sempre popule seu catálogo antes de direcionar tráfego de produção para o endpoint /cross_sell.

Paginação do catálogo ainda não está disponível. O endpoint /catalog/products retorna seu catálogo completo. Para catálogos muito grandes, essa resposta pode ser considerável — planeje adequadamente no lado do cliente.

Latência na primeira requisição. Se a API ficou ociosa por algum tempo, a primeira requisição pode demorar um pouco mais do que as subsequentes enquanto os serviços internos inicializam. Esse é um custo único por período de inatividade e não afeta o throughput contínuo.

Conclusão

O NeoRetailBrain comprime o que seria meses de trabalho em infraestrutura de IA em algumas chamadas de API. Você traz o catálogo e as avaliações; o NRB cuida dos embeddings, da busca semântica, da orquestração de LLM e do isolamento por cliente.

O resultado: um motor de recomendação que entende seus produtos da forma que um vendedor experiente entenderia, e um pipeline de análise de avaliações que diz ao seu time de produto exatamente o que melhorar a seguir.

Pronto para integrar? Encontre a documentação completa dos endpoints e comece a testar no RapidAPI Hub.

NRB — Dados Precisos. Comércio Inteligente.