# 📚 Documentación de API - Sistema Contable Tracert

## 🎯 Descripción General

Esta API permite a sistemas externos (POS, ERP, SET) enviar datos al sistema contable de forma automática, con logging completo y auditoría de todas las operaciones.

## 🔐 Autenticación

### API Key
```http
X-API-Key: your_api_key_here
```

### Bearer Token
```http
Authorization: Bearer your_jwt_token_here
```

### API Keys Válidas
- `tracert_system_key_2024` - Sistema interno Tracert
- `external_pos_key` - Sistemas POS externos
- `external_erp_key` - Sistemas ERP externos
- `set_sync_key_2024` - Sincronización con SET
- `monitoring_key_2024` - Sistema de monitoreo

## 📡 Endpoints Principales

### 1. Autenticación

#### Login
```http
POST /api/v1/auth/login
Content-Type: application/json

{
    "username": "usuario",
    "password": "contraseña"
}
```

**Respuesta:**
```json
{
    "success": true,
    "data": {
        "token": "jwt_token_here",
        "user": {
            "id": 1,
            "username": "usuario",
            "email": "usuario@empresa.com",
            "rol": "CONTADOR",
            "empresa": {
                "id": 1,
                "nombre": "Empresa S.A.",
                "ruc": "12345678-9"
            }
        },
        "expires_in": 3600,
        "token_type": "Bearer"
    }
}
```

### 2. Gestión de Empresas

#### Listar Empresas
```http
GET /api/v1/companies
Authorization: Bearer your_token
```

#### Crear Empresa
```http
POST /api/v1/companies
Authorization: Bearer your_token
Content-Type: application/json

{
    "nombre": "Nueva Empresa S.A.",
    "ruc": "87654321-0",
    "direccion": "Av. Principal 123",
    "telefono": "+595 981 123 456",
    "email": "contacto@nuevaempresa.com"
}
```

#### Actualizar Empresa
```http
PUT /api/v1/companies/1
Authorization: Bearer your_token
Content-Type: application/json

{
    "nombre": "Empresa Actualizada S.A.",
    "direccion": "Nueva Dirección 456"
}
```

#### Eliminar Empresa
```http
DELETE /api/v1/companies/1
Authorization: Bearer your_token
```

### 3. Recibir Comprobantes (Sistemas Externos)

#### Enviar Comprobante
```http
POST /api/v1/external/comprobantes
X-API-Key: external_pos_key
Content-Type: application/json

{
    "tipo_comprobante": "FACTURA",
    "numero_comprobante": "001-001-00000001",
    "fecha_emision": "2024-01-15",
    "empresa_ruc": "12345678-9",
    "total_importe": 110000,
    "subtotal": 100000,
    "iva": 10000,
    "cliente_proveedor": "Cliente Test",
    "ruc_cliente_proveedor": "87654321-0",
    "observaciones": "Venta de productos",
    "lineas": [
        {
            "descripcion": "Producto A",
            "cantidad": 2,
            "precio_unitario": 50000,
            "subtotal": 100000,
            "iva_porcentaje": 10,
            "iva_monto": 10000,
            "total_linea": 110000
        }
    ]
}
```

**Respuesta:**
```json
{
    "success": true,
    "data": {
        "comprobante_id": 123,
        "numero_comprobante": "001-001-00000001",
        "fecha_procesamiento": "2024-01-15 10:30:00",
        "estado": "procesado"
    },
    "message": "Comprobante recibido y procesado exitosamente"
}
```

### 4. Sincronización con SET

#### Sincronizar Comprobantes
```http
POST /api/v1/external/set-sync
X-API-Key: set_sync_key_2024
Content-Type: application/json

{
    "sync_type": "comprobantes",
    "comprobantes": [
        {
            "numero": "001-001-00000001",
            "tipo": "FACTURA",
            "fecha_emision": "2024-01-15",
            "empresa_ruc": "12345678-9",
            "total_importe": 110000,
            "subtotal": 100000,
            "iva": 10000,
            "timbre_fiscal": 1000,
            "estado": "ACTIVO"
        }
    ]
}
```

#### Sincronizar Declaraciones
```http
POST /api/v1/external/set-sync
X-API-Key: set_sync_key_2024
Content-Type: application/json

{
    "sync_type": "declaraciones",
    "declaraciones": [
        {
            "tipo": "IVA",
            "periodo": "2024-01",
            "empresa_ruc": "12345678-9",
            "fecha_vencimiento": "2024-02-15",
            "monto_declarado": 10000,
            "monto_pagado": 10000,
            "estado": "PAGADO"
        }
    ]
}
```

### 5. Datos de POS/ERP

#### Enviar Ventas
```http
POST /api/v1/external/pos-erp
X-API-Key: external_pos_key
Content-Type: application/json

{
    "data_type": "ventas",
    "ventas": [
        {
            "numero_factura": "V-001-00000001",
            "fecha_venta": "2024-01-15",
            "empresa_ruc": "12345678-9",
            "cliente_nombre": "Cliente Test",
            "cliente_ruc": "87654321-0",
            "subtotal": 100000,
            "iva": 10000,
            "descuento": 0,
            "total": 110000,
            "metodo_pago": "EFECTIVO",
            "estado": "ACTIVO"
        }
    ]
}
```

#### Enviar Compras
```http
POST /api/v1/external/pos-erp
X-API-Key: external_erp_key
Content-Type: application/json

{
    "data_type": "compras",
    "compras": [
        {
            "numero_factura": "C-001-00000001",
            "fecha_compra": "2024-01-15",
            "empresa_ruc": "12345678-9",
            "proveedor_nombre": "Proveedor Test",
            "proveedor_ruc": "11223344-5",
            "subtotal": 50000,
            "iva": 5000,
            "descuento": 0,
            "total": 55000,
            "metodo_pago": "TRANSFERENCIA",
            "estado": "ACTIVO"
        }
    ]
}
```

#### Enviar Inventario
```http
POST /api/v1/external/pos-erp
X-API-Key: external_pos_key
Content-Type: application/json

{
    "data_type": "inventario",
    "inventario": [
        {
            "codigo_producto": "PROD-001",
            "nombre_producto": "Producto Test",
            "descripcion": "Descripción del producto",
            "categoria": "CATEGORIA_A",
            "precio_compra": 50000,
            "precio_venta": 55000,
            "stock_actual": 100,
            "stock_minimo": 10,
            "unidad_medida": "UNIDAD",
            "estado": "ACTIVO",
            "empresa_ruc": "12345678-9"
        }
    ]
}
```

### 6. Protección de Datos

#### Obtener Políticas
```http
GET /api/v1/data-protection
Authorization: Bearer your_token
```

#### Registrar Consentimiento
```http
POST /api/v1/data-protection/consent
Authorization: Bearer your_token
Content-Type: application/json

{
    "consent_type": "data_processing",
    "consent_given": true,
    "data_categories": ["personal_data", "financial_data"]
}
```

#### Encriptar Datos
```http
POST /api/v1/data-protection/encrypt
Authorization: Bearer your_token
Content-Type: application/json

{
    "data": "datos_sensibles_aqui"
}
```

### 7. Monitoreo y Auditoría

#### Obtener Estadísticas
```http
GET /api/v1/monitoring/api-monitor?timeframe=24h
X-API-Key: monitoring_key_2024
```

#### Resolver Problema
```http
POST /api/v1/monitoring/api-monitor
X-API-Key: monitoring_key_2024
Content-Type: application/json

{
    "action": "resolve_problem",
    "problem_id": 123,
    "resolution_notes": "Problema resuelto manualmente"
}
```

#### Limpiar Logs
```http
POST /api/v1/monitoring/api-monitor
X-API-Key: monitoring_key_2024
Content-Type: application/json

{
    "action": "clean_logs",
    "days_to_keep": 30
}
```

## 📊 Códigos de Respuesta

### Éxito
- `200` - OK
- `201` - Creado exitosamente

### Errores del Cliente
- `400` - Bad Request (datos inválidos)
- `401` - Unauthorized (autenticación requerida)
- `403` - Forbidden (sin permisos)
- `404` - Not Found (recurso no encontrado)
- `409` - Conflict (recurso ya existe)
- `422` - Unprocessable Entity (validación fallida)

### Errores del Servidor
- `500` - Internal Server Error
- `502` - Bad Gateway
- `503` - Service Unavailable

## 🔍 Logging y Auditoría

### Tipos de Logs
1. **Conexiones API** - Todas las llamadas a la API
2. **Errores** - Errores y excepciones
3. **Operaciones** - Operaciones exitosas
4. **Problemas de Conexión** - Fallos de conectividad
5. **Métricas de Rendimiento** - Tiempos de respuesta

### Niveles de Severidad
- `DEBUG` (1) - Información de debugging
- `INFO` (2) - Información general
- `WARNING` (3) - Advertencias
- `ERROR` (4) - Errores
- `CRITICAL` (5) - Errores críticos

## 🚨 Alertas del Sistema

### Tipos de Alertas
- `HIGH_ERROR_RATE` - Alta tasa de errores
- `HIGH_RESPONSE_TIME` - Tiempo de respuesta alto
- `UNRESOLVED_PROBLEMS` - Problemas sin resolver
- `CONNECTION_FAILED` - Fallos de conexión

### Configuración de Alertas
- Tiempo máximo de respuesta: 5000ms
- Umbral de tasa de errores: 10%
- Retención de logs: 30 días
- Email de alertas: admin@tracertsystem.net

## 📈 Métricas de Salud

### Indicadores
- **Uptime**: Porcentaje de disponibilidad
- **Health Score**: Puntuación de salud (0-100)
- **Tiempo de Respuesta**: Promedio y máximo
- **Tasa de Errores**: Porcentaje de errores
- **Conexiones Únicas**: IPs y sistemas únicos

## 🔧 Configuración

### Variables de Entorno
```bash
API_BASE_URL=https://gestion.tracertsystem.net/contabilidad/api/v1
API_TIMEOUT=30
LOG_LEVEL=INFO
MONITORING_ENABLED=true
```

### Configuración de Base de Datos
```php
DB_HOST=192.168.0.151
DB_NAME=contabilidad_paraguay
DB_USER=dev
DB_PASS=Paraguay2024!.Py
```

## 📝 Ejemplos de Uso

### Python
```python
import requests
import json

# Configuración
api_url = "https://gestion.tracertsystem.net/contabilidad/api/v1"
api_key = "external_pos_key"

# Enviar comprobante
comprobante = {
    "tipo_comprobante": "FACTURA",
    "numero_comprobante": "001-001-00000001",
    "fecha_emision": "2024-01-15",
    "empresa_ruc": "12345678-9",
    "total_importe": 110000,
    "subtotal": 100000,
    "iva": 10000
}

headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

response = requests.post(
    f"{api_url}/external/comprobantes",
    headers=headers,
    json=comprobante
)

print(response.json())
```

### JavaScript
```javascript
const apiUrl = 'https://gestion.tracertsystem.net/contabilidad/api/v1';
const apiKey = 'external_pos_key';

// Enviar venta
const venta = {
    data_type: 'ventas',
    ventas: [{
        numero_factura: 'V-001-00000001',
        fecha_venta: '2024-01-15',
        empresa_ruc: '12345678-9',
        total: 110000
    }]
};

fetch(`${apiUrl}/external/pos-erp`, {
    method: 'POST',
    headers: {
        'X-API-Key': apiKey,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(venta)
})
.then(response => response.json())
.then(data => console.log(data));
```

### PHP
```php
<?php
$apiUrl = 'https://gestion.tracertsystem.net/contabilidad/api/v1';
$apiKey = 'external_erp_key';

$comprobante = [
    'tipo_comprobante' => 'FACTURA',
    'numero_comprobante' => '001-001-00000001',
    'fecha_emision' => '2024-01-15',
    'empresa_ruc' => '12345678-9',
    'total_importe' => 110000
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $apiUrl . '/external/comprobantes');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($comprobante));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ' . $apiKey,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>
```

## 🛡️ Seguridad

### Protección de Datos
- Encriptación AES-256 para datos sensibles
- Logs de auditoría completos
- Control de acceso basado en roles
- Validación de entrada estricta

### Mejores Prácticas
- Usar HTTPS siempre
- Validar todos los datos de entrada
- Implementar rate limiting
- Monitorear logs regularmente
- Mantener API keys seguras

## 📞 Soporte

Para soporte técnico:
- Email: admin@tracertsystem.net
- Teléfono: +595 972 258 258
- Horario: Lunes a Viernes 8:00 - 18:00

## 🔄 Actualizaciones

### Versión 1.0
- APIs básicas de autenticación
- Recepción de comprobantes
- Sincronización con SET
- Sistema de logging completo
- Monitoreo y alertas

---

**Sistema Contable Tracert - API v1.0**  
*Desarrollado para integración con sistemas externos*