consultoria-as
61320b44d8
- API REST para gestion de facturas electronicas mexicanas (CFDI) - Laravel 9 con autenticacion OAuth 2.0 (Passport) - Integracion con Syntage, Clerk y Facturama - 30 modelos Eloquent, 39 controladores - Documentacion completa en /docs Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
593 lines
9.9 KiB
Markdown
593 lines
9.9 KiB
Markdown
# 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);
|
|
```
|