# ❓ PREGUNTAS FRECUENTES (FAQ)

## 📡 API y Conexión

### ¿Cuál es el endpoint de la API?
```
POST: https://datosrut.codepyme.com/procesar
```

### ¿Cuánto tiempo tarda procesar un RUT?
Entre 10-30 segundos dependiendo del tamaño del PDF y la complejidad.

### ¿Hay límite de solicitudes?
No hay límite de solicitudes actualmente.

### ¿Qué pasa si la solicitud tarda mucho?
Configura timeout de al menos 120 segundos (2 minutos).

```python
# Python
response = requests.post(url, files=files, timeout=120)

# JavaScript
fetch(url, {signal: AbortSignal.timeout(120000)})

# Node.js
axios.post(url, {timeout: 120000})
```

### ¿Es segura la información?
Sí, los archivos se procesan y eliminan inmediatamente. No se almacenan.

---

## 📁 Archivos y Formatos

### ¿Qué formatos soporta?
Solo PDF. Asegúrate que sea un PDF válido, no una imagen en formato PDF.

### ¿Cuál es el tamaño máximo?
10 MB por archivo.

### ¿Puedo enviar archivos por lotes?
Sí, pero debes procesar uno a uno con esperas de 1-2 segundos entre solicitudes.

### ¿Qué pasa si el PDF no es válido?
Recibirás un error indicando el problema. El archivo debe ser un PDF real con texto extraíble.

### ¿Puedo subir PDFs escaneados?
Depende. Si el PDF tiene texto extraíble, sí. Si es solo imagen, necesitaría OCR (no soportado actualmente).

---

## 📊 Datos Extraídos

### ¿Qué datos se extraen?
- Identificación (NIT, DV, tipo de documento)
- Datos jurídicos (razón social, nombre comercial)
- Ubicación (país, departamento, ciudad, dirección, teléfono, email)
- Actividad económica (códigos, descripciones, fechas)
- Responsabilidades (códigos DIAN)
- Representante legal (nombre, documento, cargo)
- Revisor fiscal (nombre, documento)
- Contador (nombre, documento)
- Socios (nombre, documento, participación)
- Establecimientos

### ¿Por qué algunos campos están vacíos (null)?
Porque el RUT no tiene esa información o no está visible en el PDF.

### ¿Cómo manejo los campos nulos?
Verifica antes de usar:

```python
# Python
nit = datos.get('identificacion', {}).get('nit')
if nit:
    print(nit)
else:
    print("NIT no disponible")

# JavaScript
const nit = datos?.identificacion?.nit || 'No disponible';
```

### ¿Puedo confiar en que todos los datos estén?
Sí, siempre que el PDF sea válido. Nuestro sistema busca en TODAS las páginas.

---

## 🐛 Problemas Comunes

### Error: "CORS Error"
**Síntoma:** En JavaScript obtienes error de CORS  
**Causa:** Navegador bloquea solicitud de diferentes dominios  
**Solución:**
- Opción 1: Usa un backend (Node.js, Python) como proxy
- Opción 2: El servidor debe tener CORS habilitado (ya lo está)
- Opción 3: Usa cliente HTML que está en el mismo dominio

### Error: "Timeout"
**Síntoma:** La solicitud nunca completa  
**Causa:** El servidor tardó más de lo esperado o conexión lenta  
**Solución:**
```python
# Aumenta timeout
response = requests.post(url, files=files, timeout=180)  # 3 minutos
```

### Error: "PDF no válido"
**Síntoma:** La API rechaza el archivo  
**Causa:** El PDF es corrupto o no tiene texto extraíble  
**Solución:**
- Abre el PDF en tu lector y verifica que se vea bien
- Intenta guardar el PDF nuevamente
- Si es imagen escaneada, necesitaría OCR

### Error: "JSON inválido"
**Síntoma:** No puedo parsear la respuesta  
**Causa:** La respuesta no es JSON válido  
**Solución:**
```javascript
try {
    const data = JSON.parse(response);
} catch (e) {
    console.log('Respuesta raw:', response);
}
```

### Error: "Módulo no encontrado"
**Síntoma:** `ModuleNotFoundError` en Python o `npm ERR!` en Node  
**Causa:** Falta instalar dependencias  
**Solución:**
```bash
# Python
pip install requests

# Node.js
npm install express multer axios form-data
```

### Mi cliente recibe datos incompletos
**Síntoma:** Faltan campos del RUT  
**Causa:** Posiblemente PDF no tiene toda la información legible  
**Solución:**
- Verifica que sea el PDF correcto
- Verifica que tenga todas las páginas
- Intenta procesar manualmente para comparar

---

## 🔄 Integración

### ¿Debo procesar todos de una vez?
No, hazlo de uno en uno con esperas:

```python
for rut_file in rut_files:
    datos = extraer_rut(rut_file)
    # Procesar datos
    time.sleep(1)  # Esperar 1 segundo
```

### ¿Cómo integro en mi base de datos?
Después de extraer, guarda los datos:

```python
import sqlite3

# Guardar
db = sqlite3.connect('ruts.db')
db.execute('''
    INSERT INTO ruts (nit, razon_social, email)
    VALUES (?, ?, ?)
''', (
    datos['identificacion']['nit'],
    datos['datos_juridicos']['razon_social'],
    datos['ubicacion']['correo_electronico']
))
db.commit()
```

### ¿Puedo guardar archivos localmente?
Sí:

```python
import json

# Guardar resultado en archivo
with open('resultado.json', 'w') as f:
    json.dump(datos, f, indent=2)
```

---

## 🚀 Rendimiento

### ¿Cuántos RUTs puedo procesar por hora?
Teóricamente ilimitado, pero respeta:
- 1-2 segundos entre solicitudes
- Máximo 120 segundos de timeout por solicitud

```
Estimado: 1 RUT cada 30 segundos = 120 por hora
```

### ¿Es muy lenta para mi caso de uso?
- Si necesitas < 30 segundos por RUT: Contacta para soluciones premium
- Si está bien > 30 segundos: Usa el sistema actual
- Si necesitas procesamiento batch: Implementa cola de procesos

### ¿Puedo paralelizar solicitudes?
Con cuidado. Máximo 5-10 en paralelo:

```python
import asyncio

async def procesar_multiples():
    tasks = []
    for rut in ruts[:10]:  # Máximo 10 en paralelo
        tasks.append(extraer_rut(rut))
    
    resultados = await asyncio.gather(*tasks)
    return resultados
```

---

## 🔐 Seguridad

### ¿Son seguros mis datos?
Sí:
- Solo se envía el PDF a nuestra API
- Los datos se procesan inmediatamente
- No se almacenan en nuestro servidor
- Conexión HTTPS encriptada

### ¿Quién puede ver mis datos?
Nadie, excepto tú:
- Los datos se procesan en memoria
- Se devuelven directamente al cliente
- No quedan logs con información personal

### ¿Debo autenticar mis solicitudes?
No actualmente, pero puedes:
- Usar Node.js como proxy con validación
- Agregar API Key en headers
- Proteger el endpoint con contraseña

---

## 💻 Lenguajes Soportados

### ¿Soportan todos los lenguajes?
Cualquier lenguaje que pueda hacer HTTP POST multipart:
- ✅ Python
- ✅ JavaScript
- ✅ Node.js
- ✅ Java
- ✅ C#
- ✅ Go
- ✅ Ruby
- ✅ PHP
- ✅ Cualquier otro

### ¿Hay SDKs oficiales?
No actualmente, pero el API es simple de usar.

### ¿Puedo contribuir un cliente?
Sí, contacta al equipo!

---

## 🎯 Casos de Uso

### Caso: Procesar masivamente RUTs de un archivo CSV
```python
import csv

with open('ruts.csv') as f:
    reader = csv.DictReader(f)
    for row in reader:
        datos = extraer_rut(row['archivo_pdf'])
        # Procesar y guardar
```

### Caso: API REST para que mis clientes suban RUTs
```javascript
// Node.js Express
app.post('/api/ruts', upload.single('file'), async (req, res) => {
    const datos = await extraerRUT(req.file.path);
    res.json(datos);
});
```

### Caso: Integración con sistema de facturación
```python
# Extraer datos del RUT
datos = extraer_rut('rut.pdf')

# Crear cliente en tu sistema
cliente = {
    'nit': datos['identificacion']['nit'],
    'nombre': datos['datos_juridicos']['razon_social'],
    'email': datos['ubicacion']['correo_electronico'],
    'telefono': datos['ubicacion']['telefono_1'],
    'direccion': datos['ubicacion']['direccion_principal']
}

# Guardar en tu base de datos
crear_cliente(cliente)
```

---

## ❌ Lo que NO funciona

- ❌ Documentos que no sean RUTs
- ❌ PDFs solo en imagen (sin texto)
- ❌ Archivos corrompidos
- ❌ Documentos sin información extraíble
- ❌ Más de 10 MB
- ❌ Solicitudes simultáneas masivas (>50 paralelas)

---

## 📞 Contacto

Si tu pregunta no está aquí:
1. Consulta README_CLIENTE.md
2. Revisa INTEGRACION_RAPIDA.md
3. Contacta al equipo de desarrollo

---

## 🔄 Feedback

¿Encontraste un problema o tienes sugerencia?

Avísale al equipo:
- Describe el problema claramente
- Incluye el código que usaste
- Incluye mensaje de error exacto
- Incluye tu caso de uso

---

**¡Espero haberte ayudado! Si necesitas más, consulta la documentación principal.** 📚