Initial commit: Horux Backend API
- 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>
This commit is contained in:
592
docs/API.md
Normal file
592
docs/API.md
Normal file
@@ -0,0 +1,592 @@
|
||||
# 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);
|
||||
```
|
||||
Reference in New Issue
Block a user