rckrdmrd
97f407c661
- Prefijo v2: MCH - TRACEABILITY-MASTER.yml creado - Listo para integracion como submodulo Workspace: v2.0.0 | SIMCO: v4.0.0
172 lines
6.5 KiB
Markdown
172 lines
6.5 KiB
Markdown
---
|
|
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
|