---
id: INT-008
type: Integration
title: "OCR de productos"
provider: "Google Cloud Vision"
status: Pendiente
integration_type: "Reconocimiento de imágenes"
created_at: 2026-01-10
updated_at: 2026-01-10
simco_version: "3.8.0"
tags:
  - ocr
  - vision
  - google-cloud
  - imagenes
  - facturas
  - productos
---

# INT-008: OCR de productos

## Metadata

| Campo | Valor |
|-------|-------|
| **Codigo** | INT-008 |
| **Proveedor** | Google Cloud Vision |
| **Tipo** | Reconocimiento de imágenes |
| **Estado** | Pendiente |
| **Multi-tenant** | Si |
| **Fecha planeada** | 2026-Q1 |
| **Owner** | Backend Team |

---

## 1. Descripcion

Integración con Google Cloud Vision API para reconocimiento óptico de caracteres (OCR) y análisis de imágenes. Permite a los changarros digitalizar facturas de proveedores, escanear códigos de barras de productos, y extraer información de tickets y documentos mediante fotografías tomadas con el celular.

**Casos de uso principales:**
- Escaneo y extracción de datos de facturas de proveedores
- Lectura de códigos de barras y QR de productos
- Captura de precios de etiquetas de productos
- Digitalización de tickets de compra para gastos
- Reconocimiento de texto en notas y pedidos manuscritos

---

## 2. Credenciales Requeridas

### Variables de Entorno

| Variable | Descripcion | Tipo | Obligatorio |
|----------|-------------|------|-------------|
| GOOGLE_CLOUD_PROJECT_ID | ID del proyecto en GCP | string | SI |
| GOOGLE_CLOUD_KEYFILE | Ruta al archivo de service account | string | SI |
| VISION_API_ENDPOINT | Endpoint regional (opcional) | string | NO |
| VISION_MAX_RESULTS | Máximo de resultados por request | number | NO |

### Ejemplo de .env

```env
# Google Cloud Vision OCR
GOOGLE_CLOUD_PROJECT_ID=michangarrito-prod
GOOGLE_CLOUD_KEYFILE=/path/to/gcp-service-account.json
VISION_API_ENDPOINT=https://vision.googleapis.com
VISION_MAX_RESULTS=10
```

### Archivo de Service Account

El service account debe tener el rol `roles/cloudvision.user`:

```json
{
  "type": "service_account",
  "project_id": "michangarrito-prod",
  "private_key_id": "xxx",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "vision-api@michangarrito-prod.iam.gserviceaccount.com",
  "client_id": "123456789",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token"
}
```

---

## 3. Arquitectura

```
┌─────────────────────────────────────────────────────────────────┐
│                      MiChangarrito                              │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────┐  │
│  │   Mobile/    │───▶│  API Server  │───▶│  VisionService   │  │
│  │   Web App    │    │              │    │                  │  │
│  │  (Cámara)    │    │              │    │  - OCR           │  │
│  └──────────────┘    └──────────────┘    │  - Barcode       │  │
│                                          │  - Document      │  │
│                                          └────────┬─────────┘  │
└────────────────────────────────────────────────────┼────────────┘
                                                     │
                                                     ▼
                                          ┌──────────────────┐
                                          │  Google Cloud    │
                                          │  Vision API      │
                                          │                  │
                                          │  - TEXT_DETECTION│
                                          │  - DOCUMENT_TEXT │
                                          │  - PRODUCT_SEARCH│
                                          └──────────────────┘
```

### Flujo de Escaneo de Factura

1. Usuario toma foto de factura con la app
2. Imagen se sube a Cloud Storage (temporal)
3. VisionService envía imagen a Vision API
4. API retorna texto estructurado detectado
5. Parser extrae campos: proveedor, productos, montos
6. Sistema sugiere registro de compra/gasto
7. Usuario confirma y datos se guardan en BD

---

## 4. Endpoints

### Endpoints Consumidos (Google Cloud Vision API)

| Método | Endpoint | Descripción |
|--------|----------|-------------|
| POST | `/v1/images:annotate` | Analizar imagen (OCR, labels, etc.) |
| POST | `/v1/images:asyncBatchAnnotate` | Análisis asíncrono batch |
| POST | `/v1/files:annotate` | Analizar PDFs |
| GET | `/v1/operations/{name}` | Estado de operación async |

### Features Utilizados

| Feature | Uso |
|---------|-----|
| `TEXT_DETECTION` | OCR básico para texto en imágenes |
| `DOCUMENT_TEXT_DETECTION` | OCR avanzado para documentos |
| `PRODUCT_SEARCH` | Búsqueda de productos por imagen |
| `BARCODE_DETECTION` | Detección de códigos de barras/QR |

### Endpoints Expuestos (MiChangarrito)

| Método | Endpoint | Descripción |
|--------|----------|-------------|
| POST | `/api/v1/ocr/scan` | Escanear imagen genérica |
| POST | `/api/v1/ocr/invoice` | Escanear factura |
| POST | `/api/v1/ocr/barcode` | Leer código de barras |
| POST | `/api/v1/ocr/receipt` | Escanear ticket de compra |
| GET | `/api/v1/ocr/jobs/{id}` | Estado de escaneo async |

---

## 5. Notas de Implementacion

- Vision API cobra por imagen procesada (~$1.50 USD por 1000 imágenes)
- Implementar caché de resultados para imágenes idénticas
- Comprimir imágenes antes de enviar (máx 20MB, recomendado <4MB)
- Usar DOCUMENT_TEXT_DETECTION para facturas (mejor precisión)
- Implementar parser específico para facturas mexicanas (RFC, CFDI)
- Considerar preprocesamiento de imagen (contraste, rotación)
- Almacenar imágenes originales para auditoría
- Manejar rate limits: 1800 requests/min por proyecto
- Implementar retry con exponential backoff
- Para alto volumen, considerar batch async
- Validar formatos soportados: JPEG, PNG, GIF, BMP, WEBP, PDF
- Extraer coordenadas de texto para highlighting en UI