# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
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