Reportes y Análisis

Pruebas
Producción

Dominio: https://test-api-factura.edw-dev.com

La API de reportes permite generar análisis detallados de las operaciones del sistema, incluyendo reportes de pagos, ventas y exportación de documentos emitidos.

Endpoints Disponibles

1. Reporte de Pagos

Endpoint: GET /api/v1/reports/payments

Descripción: Genera un reporte consolidado de pagos agrupados por método de pago, tipos de documentos y análisis de impuestos.

Headers Requeridos

Accept: application/json
Authorization: Bearer {token}

Parámetros de Consulta (Opcionales)

Parámetro	Tipo	Descripción	Ejemplo
`filters`	string	Filtros en formato JSON	`{"payment_date":[{"eq":"2024-01-15"}]}`

Filtros Disponibles

Campo	Tipo	Descripción	Operadores
`payment_date`	date	Fecha de pago	`eq`, `ge`, `le`, `gt`, `lt`
`document_type`	string	Tipo de documento	`eq`, `in`
`payment_method`	string	Método de pago	`eq`, `in`
`client_id`	integer	ID del cliente	`eq`
`amount`	number	Monto del pago	`eq`, `ge`, `le`, `gt`, `lt`

Ejemplos de Implementación

curl -X GET "https://dev-facturacion.e-dinky.test/api/v1/reports/payments?filters={\"payment_date\":[{\"eq\":\"2024-01-15\"}]}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your_token_here"

use Illuminate\Support\Facades\Http;

class ReportController extends Controller
{
    public function getPaymentsReport(Request $request)
    {
        $filters = [];

        if ($request->payment_date) {
            $filters['payment_date'] = [['eq' => $request->payment_date]];
        }

        if ($request->document_type) {
            $filters['document_type'] = [['eq' => $request->document_type]];
        }

        if ($request->payment_method) {
            $filters['payment_method'] = [['eq' => $request->payment_method]];
        }

        $response = Http::withHeaders([
            'Authorization' => 'Bearer ' . $this->getToken(),
            'Accept' => 'application/json'
        ])->get('https://dev-facturacion.e-dinky.test/api/v1/reports/payments', [
            'filters' => json_encode($filters)
        ]);

        if ($response->successful()) {
            return $response->json();
        }

        return response()->json(['error' => 'Error al obtener reporte'], 400);
    }
}

const axios = require('axios');

async function getPaymentsReport(filters, token) {
    try {
        const params = new URLSearchParams();
        if (Object.keys(filters).length > 0) {
            params.append('filters', JSON.stringify(filters));
        }

        const response = await axios.get(
            `https://dev-facturacion.e-dinky.test/api/v1/reports/payments?${params.toString()}`,
            {
                headers: {
                    'Authorization': `Bearer ${token}`,
                    'Accept': 'application/json'
                }
            }
        );

        return response.data;
    } catch (error) {
        console.error('Error al obtener reporte de pagos:', error.response?.data);
        throw error;
    }
}

// Ejemplo de uso
const filters = {
    payment_date: [{ eq: '2024-01-15' }],
    document_type: [{ eq: 'invoice' }]
};

getPaymentsReport(filters, 'your_token_here')
    .then(data => console.log(data))
    .catch(error => console.error(error));

Respuesta Exitosa (200 OK)

{
  "message": "Pagos",
  "status": "OK",
  "payload": {
    "payment": [
      {
        "amount": 10,
        "code": "01",
        "title": "SIN UTILIZACIÓN DEL SISTEMA FINANCIERO",
        "short_name": "Efectivo",
        "icon": "<i class=\"fas fa-money-bill\"></i>"
      },
      {
        "amount": 28.36,
        "code": "19",
        "title": "TARJETA DE CRÉDITO",
        "short_name": "Tarjeta/Crédito",
        "icon": "<i class=\"fas fa-credit-card\"></i>"
      },
      {
        "amount": 3.8,
        "code": "15",
        "title": "COMPENSACIÓN DE DEUDAS",
        "short_name": "Comp. Deudas",
        "icon": "<i class=\"fas fa-money-check\"></i>"
      }
    ],
    "sales": [
      {
        "title": "Factura",
        "type": "invoice",
        "code": "01",
        "subtotal": 36.66,
        "discount": 0,
        "taxes_amount": 5.50,
        "total": 42.16
      },
      {
        "title": "Nota de débito",
        "type": "debit_note",
        "code": "05",
        "subtotal": 0,
        "discount": 0,
        "taxes_amount": 0,
        "total": 0
      }
    ],
    "taxes": [
      {
        "taxCode": 2,
        "payments": 42.16,
        "taxes": 5.5,
        "subtotal": 36.66,
        "typeTaxTitle": "IVA",
        "taxTitle": "15%",
        "items": [
          {
            "taxCodeSri": "4",
            "subtotal": "36.66",
            "taxes": "5.50",
            "payments": "42.16"
          }
        ]
      }
    ]
  }
}

2. Exportar Documentos Emitidos

Endpoint: GET /api/v1/reports/documents/export

Descripción: Exporta un reporte detallado de todos los documentos emitidos en un rango de fechas específico en formato Excel.

Headers Requeridos

Accept: application/json
Authorization: Bearer {token}

Parámetros de Consulta (Requeridos)

Parámetro	Tipo	Descripción	Ejemplo
`filters`	string	Filtros en formato JSON con rango de fechas	`{"date":[{"ge":"2024-01-01"},{"le":"2024-01-31"}]}`

Filtros Disponibles

Campo	Tipo	Descripción	Operadores	Requerido
`date`	date	Fecha de emisión del documento	`ge`, `le`	Sí
`document_type`	string	Tipo de documento	`eq`, `in`	No
`client_id`	integer	ID del cliente	`eq`	No
`status`	string	Estado del documento	`eq`, `in`	No

Restricciones

Rango máximo: 31 días entre fecha de inicio y fin
Fechas válidas: La fecha de inicio debe ser menor o igual a la fecha de fin
Formato de fecha: YYYY-MM-DD

Ejemplos de Implementación

Reporte mensual:

curl -X GET "https://dev-facturacion.e-dinky.test/api/v1/reports/documents/export?filters={\"date\":[{\"ge\":\"2024-01-01\"},{\"le\":\"2024-01-31\"}]}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your_token_here" \
  --output documentos_enero_2024.xlsx

Reporte con filtro por tipo de documento:

curl -X GET "https://dev-facturacion.e-dinky.test/api/v1/reports/documents/export?filters={\"date\":[{\"ge\":\"2024-01-01\"},{\"le\":\"2024-01-31\"}],\"document_type\":[{\"eq\":\"invoice\"}]}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your_token_here" \
  --output facturas_enero_2024.xlsx

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Storage;

class ReportController extends Controller
{
    public function exportDocuments(Request $request)
    {
        $filters = [
            'date' => [
                ['ge' => $request->date_from],
                ['le' => $request->date_to]
            ]
        ];

        if ($request->document_type) {
            $filters['document_type'] = [['eq' => $request->document_type]];
        }

        if ($request->client_id) {
            $filters['client_id'] = [['eq' => $request->client_id]];
        }

        $response = Http::withHeaders([
            'Authorization' => 'Bearer ' . $this->getToken(),
            'Accept' => 'application/json'
        ])->get('https://dev-facturacion.e-dinky.test/api/v1/reports/documents/export', [
            'filters' => json_encode($filters)
        ]);

        if ($response->successful()) {
            $filename = 'documentos_' . date('Y-m-d') . '.xlsx';
            Storage::put($filename, $response->body());
            return response()->download(storage_path("app/{$filename}"));
        }

        return response()->json(['error' => 'Error al exportar reporte'], 400);
    }
}

const axios = require('axios');
const fs = require('fs');

async function exportDocumentsReport(dateFrom, dateTo, options = {}, token) {
    try {
        const filters = {
            date: [
                { ge: dateFrom },
                { le: dateTo }
            ]
        };

        if (options.documentType) {
            filters.document_type = [{ eq: options.documentType }];
        }

        if (options.clientId) {
            filters.client_id = [{ eq: options.clientId }];
        }

        const response = await axios.get(
            'https://dev-facturacion.e-dinky.test/api/v1/reports/documents/export',
            {
                params: {
                    filters: JSON.stringify(filters)
                },
                headers: {
                    'Authorization': `Bearer ${token}`,
                    'Accept': 'application/json'
                },
                responseType: 'stream'
            }
        );

        const filename = `documentos_${new Date().toISOString().split('T')[0]}.xlsx`;
        const writer = fs.createWriteStream(filename);
        response.data.pipe(writer);

        return new Promise((resolve, reject) => {
            writer.on('finish', () => resolve(filename));
            writer.on('error', reject);
        });
    } catch (error) {
        console.error('Error al exportar reporte de documentos:', error.response?.data);
        throw error;
    }
}

#### Respuesta Exitosa (200 OK)

La respuesta será un archivo Excel (.xlsx) con los siguientes datos:

- **Información del documento:** Número, fecha, tipo, estado
- **Datos del cliente:** Identificación, nombre, email
- **Detalles financieros:** Subtotal, impuestos, descuentos, total
- **Items:** Descripción, cantidad, precio unitario, total
- **Información de pagos:** Métodos de pago utilizados

#### Respuestas de Error

**422 - Rango de fechas excede 31 días:**
```json
{
  "message": "La diferencia de días no puede ser mayor a 31 días",
  "status": "ERROR",
  "payload": null,
  "error": "La diferencia de días no puede ser mayor a 31 días"
}

422 - Fechas inválidas:

{
  "message": "Fechas inválidas para para exportar el reporte",
  "status": "ERROR",
  "payload": null,
  "error": "Fechas inválidas para para exportar el reporte"
}

Estructura de Respuestas

Reporte de Pagos

La respuesta del reporte de pagos contiene tres secciones principales:

1. Pagos por Método (`payment`)

Campo	Tipo	Descripción
`amount`	number	Monto total recaudado por este método
`code`	string	Código SRI del método de pago
`title`	string	Nombre completo del método de pago
`short_name`	string	Nombre corto para visualización
`icon`	string	Icono HTML para la interfaz

2. Ventas por Tipo de Documento (`sales`)

Campo	Tipo	Descripción
`title`	string	Nombre del tipo de documento
`type`	string	Tipo interno del documento
`code`	string	Código SRI del documento
`subtotal`	number	Subtotal antes de impuestos
`discount`	number	Total de descuentos aplicados
`taxes_amount`	number	Total de impuestos
`total`	number	Total final del documento

3. Análisis de Impuestos (`taxes`)

Campo	Tipo	Descripción
`taxCode`	integer	Código del tipo de impuesto
`payments`	number	Total de pagos con este impuesto
`taxes`	number	Monto total del impuesto
`subtotal`	number	Subtotal antes del impuesto
`typeTaxTitle`	string	Nombre del tipo de impuesto
`taxTitle`	string	Descripción del porcentaje
`items`	array	Desglose detallado por código SRI

Filtros Avanzados

Los reportes soportan el sistema de filtros avanzados. Para más información sobre cómo implementar filtros, consulta la documentación de filtros.

Operadores de Filtro

Operador	Descripción	Ejemplo
`eq`	Igual a	`{"eq": "2024-01-15"}`
`ge`	Mayor o igual que	`{"ge": "2024-01-01"}`
`le`	Menor o igual que	`{"le": "2024-01-31"}`
`gt`	Mayor que	`{"gt": "2024-01-01"}`
`lt`	Menor que	`{"lt": "2024-01-31"}`
`in`	Dentro de una lista	`{"in": ["invoice", "credit_note"]}`

Ejemplos de Filtros Complejos

Reporte de pagos del último trimestre:

{
  "payment_date": [
    {"ge": "2024-01-01"},
    {"le": "2024-03-31"}
  ]
}

Reporte de facturas pagadas con tarjeta:

{
  "document_type": [{"eq": "invoice"}],
  "payment_method": [{"in": ["19", "16"]}]
}

Códigos de Métodos de Pago

Código	Descripción	Nombre Corto
`01`	SIN UTILIZACIÓN DEL SISTEMA FINANCIERO	Efectivo
`15`	COMPENSACIÓN DE DEUDAS	Comp. Deudas
`16`	TARJETA DE DÉBITO	Tarjeta/Débito
`17`	DINERO ELECTRÓNICO	Dinero electrónico
`18`	TARJETA PREPAGO	Tarjeta prepago
`19`	TARJETA DE CRÉDITO	Tarjeta/Crédito
`20`	OTROS CON UTILIZACIÓN DEL SISTEMA FINANCIERO	Banco
`21`	ENDOSO DE TÍTULOS	Endoso

Códigos de Tipos de Documento

Código	Tipo	Descripción
`01`	invoice	Factura
`04`	credit_note	Nota de crédito
`05`	debit_note	Nota de débito
`06`	guide	Guía de remisión
`07`	retention	Comprobante de retención

Códigos de Respuesta

Código	Descripción
`200`	Reporte generado exitosamente
`400`	Error en los parámetros de la solicitud
`401`	Token de autorización inválido
`422`	Error de validación (fechas inválidas o rango excedido)
`500`	Error interno del servidor

Notas Importantes

Los reportes se generan en tiempo real basándose en los datos actuales
Las exportaciones de documentos tienen un límite de 31 días para optimizar el rendimiento
Los filtros de fecha son obligatorios para las exportaciones
Los montos se muestran con 2 decimales de precisión
Los iconos HTML están diseñados para usar Font Awesome
Los reportes incluyen solo documentos autorizados por el SRI
Las fechas deben estar en formato ISO (YYYY-MM-DD)
Los archivos exportados se generan en formato Excel (.xlsx)
Los reportes respetan los permisos del usuario autenticado

Reportes y Análisis

Reportes y Análisis

Endpoints Disponibles

1. Reporte de Pagos

Headers Requeridos

Parámetros de Consulta (Opcionales)

Filtros Disponibles

Ejemplos de Implementación

Respuesta Exitosa (200 OK)

2. Exportar Documentos Emitidos

Headers Requeridos

Parámetros de Consulta (Requeridos)

Filtros Disponibles

Restricciones

Ejemplos de Implementación

Estructura de Respuestas

Reporte de Pagos

1. Pagos por Método (payment)

2. Ventas por Tipo de Documento (sales)

3. Análisis de Impuestos (taxes)

Filtros Avanzados

Operadores de Filtro

Ejemplos de Filtros Complejos

Códigos de Métodos de Pago

Códigos de Tipos de Documento

Códigos de Respuesta

Notas Importantes

1. Pagos por Método (`payment`)

2. Ventas por Tipo de Documento (`sales`)

3. Análisis de Impuestos (`taxes`)