feat: implement barcode search configuration in 'Almoxarifado', integrating multiple external APIs for enhanced product information retrieval and improving user experience with new modals for data handling
This commit is contained in:
196
packages/backend/convex/actions/README_BUSCAR_PRODUTO.md
Normal file
196
packages/backend/convex/actions/README_BUSCAR_PRODUTO.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user