# Documentacion de API - Horux Backend

Esta documentacion describe todos los endpoints disponibles en la API de Horux.

## Base URL

```
Produccion: https://horuxfin.com/api
Desarrollo: http://localhost:8000/api
```

## Autenticacion

La API utiliza OAuth 2.0 mediante Laravel Passport. Todos los endpoints protegidos requieren un token Bearer en el header:

```
Authorization: Bearer {access_token}
```

---

## Endpoints Publicos

### POST /auth
Autenticacion mediante Clerk OAuth.

**Request Body:**
```json
{
  "code": "authorization_code_from_clerk"
}
```

**Response:**
```json
{
  "token_type": "Bearer",
  "expires_in": 31536000,
  "access_token": "eyJ0...",
  "refresh_token": "def50..."
}
```

---

### GET /retenciones
Obtener retenciones fiscales.

**Response:**
```json
{
  "data": [...]
}
```

---

### POST /invoice-endpoint
Endpoint para recibir facturas (rate limited).

**Middleware:** `throttle:custom-origin`

---

### GET /obtener-ingresos
Obtener ingresos desde Syntage API.

**Query Parameters:**
| Parametro | Tipo | Requerido | Descripcion |
|-----------|------|-----------|-------------|
| rfc | string | Si | RFC del contribuyente |
| year | integer | No | Ano fiscal |

---

### POST /obtener-egresos
Obtener egresos desde Syntage API.

**Request Body:**
```json
{
  "rfc": "RFC123456789",
  "year": 2024
}
```

---

### GET /ivaAFavor
Calcular IVA a favor.

**Query Parameters:**
| Parametro | Tipo | Requerido | Descripcion |
|-----------|------|-----------|-------------|
| rfc | string | Si | RFC del contribuyente |

---

### GET /utilidadBrutaVsIndustria
Comparar utilidad bruta vs industria.

---

### GET /risk
Consultar riesgos fiscales del contribuyente.

---

### POST /consultarmetrica
Consultar metricas almacenadas.

---

### POST /insertmetrica
Insertar nuevas metricas.

---

### POST /consultarcomparativo
Consultar comparativo mensual.

---

### POST /insertcomparativo
Insertar comparativo mensual.

---

### POST /usuariosat
Registrar usuario SAT.

---

## Endpoints Protegidos

Todos estos endpoints requieren autenticacion (`middleware: auth:api`).

---

## Gestion de RFCs

### POST /insertar-rfc
Asociar un RFC al usuario autenticado.

**Request Body:**
```json
{
  "rfc": "RFC123456789",
  "razon_social": "Empresa SA de CV"
}
```

**Response:**
```json
{
  "success": true,
  "message": "RFC insertado correctamente",
  "data": {
    "id": 1,
    "rfc": "RFC123456789",
    "razon_social": "Empresa SA de CV"
  }
}
```

---

### GET /obtener-rfcs
Obtener todos los RFCs asociados al usuario.

**Response:**
```json
{
  "data": [
    {
      "id": 1,
      "rfc": "RFC123456789",
      "razon_social": "Empresa SA de CV"
    }
  ]
}
```

---

## Catalogos Fiscales

### GET /tipos-factura
Obtener catalogo de tipos de factura.

**Response:**
```json
{
  "data": [
    {"id": 1, "code": "I", "name": "Ingreso"},
    {"id": 2, "code": "E", "name": "Egreso"},
    {"id": 3, "code": "T", "name": "Traslado"},
    {"id": 4, "code": "N", "name": "Nomina"},
    {"id": 5, "code": "P", "name": "Pago"}
  ]
}
```

---

### GET /uso-factura
Obtener catalogo de usos de factura (CFDI).

---

### GET /tipos-pago
Obtener catalogo de tipos de pago.

---

### GET /metodos-pago
Obtener catalogo de metodos de pago.

**Response:**
```json
{
  "data": [
    {"id": 1, "code": "PUE", "name": "Pago en una sola exhibicion"},
    {"id": 2, "code": "PPD", "name": "Pago en parcialidades o diferido"}
  ]
}
```

---

### GET /monedas
Obtener catalogo de monedas.

---

### GET /regimenes-fiscales
Obtener catalogo de regimenes fiscales.

---

### GET /codigos-prod-serv
Obtener catalogo de codigos de productos/servicios SAT.

---

### GET /codigos-unidad
Obtener catalogo de codigos de unidad SAT.

---

### GET /impuestos
Obtener catalogo de impuestos.

---

### GET /tasas-impuesto
Obtener catalogo de tasas de impuesto.

---

## Gestion de Facturas

### GET /obtener-facturas
Obtener todas las facturas del RFC.

**Query Parameters:**
| Parametro | Tipo | Requerido | Descripcion |
|-----------|------|-----------|-------------|
| rfc | string | Si | RFC del contribuyente |
| fecha_inicio | date | No | Fecha inicio (YYYY-MM-DD) |
| fecha_fin | date | No | Fecha fin (YYYY-MM-DD) |
| tipo | string | No | Tipo de factura (I, E, T, N, P) |

**Response:**
```json
{
  "data": [
    {
      "id": 1,
      "uuid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "serie": "A",
      "folio": "123",
      "fecha": "2024-01-15",
      "subtotal": 1000.00,
      "total": 1160.00,
      "emisor_rfc": "RFC123456789",
      "emisor_nombre": "Empresa Emisora",
      "receptor_rfc": "RFC987654321",
      "receptor_nombre": "Empresa Receptora",
      "tipo_comprobante": "I",
      "metodo_pago": "PUE"
    }
  ]
}
```

---

### GET /endpoint-facturas
Endpoint alternativo para obtener facturas.

---

### GET /facturas-emitidas
Obtener facturas emitidas por el RFC.

**Query Parameters:**
| Parametro | Tipo | Requerido | Descripcion |
|-----------|------|-----------|-------------|
| rfc | string | Si | RFC del emisor |
| year | integer | No | Ano fiscal |
| month | integer | No | Mes (1-12) |

---

### GET /facturas-emitidas-conciliadas
Obtener facturas emitidas ya conciliadas.

---

### GET /facturas-recibidas
Obtener facturas recibidas por el RFC.

---

### GET /facturas-recibidas-conciliadas
Obtener facturas recibidas ya conciliadas.

---

### POST /conciliar-facturas
Marcar facturas como conciliadas.

**Request Body:**
```json
{
  "invoice_ids": [1, 2, 3],
  "rfc": "RFC123456789"
}
```

---

### GET /descargar-factura
Descargar CFDI en formato XML.

**Query Parameters:**
| Parametro | Tipo | Requerido | Descripcion |
|-----------|------|-----------|-------------|
| uuid | string | Si | UUID de la factura |

**Response:** Archivo XML del CFDI.

---

## Complementos de Pago

### GET /obtener-complementos-pago
Obtener complementos de pago (facturas PPD).

**Query Parameters:**
| Parametro | Tipo | Requerido | Descripcion |
|-----------|------|-----------|-------------|
| rfc | string | Si | RFC del contribuyente |

---

## Contribuyentes

### GET /obtener-contribuyente
Obtener informacion del contribuyente desde Syntage.

**Query Parameters:**
| Parametro | Tipo | Requerido | Descripcion |
|-----------|------|-----------|-------------|
| rfc | string | Si | RFC a consultar |

**Response:**
```json
{
  "data": {
    "rfc": "RFC123456789",
    "razon_social": "Empresa SA de CV",
    "regimen_fiscal": "601",
    "actividades_economicas": [...],
    "riesgos": [...]
  }
}
```

---

## Lineas de Facturas

### GET /obtener-lineas-facturas
Obtener lineas/conceptos de facturas.

---

### GET /obtener-facturas-conceptos
Obtener facturas con sus conceptos.

---

## Calculos Financieros

### GET /ingreso-tipo-i
Calcular ingresos tipo I (facturas de ingreso).

---

### GET /gasto-tipo-i
Calcular gastos tipo I.

---

### GET /ingreso-tipo-e
Calcular ingresos tipo E (notas de credito).

---

### GET /gasto-tipo-e
Calcular gastos tipo E.

---

### GET /gasto-tipo-n
Calcular gastos tipo N (nomina).

---

### GET /ingreso-ppd
Calcular ingresos PPD (pagos en parcialidades).

---

### GET /gasto-ppd
Calcular gastos PPD.

---

### GET /adquisicion-pue
Calcular adquisiciones PUE.

---

### GET /adquisicion-ppd
Calcular adquisiciones PPD.

---

## Metricas

### GET /obtener-metricas
Obtener metricas globales del RFC.

**Query Parameters:**
| Parametro | Tipo | Requerido | Descripcion |
|-----------|------|-----------|-------------|
| rfc | string | Si | RFC del contribuyente |
| year | integer | No | Ano fiscal |

**Response:**
```json
{
  "data": {
    "ingresos_totales": 1000000.00,
    "egresos_totales": 600000.00,
    "iva_trasladado": 160000.00,
    "iva_acreditable": 96000.00,
    "iva_a_favor": 64000.00,
    "isr_retenido": 50000.00
  }
}
```

---

### GET /obtener-metricas-mensuales
Obtener metricas desglosadas por mes.

---

## Importacion Masiva

### POST /importar-facturas
Importar facturas desde archivo Excel.

**Request:**
- Content-Type: `multipart/form-data`
- Campo: `file` (archivo .xlsx o .xls)

**Response:**
```json
{
  "success": true,
  "message": "Se importaron 150 facturas correctamente",
  "imported": 150,
  "errors": 0
}
```

---

### POST /importar-lineas-facturas
Importar lineas de facturas desde Excel.

---

### POST /importar-codigos-prod-serv
Importar catalogo de codigos de productos/servicios.

---

### POST /importar-codigos-unidad
Importar catalogo de codigos de unidad.

---

## Codigos de Error

| Codigo | Descripcion |
|--------|-------------|
| 200 | Exito |
| 201 | Recurso creado |
| 400 | Solicitud invalida |
| 401 | No autenticado |
| 403 | No autorizado |
| 404 | Recurso no encontrado |
| 422 | Error de validacion |
| 429 | Demasiadas solicitudes (rate limit) |
| 500 | Error interno del servidor |

---

## Rate Limiting

Algunos endpoints tienen rate limiting configurado:
- `/invoice-endpoint`: Limitado por origen (middleware `throttle:custom-origin`)

---

## Ejemplos de Uso

### Autenticacion con cURL

```bash
# 1. Obtener token
curl -X POST https://horuxfin.com/api/auth \
  -H "Content-Type: application/json" \
  -d '{"code": "clerk_authorization_code"}'

# 2. Usar token en peticiones
curl -X GET https://horuxfin.com/api/obtener-rfcs \
  -H "Authorization: Bearer {access_token}"
```

### Obtener facturas con JavaScript

```javascript
const response = await fetch('https://horuxfin.com/api/obtener-facturas?rfc=RFC123456789', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);
```

### Importar facturas con PHP

```php
$client = new GuzzleHttp\Client();

$response = $client->post('https://horuxfin.com/api/importar-facturas', [
    'headers' => [
        'Authorization' => 'Bearer ' . $accessToken,
    ],
    'multipart' => [
        [
            'name' => 'file',
            'contents' => fopen('/path/to/facturas.xlsx', 'r'),
            'filename' => 'facturas.xlsx'
        ]
    ]
]);

$result = json_decode($response->getBody(), true);
```