# Factura Global Mensual — Documentación Técnica

**Versión DB:** v4.1  
**Commit:** `2b73c2c`

---

## Requerimiento SAT

El SAT permite agrupar tickets de contado (menores a $2,000) en una sola factura mensual tipo **Ingreso** con `InformacionGlobal`.

## Criterios de elegibilidad

Una venta es elegible para factura global si:
1. `metodo_pago_sat = 'PUE'` (pagado al momento)
2. `total <= $2,000`
3. `status = 'completed'`
4. No tiene CFDI individual timbrado (`cfdi_queue.status = 'stamped'`)
5. No está ya en una factura global (`sales.global_invoiced_at IS NULL`)
6. Fecha dentro del mes/año solicitado

## Arquitectura

### Tablas
- `global_invoice_sales (global_invoice_id, sale_id)` — relación N:M
- `sales.global_invoiced_at` — marca de inclusión

### XML
- `build_global_invoice_xml()` en `cfdi_builder.py`
- `InformacionGlobal Periodicidad="04"` (mensual)
- Receptor: `PUBLICO EN GENERAL` (RFC XAXX010101000)

---

## Endpoints

| Método | Endpoint | Descripción |
|--------|----------|-------------|
| `GET` | `/pos/api/invoicing/global-invoice/eligible-sales?year=&month=&branch_id=` | Preview de ventas elegibles |
| `POST` | `/pos/api/invoicing/global-invoice` | Genera factura global |
| `GET` | `/pos/api/invoicing/global-invoice/<id>` | Estado y ventas vinculadas |

### POST body
```json
{
  "year": 2026,
  "month": 6,
  "branch_id": 1
}
```

### Response
```json
{
  "id": 42,
  "status": "pending",
  "sales_count": 15,
  "total": 18450.00,
  "provisional_folio": "PRE-00042",
  "xml": "<?xml ...>"
}
```

---

## Flujo de uso (Frontend)

1. Ir a **Facturación**
2. Clic en botón **Factura Global**
3. Seleccionar año y mes
4. Clic en **Vista previa** para ver ventas elegibles
5. Clic en **Generar** para crear y encolar el CFDI
6. Procesar cola de timbrado normalmente

---

## Timbrado

La factura global entra en la cola `cfdi_queue` con:
- `type = 'ingreso'`
- `sale_id = NULL`
- Se timbra igual que cualquier otro CFDI vía Horux360