================================================================================
                   ÍNDICE DE TEMPLATES - FACTURA ELECTRÓNICA v4.4
                              Costa Rica - Hacienda
================================================================================

Carpeta: /4_4/fe/
Fecha de Creación: Enero 2026
Formato: XML según especificación XSD v4.4

================================================================================
ARCHIVOS DISPONIBLES
================================================================================

1. README.md
   ───────────
   • Guía completa y detallada de los templates
   • Instrucciones de uso paso a paso
   • Referencia rápida de códigos y validaciones
   • Ejemplos de cálculos
   • Integración con aplicación

2. template_base_factura.xml
   ──────────────────────────
   • Estructura principal de una factura electrónica
   • Contiene todos los elementos obligatorios
   • Incluye: Emisor, Receptor, Condiciones de venta, Detalle
   • Punto de partida para crear nuevas facturas
   • Uso: Base para todas las facturas

3. template_linea_detalle_simple.xml
   ──────────────────────────────────
   • Línea de detalle para productos/servicios sin complejidad
   • 1 producto por línea
   • Soporta descuentos (hasta 5)
   • Tarifa IVA única
   • Uso: La mayoría de productos estándar (comida, ropa, servicios)

4. template_linea_detalle_multimpuesto.xml
   ────────────────────────────────────────
   • Línea con múltiples impuestos
   • Ejemplo: Cerveza (IVA + Impuesto Selectivo)
   • Soporta impuestos específicos (consumo, bebidas alcohólicas, etc.)
   • Uso: Productos con impuestos adicionales al IVA

5. template_linea_surtido.xml
   ──────────────────────────
   • Línea de un paquete/combo/surtido
   • Combina 2 o más productos diferentes
   • Cada componente se detalla por separado
   • Cálculo de impuestos por componente
   • Uso: Combos de restaurante, kits de productos, promociones

6. template_linea_exenta.xml
   ──────────────────────────
   • Línea con productos/servicios SIN IVA (Exentos)
   • Código de tarifa IVA = 06 (0%)
   • Ejemplos: Leche, pan, medicinas, servicios médicos
   • Incluye dos ejemplos: alimentos y servicios médicos
   • Uso: Productos protegidos por ley

7. ejemplo_factura_completa.xml
   ────────────────────────────
   • Factura de ejemplo con TODOS los tipos de líneas
   • Contiene:
     - Línea simple con descuento (Arroz)
     - Línea exenta (Leche)
     - Línea con IVA 13% (Atún)
     - Línea con surtido (Combo)
   • Totales calculados correctamente
   • Uso: Referencia visual completa

8. INDICE.txt (este archivo)
   ──────────────────────────
   • Descripción de todos los archivos
   • Guía de navegación rápida

================================================================================
CÓMO USAR ESTOS TEMPLATES EN TU APLICACIÓN
================================================================================

OPCIÓN 1: Copia Manual
──────────────────────
1. Abre el template que necesites en tu editor XML
2. Copia y adapta los valores ficticios con datos reales
3. Duplica líneas de detalle según sea necesario
4. Recalcula totales
5. Valida contra el XSD

OPCIÓN 2: Generación Automática (Recomendado)
──────────────────────────────────────────────
1. En tu aplicación (PHP/Laravel), carga el template_base_factura.xml
2. Usa str_replace() para reemplazar variables {{VARIABLE}}
3. Genera dinámicamente <LineaDetalle> basado en datos de BD
4. Calcula totales automáticamente
5. Firma digitalmente y envía a Hacienda

Pseudocódigo en PHP:
```php
// Cargar template
$xml = file_get_contents('4_4/fe/template_base_factura.xml');

// Reemplazar datos
$xml = str_replace('{{NOMBRE_EMISOR}}', $factura->emisor, $xml);
$xml = str_replace('{{NOMBRE_RECEPTOR}}', $factura->receptor, $xml);

// Generar líneas dinámicamente
$detalles = '';
foreach ($factura->items as $item) {
    $detalles .= generarLineaDetalle($item);
}
$xml = str_replace('{{LINEAS_DETALLE}}', $detalles, $xml);

// Guardar
file_put_contents('factura_001_001_000000001.xml', $xml);
```

================================================================================
FLUJO DE TRABAJO RECOMENDADO
================================================================================

1. PLANIFICACIÓN
   ├─ Determinar tipo de líneas que necesitas:
   │  ├─ ¿Todas simples? → template_linea_detalle_simple.xml
   │  ├─ ¿Con múltiples impuestos? → template_linea_detalle_multimpuesto.xml
   │  ├─ ¿Hay combos/surtidos? → template_linea_surtido.xml
   │  └─ ¿Hay productos exentos? → template_linea_exenta.xml
   │
   └─ Revisar ejemplo_factura_completa.xml para ver todos juntos

2. DESARROLLO
   ├─ Usar template_base_factura.xml como estructura principal
   ├─ Adaptar cada tipo de línea necesaria
   ├─ Implementar cálculos de totales
   └─ Validar contra XSD

3. TESTING
   ├─ Probar con ejemplo_factura_completa.xml
   ├─ Verificar cálculos manuales
   ├─ Validar XML bien formado
   └─ Probar con herramientas (XMLLint, etc.)

4. PRODUCCIÓN
   ├─ Integrar generación automática en aplicación
   ├─ Implementar firma digital
   ├─ Configurar comunicación con Hacienda
   └─ Monitorear respuestas

================================================================================
REFERENCIA RÁPIDA DE CAMPOS CRÍTICOS
================================================================================

CLAVE (50 dígitos):
   TT-DD-MM-AAAA-XXXXXXXXXXXX-YYYYYYYYYY-ZZ
   TT = Tipo (01=Factura, 02=Nota Débito, 03=Nota Crédito)

CÓDIGOS IMPORTANTES:
   CodigoActividadEmisor = 6 dígitos CIIU
   CodigoCABYS = 13 dígitos (referencia BCCR)
   TipoIdentificación = 01/02/03/04
   CodigoTarifaIVA = 06(0%), 07(1%), 08(13%), 09(27%)

MONTOS:
   • Máximo 18 dígitos, 2 decimales (para dinero)
   • Máximo 16 dígitos, 3 decimales (para cantidades)

VALIDACIONES:
   • XML bien formado
   • Contra XSD schema
   • Números de línea consecutivos (1-1000)
   • Cálculos precisos de totales
   • Códigos de catálogos válidos

================================================================================
NOTAS IMPORTANTES
================================================================================

✓ Los templates son PLANTILLAS - adapta los valores ficticios a tu caso
✓ Siempre valida contra el XSD después de generar
✓ Los cálculos deben ser precisos (redondeo a 2 decimales)
✓ La Clave debe ser única por factura
✓ Requiere CERTIFICADO DIGITAL para firmar y enviar a Hacienda
✓ Consulta documentación oficial de Hacienda para campos opcionales
✓ Los montos en ejemplo_factura_completa.xml son ficticios

================================================================================
CONTACTO Y SOPORTE
================================================================================

• Ministerio de Hacienda (CR): https://www.hacienda.go.cr/
• Banco Central (Catálogos): https://www.bccr.fi.cr/
• Documentación XSD: Incluida en proyecto
• Técnico: facturacion@empresa.cr

================================================================================
VERSIÓN: 4.4 - ENERO 2026
================================================================================