sgse-app/packages/backend/convex/actions/README_BUSCAR_PRODUTO.md

Configuração de APIs para Busca de Produtos por Código de Barras

Este documento descreve como configurar as variáveis de ambiente necessárias para as diferentes APIs de busca de produtos.

Fontes de Dados Disponíveis

O sistema busca produtos em 5 fontes diferentes, em ordem de prioridade:

1. GS1 Brasil (Prioridade 1 - requer credenciais)
2. Bluesoft Cosmo (Prioridade 2 - requer credenciais)
3. Product-Search.net (Prioridade 3 - pode requerer credenciais)
4. Busca Unificada (Prioridade 4 - GRATUITA, sem credenciais)
5. Open Food Facts (Prioridade 5 - GRATUITA, sem credenciais)

Configuração das APIs

1. GS1 Brasil (API Verified by GS1)

A GS1 Brasil oferece a API "Verified by GS1" para consulta de produtos cadastrados.

Passos para obter credenciais:

1. Acesse o portal: https://apicnp.gs1br.org
2. Faça login ou crie uma conta
3. No menu "Apps", cadastre uma nova aplicação
4. Obtenha o Client_ID e Client_Secret

Configuração no Convex:

# Client ID da aplicação registrada
npx convex env set GS1_BRASIL_CLIENT_ID "seu-client-id-aqui"

# Client Secret da aplicação
npx convex env set GS1_BRASIL_CLIENT_SECRET "seu-client-secret-aqui"

# URL do token (opcional, padrão já configurado)
npx convex env set GS1_BRASIL_TOKEN_URL "https://apicnp.gs1br.org/oauth/token"

# URL da API (opcional, padrão já configurado)
npx convex env set GS1_BRASIL_API_URL "https://apicnp.gs1br.org/api/v1/products"

Documentação:

• Manual: https://www.gs1br.org/educacao-e-eventos/Documents/Manual%20do%20Usu%C3%A1rio%20-%20API%20Verified%20by%20GS1_v.03.pdf
• Portal: https://apicnp.gs1br.org

---

2. Bluesoft Cosmos

A Bluesoft oferece uma API REST para consulta de produtos por código de barras (GTIN/EAN).

Passos para obter credenciais:

1. Acesse: https://api.cosmos.bluesoft.com.br/api
2. Faça login na plataforma
3. Obtenha seu token de API (X-Cosmos-Token) e User-Agent
4. Ambos estarão disponíveis na página após fazer login

Configuração no Convex:

# Token de autenticação da Bluesoft (X-Cosmos-Token)
npx convex env set BLUESOFT_API_KEY "seu-token-aqui"

# URL da API (opcional, padrão já configurado)
npx convex env set BLUESOFT_API_URL "https://api.cosmos.bluesoft.com.br"

Importante: O sistema usa automaticamente o endpoint correto /gtins/{codigo}.json conforme a documentação oficial.

Endpoint:

• GET /gtins/{código}.json - Recupera detalhes do produto através do GTIN/EAN informado

Estrutura de Resposta:

A API retorna informações incluindo:

• description: Nome/descrição do produto
• brand.name: Nome da marca
• gpc.description: Categoria do produto
• ncm.code e ncm.description: Código NCM e descrição
• thumbnail: URL da imagem do produto
• price: Preço formatado
• gross_weight e net_weight: Peso bruto e líquido

Documentação:

• Documentação Oficial: https://api.cosmos.bluesoft.com.br/api
• Central de Ajuda: https://ajuda.bluesoft.com.br/
• Suporte: suporte.api@bluesoft.com.br

---

3. Product-Search.net

Plataforma que fornece informações sobre produtos com base em códigos de barras.

Passos para obter credenciais (opcional):

1. Acesse: https://product-search.net
2. Crie uma conta (se necessário)
3. Obtenha sua API key (se disponível no seu plano)

Configuração no Convex:

# API Key (opcional - pode funcionar sem autenticação dependendo do plano)
npx convex env set PRODUCT_SEARCH_API_KEY "sua-api-key-aqui"

# URL da API (opcional, padrão já configurado)
npx convex env set PRODUCT_SEARCH_API_URL "https://api.product-search.net/v1/products"

Documentação:

• Site: https://product-search.net

---

4. Busca Unificada

API gratuita e pública para busca de produtos por código de barras. Não requer configuração ou credenciais.

Características:

• ✅ Totalmente gratuita para uso pessoal e comercial
• ✅ Sem necessidade de cadastro ou credenciais
• ✅ Sempre disponível
• ✅ Foco em produtos brasileiros

Documentação:

• Site: https://api-produtos.seunegocionanuvem.com.br

---

5. Open Food Facts

API gratuita e pública, não requer configuração. Sempre disponível como fallback.

Características:

• ✅ Totalmente gratuita e colaborativa
• ✅ Sem necessidade de cadastro ou credenciais
• ✅ Foco em produtos alimentícios
• ✅ Base de dados colaborativa internacional

---

Ordem de Prioridade

O sistema tenta buscar em todas as fontes em paralelo e retorna o primeiro resultado válido encontrado, seguindo esta ordem de prioridade:

1. GS1 Brasil (requer credenciais)
2. Bluesoft Cosmo (requer credenciais)
3. Product-Search.net (pode requerer credenciais)
4. Busca Unificada (gratuita, sem credenciais) ⭐
5. Open Food Facts (gratuita, sem credenciais) ⭐

⭐ Nota: As APIs gratuitas (Busca Unificada e Open Food Facts) funcionam sem nenhuma configuração adicional e estão sempre disponíveis.

Verificação da Configuração

Para verificar se as variáveis de ambiente estão configuradas:

npx convex env list

Notas Importantes

1. Limites de Uso: Cada API pode ter limites de requisições por período. Consulte a documentação de cada serviço.

2. Custos: Algumas APIs podem ter custos associados. Verifique os planos disponíveis.

3. Segurança: As credenciais são armazenadas de forma segura nas variáveis de ambiente do Convex e nunca são expostas ao frontend.

4. Fallback: Se uma API falhar ou não estiver configurada, o sistema automaticamente tenta as outras fontes. As APIs gratuitas (Busca Unificada e Open Food Facts) sempre estarão disponíveis mesmo sem configuração.

5. Timeout: Todas as requisições têm timeout de 5 segundos para evitar travamentos.

Testando a Configuração

Após configurar as variáveis de ambiente, teste a busca com um código de barras conhecido:

1. Acesse a página de cadastro de materiais
2. Digite ou escaneie um código de barras
3. O sistema deve buscar em todas as fontes configuradas
4. O modal mostrará a fonte dos dados encontrados

Suporte

Em caso de problemas:

1. Verifique se as credenciais estão corretas
2. Verifique se as URLs dos endpoints estão corretas
3. Consulte os logs do Convex para erros específicos
4. Verifique a documentação oficial de cada API