Sistema de Filtros

Sistema de Filtros

Pruebas

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

Producción

Dominio: https://api-financiero.e-dinky.com

La API de facturación implementa un sistema de filtros avanzado que permite realizar consultas complejas en todos los endpoints que soportan filtrado de datos.

Esquema de Filtros

Los filtros se implementan como un array de objetos JSON, donde cada objeto representa una condición de filtrado:

[
    {
        "field": "nombre_del_campo",
        "condition": "condición",
        "value": "valor"
    }
]

Parámetros del Filtro

Campo	Tipo	Requerido	Descripción
field	string	Sí	Campo en la base de datos para filtrar
condition	string	Sí	Condición del filtro
value	string	Sí	Valor para aplicar el filtro

Condiciones Disponibles

Condición	Descripción	Ejemplo
eq	Igual a	{"field": "status", "condition": "eq", "value": "active"}
in	Está en la lista (valores separados por coma)	{"field": "type", "condition": "in", "value": "invoice,credit_note"}
sw	Comienza con	{"field": "number_document", "condition": "sw", "value": "001"}
ew	Termina con	{"field": "access_key", "condition": "ew", "value": "123"}
gt	Mayor que	{"field": "total", "condition": "gt", "value": "100"}
ge	Mayor o igual que	{"field": "created_at", "condition": "ge", "value": "2024-01-01"}
lt	Menor que	{"field": "total", "condition": "lt", "value": "500"}
le	Menor o igual que	{"field": "date_sent_costumer", "condition": "le", "value": "2024-12-31"}

Ejemplos de Filtros

Filtros Básicos

[
    {"field": "date_sent_costumer", "condition": "eq", "value": "2024-02-10"},
    {"field": "subtotal", "condition": "in", "value": "4,5"},
    {"field": "number_document", "condition": "sw", "value": "1234"},
    {"field": "access_key", "condition": "ew", "value": "0192"},
    {"field": "signed_date", "condition": "gt", "value": "2024-02-16"},
    {"field": "created_at", "condition": "ge", "value": "2024-11-19"}
]

Filtros por Rango de Fechas

[
    {"field": "created_at", "condition": "ge", "value": "2024-01-01"},
    {"field": "created_at", "condition": "le", "value": "2024-12-31"}
]

Filtros por Estado y Tipo

[
    {"field": "status", "condition": "eq", "value": "authorized"},
    {"field": "type", "condition": "in", "value": "invoice,credit_note"}
]

Filtros por Montos

[
    {"field": "total", "condition": "gt", "value": "100"},
    {"field": "total", "condition": "lt", "value": "1000"}
]

Implementación en Diferentes Tecnologías

Laravel PHP

<?php

use Illuminate\Http\Client\Response;
use Illuminate\Support\Facades\Http;

class ApiClient
{
    private $baseUrl;
    private $token;

    public function __construct(string $baseUrl, string $token)
    {
        $this->baseUrl = $baseUrl;
        $this->token = $token;
    }

    /**
     * Consultar documentos con filtros
     */
    public function getDocumentsWithFilters(array $filters, int $page = 1, int $perPage = 15): Response
    {
        $queryParams = [
            'page' => $page,
            'per_page' => $perPage,
            'filters' => json_encode($filters)
        ];

        return Http::withHeaders([
            'Authorization' => 'Bearer ' . $this->token,
            'Content-Type' => 'application/json',
            'Accept' => 'application/json'
        ])->get($this->baseUrl . '/api/v1/documents', $queryParams);
    }

    /**
     * Consultar usuarios con filtros
     */
    public function getUsersWithFilters(array $filters, int $page = 1): Response
    {
        $queryParams = [
            'page' => $page,
            'filters' => json_encode($filters)
        ];

        return Http::withHeaders([
            'Authorization' => 'Bearer ' . $this->token,
            'Accept' => 'application/json'
        ])->get($this->baseUrl . '/api/v1/users', $queryParams);
    }

    /**
     * Reportes de pagos con filtros
     */
    public function getPaymentReports(array $filters): Response
    {
        $queryParams = [
            'filters' => json_encode($filters)
        ];

        return Http::withHeaders([
            'Authorization' => 'Bearer ' . $this->token,
            'Accept' => 'application/json'
        ])->get($this->baseUrl . '/api/v1/reports/payments', $queryParams);
    }
}

// Ejemplo de uso
$apiClient = new ApiClient('https://api.facturacion.com', 'your-token-here');

// Filtros para documentos autorizados del último mes
$documentFilters = [
    ['field' => 'status', 'condition' => 'eq', 'value' => 'authorized'],
    ['field' => 'created_at', 'condition' => 'ge', 'value' => '2024-11-01'],
    ['field' => 'created_at', 'condition' => 'le', 'value' => '2024-11-30']
];

$response = $apiClient->getDocumentsWithFilters($documentFilters, 1, 20);

if ($response->successful()) {
    $documents = $response->json();
    // Procesar documentos
} else {
    // Manejar error
    echo 'Error: ' . $response->body();
}

Node.js

const axios = require('axios');

class ApiClient {
    constructor(baseUrl, token) {
        this.baseUrl = baseUrl;
        this.token = token;
        this.headers = {
            'Authorization': `Bearer ${token}`,
            'Content-Type': 'application/json',
            'Accept': 'application/json'
        };
    }

    /**
     * Consultar documentos con filtros
     */
    async getDocumentsWithFilters(filters, page = 1, perPage = 15) {
        try {
            const params = {
                page,
                per_page: perPage,
                filters: JSON.stringify(filters)
            };

            const response = await axios.get(`${this.baseUrl}/api/v1/documents`, {
                headers: this.headers,
                params
            });

            return response.data;
        } catch (error) {
            throw new Error(`Error fetching documents: ${error.response?.data?.message || error.message}`);
        }
    }

    /**
     * Consultar usuarios con filtros
     */
    async getUsersWithFilters(filters, page = 1) {
        try {
            const params = {
                page,
                filters: JSON.stringify(filters)
            };

            const response = await axios.get(`${this.baseUrl}/api/v1/users`, {
                headers: this.headers,
                params
            });

            return response.data;
        } catch (error) {
            throw new Error(`Error fetching users: ${error.response?.data?.message || error.message}`);
        }
    }

    /**
     * Reportes de pagos con filtros
     */
    async getPaymentReports(filters) {
        try {
            const params = {
                filters: JSON.stringify(filters)
            };

            const response = await axios.get(`${this.baseUrl}/api/v1/reports/payments`, {
                headers: this.headers,
                params
            });

            return response.data;
        } catch (error) {
            throw new Error(`Error fetching payment reports: ${error.response?.data?.message || error.message}`);
        }
    }

    /**
     * Exportar reportes de documentos con filtros
     */
    async exportDocumentReports(filters) {
        try {
            const params = {
                filters: JSON.stringify(filters)
            };

            const response = await axios.get(`${this.baseUrl}/api/v1/reports/documents/export`, {
                headers: this.headers,
                params,
                responseType: 'blob' // Para descargar archivos
            });

            return response.data;
        } catch (error) {
            throw new Error(`Error exporting reports: ${error.response?.data?.message || error.message}`);
        }
    }
}

// Ejemplo de uso
const apiClient = new ApiClient('https://api.facturacion.com', 'your-token-here');

// Filtros para facturas del último trimestre
const documentFilters = [
    { field: 'type', condition: 'eq', value: 'invoice' },
    { field: 'created_at', condition: 'ge', value: '2024-10-01' },
    { field: 'created_at', condition: 'le', value: '2024-12-31' },
    { field: 'total', condition: 'gt', value: '50' }
];

// Usar async/await
(async () => {
    try {
        const documents = await apiClient.getDocumentsWithFilters(documentFilters, 1, 25);
        console.log('Documentos encontrados:', documents.payload.items.length);

        // Filtros para usuarios activos
        const userFilters = [
            { field: 'status', condition: 'eq', value: 'active' },
            { field: 'created_at', condition: 'ge', value: '2024-01-01' }
        ];

        const users = await apiClient.getUsersWithFilters(userFilters);
        console.log('Usuarios activos:', users.payload.items.length);

    } catch (error) {
        console.error('Error:', error.message);
    }
})();

cURL

#!/bin/bash

# Variables de configuración
BASE_URL="https://api.facturacion.com"
TOKEN="your-token-here"

# Función para hacer peticiones con filtros
make_request_with_filters() {
    local endpoint="$1"
    local filters="$2"
    local additional_params="$3"

    # URL encode de los filtros
    local encoded_filters=$(echo "$filters" | jq -r @uri)

    # Construir URL completa
    local url="${BASE_URL}${endpoint}?filters=${encoded_filters}"

    # Agregar parámetros adicionales si existen
    if [ ! -z "$additional_params" ]; then
        url="${url}&${additional_params}"
    fi

    # Hacer la petición
    curl -X GET "$url" \
        -H "Authorization: Bearer $TOKEN" \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -w "\nHTTP Status: %{http_code}\n" \
        -s
}

# Ejemplo 1: Consultar documentos con filtros
echo "=== Consultando documentos con filtros ==="
DOCUMENT_FILTERS='[
    {"field": "status", "condition": "eq", "value": "authorized"},
    {"field": "type", "condition": "in", "value": "invoice,credit_note"},
    {"field": "created_at", "condition": "ge", "value": "2024-11-01"},
    {"field": "total", "condition": "gt", "value": "100"}
]'

make_request_with_filters "/api/v1/documents" "$DOCUMENT_FILTERS" "page=1&per_page=20"

echo -e "\n\n"

# Ejemplo 2: Consultar usuarios con filtros
echo "=== Consultando usuarios con filtros ==="
USER_FILTERS='[
    {"field": "status", "condition": "eq", "value": "active"},
    {"field": "created_at", "condition": "ge", "value": "2024-01-01"}
]'

make_request_with_filters "/api/v1/users" "$USER_FILTERS" "page=1"

echo -e "\n\n"

# Ejemplo 3: Reportes de pagos con filtros
echo "=== Consultando reportes de pagos ==="
PAYMENT_FILTERS='[
    {"field": "payment_date", "condition": "ge", "value": "2024-11-01"},
    {"field": "payment_date", "condition": "le", "value": "2024-11-30"}
]'

make_request_with_filters "/api/v1/reports/payments" "$PAYMENT_FILTERS"

echo -e "\n\n"

# Ejemplo 4: Exportar reportes de documentos
echo "=== Exportando reportes de documentos ==="
EXPORT_FILTERS='[
    {"field": "date", "condition": "ge", "value": "2024-02-01"},
    {"field": "date", "condition": "le", "value": "2024-02-28"}
]'

# Para exportar archivos, guardar la respuesta en un archivo
curl -X GET "${BASE_URL}/api/v1/reports/documents/export?filters=$(echo "$EXPORT_FILTERS" | jq -r @uri)" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Accept: application/json" \
    -o "reporte_documentos.xlsx" \
    -w "HTTP Status: %{http_code}\n"

echo "Reporte guardado en reporte_documentos.xlsx"

# Ejemplo 5: Filtros complejos con múltiples condiciones
echo -e "\n\n=== Filtros complejos ==="
COMPLEX_FILTERS='[
    {"field": "number_document", "condition": "sw", "value": "001"},
    {"field": "access_key", "condition": "ew", "value": "123"},
    {"field": "subtotal", "condition": "in", "value": "10,20,30,40,50"},
    {"field": "signed_date", "condition": "gt", "value": "2024-01-01"}
]'

make_request_with_filters "/api/v1/documents" "$COMPLEX_FILTERS" "page=1&per_page=10"

Endpoints que Soportan Filtros

Documentos

• GET /api/v1/documents - Consultar documentos
• GET /api/v1/reports/documents/export - Exportar reportes de documentos

Usuarios

• GET /api/v1/users - Consultar usuarios

Reportes

• GET /api/v1/reports/payments - Reportes de pagos

Clientes

• GET /api/v1/customers - Consultar clientes (próximamente)

Campos Comunes para Filtros

Documentos

• date_sent_costumer - Fecha de envío al cliente
• subtotal - Subtotal del documento
• total - Total del documento
• number_document - Número del documento
• access_key - Clave de acceso
• signed_date - Fecha de firma
• created_at - Fecha de creación
• status - Estado del documento
• type - Tipo de documento
• code_document - Código del documento SRI

Usuarios

• name - Nombre del usuario
• last_name - Apellido del usuario
• email - Email del usuario
• phone - Teléfono del usuario
• created_at - Fecha de creación
• account_id - ID de la cuenta
• estado - Estado del usuario

Pagos

• payment_date - Fecha del pago
• amount - Monto del pago
• payment_method - Método de pago
• status - Estado del pago

Notas Importantes

• Los filtros deben enviarse como un string JSON válido en el parámetro filters
• Todos los valores deben ser strings, incluso para números y fechas
• Las fechas deben estar en formato YYYY-MM-DD
• Para la condición in, los valores se separan con comas sin espacios
• Los filtros se aplican con lógica AND (todos deben cumplirse)
• Los nombres de campos son sensibles a mayúsculas y minúsculas
• Algunos campos pueden tener alias o nombres específicos según el endpoint

Códigos de Error

• 400: Formato de filtros inválido
• 422: Campos de filtro no válidos o condiciones incorrectas
• 500: Error interno del servidor al procesar filtros