botija

Buscame el código, botija.

API HTTP que recibe un código EAN y devuelve los datos del producto consultando supermercados de Uruguay y Argentina.

No existe API pública oficial de productos en estos mercados. Cada estrategia replica la llamada que el frontend de cada supermercado hace a su backend (VTEX en todos los casos hasta hoy).

Deploy

cp .env.example .env       # editar y poner un API_TOKEN seguro
docker compose up -d

Uso

curl -H "Authorization: Bearer $API_TOKEN" \
     http://localhost:8198/product/8445291738775

{
  "ean": "8445291738775",
  "name": "Café Soluble Nescafe Gold Signature 95 G",
  "brand": "Nescafé",
  "category": "Comestibles/Almacen/Café",
  "store": "El Dorado",
  "description": "Cafe Nescafe Gold Frasco 95gr",
  "image_base64": "UklGRpaPAABXRUJQVlA4..."
}

category, store, description vienen del primer supermercado que matcheó — no se completan desde estrategias posteriores. Pueden venir vacíos si el supermercado no los expone (ej: Tata no tiene category ni description).

image_base64 es la imagen re-encodeada como WebP. Si la descarga falla, viene null. Para usarla:

<img src="data:image/webp;base64,${response.image_base64}" />

Códigos: 200 encontrado · 401 token inválido · 404 no encontrado.

Documentación interactiva en /docs.

Configuración — .env

Variable	Default	Descripción
API_TOKEN	—	Token Bearer requerido. Obligatorio.
STRATEGIES	—	Estrategias activas en orden de consulta, separadas por coma.
STRATEGY_TIMEOUT	5	Segundos máximos por estrategia. Si se excede, se pasa a la siguiente.

name, brand e image_base64 se completan a través de estrategias (si la primera no tiene marca, la siguiente puede aportarla). category, store y description solo vienen del primer match.

Estrategias actuales

Estrategia	Supermercado	País
tata	Tata	UY
eldorado	El Dorado	UY
dia	Dia	AR
jumbo	Jumbo	AR
carrefour	Carrefour	AR
masonline	Más Online	AR
vea	VEA	AR
discoar	Disco Argentina	AR

Desarrollo local

Setup inicial (una sola vez):

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env       # editar y poner un API_TOKEN

Comandos:

.venv/bin/uvicorn api:app --reload --port 8198   # server con autoreload
.venv/bin/python product_lookup.py               # CLI interactivo
.venv/bin/python product_lookup.py test          # test de cada estrategia

Agregar una estrategia

1. Identificar el endpoint. Si la URL de búsqueda tiene el patrón /<ean>?_q=<ean>&map=ft, es VTEX IO clásico → copiar strategies/eldorado.py y cambiar dominio y locale. Para otros stacks, capturar el tráfico con DevTools → Network → Export HAR y buscar qué respuesta JSON contiene el producto. Ver strategies/tata.py como ejemplo de FastStore.

2. Implementar strategies/nuevo.py extendiendo ProductLookupStrategy. Setear store en el ProductInfo retornado. Sobreescribir test_ean si el supermercado no tiene el EAN de prueba por defecto.

3. Registrar en _REGISTRY dentro de product_lookup.py y agregar al STRATEGIES del .env.

4. Verificar con python product_lookup.py test.

Estructura

api.py                  # FastAPI app + auth bearer
product_lookup.py       # ProductInfo, ProductLookup, _REGISTRY, CLI
image.py                # Descarga + conversión a WebP base64
strategies/             # Una clase por supermercado
Dockerfile
docker-compose.yml

Disclaimer

Este proyecto es de uso personal y educativo. No está afiliado, asociado, autorizado ni respaldado por ninguno de los supermercados mencionados. Todas las marcas y nombres comerciales pertenecen a sus respectivos dueños.

El script consulta endpoints públicos que los propios sitios exponen a sus frontends, sin evadir autenticación ni protecciones. Cada quien es responsable del uso que le da.

El software se provee "tal cual". Si un supermercado cambia su API, la estrategia correspondiente puede dejar de funcionar.