#  GUÍA DE DESPLIEGUE EN HOSTING - CONFIGURACIÓN SUNAT

**Última actualización:** 14 de Abril de 2026  
**Para:** Sistema de Facturación Electrónica

---

##  PRE-REQUISITOS EN EL HOSTING

Verifica que tu hosting tenga:

- **PHP 7.4+** (preferentemente 8.0 o superior)
- **Módulo `openssl`** habilitado (requerido para firmas digitales)
- **Módulo `curl`** habilitado (para conexión con SUNAT)
- **Módulo `mod_rewrite`** habilitado en Apache (para ruteo de URLs)
- **Acceso a crear archivos en servidor** (para guardar certificados)
- **Permiso de ejecutar comandos PHP** (para procesar comprobantes)

---

##  PASOS DE INSTALACIÓN

### 1. **Verificar Extensiones PHP**

Crea un archivo `/public/check-ext.php` con este contenido:

```php
<?php
$extensiones = ['openssl', 'curl', 'gd', 'json', 'pdo_mysql'];
foreach ($extensiones as $ext) {
    echo $ext . ': ' . (extension_loaded($ext) ? '✅ Habilitado' : '❌ NO HABILITADO') . PHP_EOL;
}
?>
```

Luego accede a: `https://tu-dominio.com/check-ext.php`

---

### 2. **Crear Tabla de Configuración SUNAT**

Ejecuta el script de migración:

```bash
php /storage/migrations/create_sunat_config_table.php
```

o manualmente en phpMyAdmin:

```sql
CREATE TABLE sunat_config (
    id INT AUTO_INCREMENT PRIMARY KEY,
    empresa_id INT NOT NULL UNIQUE,
    
    proveedor_activo VARCHAR(50) DEFAULT 'nubefact',
    entorno_prueba INT DEFAULT 1,
    
    nubefact_ruta VARCHAR(500) NULL,
    nubefact_token VARCHAR(500) NULL,
    
    sunat_usuario_sol VARCHAR(100) NULL,
    sunat_clave_sol VARCHAR(100) NULL,
    certificado_ruta VARCHAR(500) NULL,
    certificado_password VARCHAR(100) NULL,
    
    serie_boleta VARCHAR(4) DEFAULT 'B001',
    serie_factura VARCHAR(4) DEFAULT 'F001',
    serie_nota VARCHAR(4) DEFAULT 'N001',
    serie_nc_boleta VARCHAR(4) DEFAULT 'BC01',
    serie_nc_factura VARCHAR(4) DEFAULT 'FC01',
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    
    INDEX idx_empresa (empresa_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

INSERT INTO sunat_config (empresa_id) VALUES (1);
```

---

### 3. **Crear Directorios Necesarios**

```bash
mkdir -p /storage/sunat/certificados
mkdir -p /storage/sunat/xml
mkdir -p /storage/sunat/cdr
chmod 755 /storage/sunat/certificados
```

---

### 4. **Verificar .htaccess**

En `/public/.htaccess` debe estar:

```apache
<IfModule mod_rewrite.c>
    Options -Indexes
    RewriteEngine On
    RewriteBase /

    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d

    RewriteRule ^(.*)$ index.php?url=$1 [QSA,L]
</IfModule>
```

---

##  CONFIGURACIÓN SUNAT EN HOSTING

### Paso 1: Acceder a la Configuración

1. Inicia sesión como **Administrador** en el sistema
2. Ve a **Admin > Motor de Facturación**
3. Selecciona **Conexión SUNAT Nativa**

### Paso 2: Llenar Credenciales

**Campo: Usuario SOL**
```
[escribir así, SIN ESPACIOS]
Ejemplo: 20502035851username
         └─ RUC ─┘└─ Usuario ─┘
```

**Campo: Clave SOL**
```
Tu contraseña de acceso SOL en SUNAT
```

### Paso 3: Subir Certificado Digital

1. **Archivo**: Tu certificado `.pfx` o `.p12`
2. **Contraseña**: La contraseña del certificado
3. Haz clic en **Guardar y Aplicar Cambios**

### Paso 4: Cambiar a PRODUCCIÓN

 **MUY IMPORTANTE:**

1. En la sección "Entorno de Conexión", verás un **toggle**
2. Si está en **BETA** → Tus comprobantes son de prueba
3. Si está en **PRODUCCIÓN** → Tus comprobantes tienen validez fiscal
4. Cambia solo cuando hayas verificado que todo funciona en BETA

---

##  VERIFICAR CONEXIÓN

En la misma página de configuración, hay un botón **"Probar Conexión con SUNAT"**

Debe mostrar uno de estos mensajes:

###  CONEXIÓN EXITOSA
```
 ¡Conexión exitosa a SUNAT! Tu configuración es 
correcta y lista para emitir comprobantes.
```

###  ERRORES COMUNES Y SOLUCIONES

| Error | Causa | Solución |
|-------|-------|----------|
| Credenciales Inválidas (0109, 0110, 0111) | Usuario/Contraseña SOL incorrectos | Verifica en portal SUNAT |
| SUNAT rechazó la conexión | Certificado no vinculado a RUC | Vincula en portal SOL |
| Error de conexión de red | SUNAT no responde | Intenta más tarde |
| Certificado no se Lee | Contraseña incorrecta | Reingresa la contraseña |

---

##  EMITIR PRIMER COMPROBANTE

Una vez que pase la prueba de conexión:

1. Ve a **Ventas** → Nueva venta
2. Selecciona cliente, productos
3. En el tipo de comprobante, elige **Factura o Boleta**
4. El sistema **automáticamente**:
   - Genera el XML con certificado
   - Envía a SUNAT
   - Obtiene el CDR (Comprobante de Recepción)
   - Guarda en `/storage/sunat/`

---

##  DIAGNOSTICAR PROBLEMAS

### Ver Logs de Errores

En `/public/sunat/test-conexion.php` o ejecuta:

```bash
curl -X POST "https://tu-dominio.com/sunat/test-conexion-ajax"
```

### Verificar Estructura de Directorios

```bash
ls -la /storage/sunat/
# Debe mostrar:
# - certificados/
# - xml/
# - cdr/
```

### Revisar Permisos

```bash
chmod 755 /storage/sunat/certificados
chmod 755 /storage/sunat/xml
chmod 755 /storage/sunat/cdr
```

---

##  CHECKLIST FINAL ANTES DE PRODUCCIÓN

- [ ] PHP tiene `openssl` y `curl` habilitados
- [ ] Tabla `sunat_config` existe en BD
- [ ] Directorios `/storage/sunat/*` existen y tienen permisos 755
- [ ] Usuario SOL está en formato: **RUC(11) + Usuario** (ej: 20502035851username)
- [ ] Certificado .pfx está subido y su contraseña es correcta
- [ ] Prueba de conexión **PASA** sin errores
- [ ] Entorno está en **PRODUCCIÓN** (toggle activado)
- [ ] Primer comprobante se emitió exitosamente

---

##  SOPORTE

Si tienes problemas:

1. Verifica los **errores comunes** arriba
2. Revisa la **estructura de directorios**
3. Verifica que el **certificado sea válido** (no expirado)
4. Contacta a SUNAT si el error es de ellos (códigos de error)

---

**Última revisión:** 16 de Agosto de 2026