consultoria-as/Horux_back
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Horux_back/docs/API.md
consultoria-as 61320b44d8 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>
2026-01-18 07:44:29 +00:00

9.9 KiB
Raw Permalink Blame History

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:

{
  "code": "authorization_code_from_clerk"
}

Response:

{
  "token_type": "Bearer",
  "expires_in": 31536000,
  "access_token": "eyJ0...",
  "refresh_token": "def50..."
}

GET /retenciones

Obtener retenciones fiscales.

Response:

{
  "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:

{
  "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:

{
  "rfc": "RFC123456789",
  "razon_social": "Empresa SA de CV"
}

Response:

{
  "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:

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

Catalogos Fiscales

GET /tipos-factura

Obtener catalogo de tipos de factura.

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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

# 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

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

$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 View Git Blame Copy Permalink