🚀 Novedades en Pixcua: Refactor de Paginación y Limpieza de Endpoints

Documentación
_

Con el objetivo de mejorar el rendimiento, la coherencia del API y la experiencia de desarrollo, este fin de semana liberamos una nueva versión de Pixcua con importantes ajustes en la forma en que se consultan y gestionan los recursos principales del sistema.

🔧 Novedades clave

  • Paginación estandarizada en los endpoints principales
    • GET /comprobantes ahora entrega respuestas con estructura paginada (data, meta, links).
    • Se incluyen filtros por page, limit, q (búsqueda), sortBy, sortDir, timbrado, cliente_id y fechas.
    • Para exportaciones o reportes completos, el parámetro isReporte=1 conserva el comportamiento previo (ver detalles más abajo).
  • GET /clientes actualizado
    • Adopta el mismo formato paginado.
    • Permite búsqueda por nombre, RFC o email, y orden configurable por cualquier campo.
  • Documentación y consistencia
    • Endpoints en formato homogéneo (nombres en minúsculas, descripciones actualizadas).
    • Rutas legadas marcadas como deprecated para asegurar compatibilidad temporal.
    • Se elimina la vista independiente de Addendas en el frontend; la gestión continúa dentro del wizard de Comprobantes.

⚙️ Cambios en la API

  • Los consumidores que esperaban arrays “planos” ahora deben leer los datos desde payload.data y utilizar meta y links para la navegación entre páginas.
  • El endpoint /envioComprobante pasa a estado deprecated.
    → Usar en su lugar: /comprobantes/:uuid/enviar

🧩 Compatibilidad con el modo previo (isReporte=1)

Mientras llames GET /comprobantes con el parámetro isReporte=1, el sistema mantiene el comportamiento anterior:

  • Regresa un arreglo plano de comprobantes (sin data, meta ni links).
  • Mantiene la respuesta 404 cuando no se encuentran registros, tal como en la versión anterior.
  • Este es el modo reporte, pensado para exportaciones o generación de CSV.

De esta forma, cualquier cliente o integración que aún espere el formato viejo puede seguir funcionando sin interrupciones.
En cuanto migren al nuevo esquema paginado, podrán omitir isReporte=1 y aprovechar los nuevos metadatos.

🧪 Ejemplo práctico (Swagger → cURL)

Este ejemplo muestra cómo luce una llamada real desde Swagger usando cURL al endpoint paginado.
El token y los datos sensibles fueron anonimizados, y la respuesta fue recortada a 5 registros ficticios.

# Curl
curl -X 'GET' \
  'https://sandbox.pixcua.app/api/comprobantes?page=1&limit=25' \
  -H 'accept: application/json' \
  -H 'Authorization: ***'

# Request URL
https://sandbox.pixcua.app/api/comprobantes?page=1&limit=25

# Server response
Code: 200

# Response body (5 registros fake)
{
  "data": [
    {
      "id": 90001,
      "serie": "A",
      "folio": 12001,
      "fecha": "2025-06-19 16:45:29",
      "rfc": "AAA010101AAA",
      "nombre": "ACME LOGÍSTICA, S.A. DE C.V.",
      "subtotal": 5000.00,
      "descuento": 0,
      "iva": 800.00,
      "tasa": 16,
      "total": 5800.00,
      "pagado": true,
      "forma_de_pago": "03",
      "metodo_de_pago": "PUE",
      "tipo_de_comprobante": "I",
      "timbrado": true,
      "uuid": "11111111-1111-4111-8111-111111111111"
    },
    {
      "id": 90002,
      "serie": "A",
      "folio": 12002,
      "fecha": "2025-06-20 10:12:05",
      "rfc": "XEXX010101000",
      "nombre": "CLIENTE DEMO INTERNACIONAL",
      "subtotal": 2100.00,
      "iva": 336.00,
      "total": 2436.00,
      "uuid": "22222222-2222-4222-8222-222222222222"
    },
    {
      "id": 90003,
      "serie": "B",
      "folio": 305,
      "fecha": "2025-06-21 08:30:15",
      "rfc": "ABC123456T11",
      "nombre": "FABRICACIONES DEL NORTE",
      "subtotal": 14500.00,
      "iva": 2240.00,
      "total": 16240.00,
      "uuid": "33333333-3333-4333-8333-333333333333"
    },
    {
      "id": 90004,
      "serie": "C",
      "folio": 78,
      "fecha": "2025-06-21 12:05:40",
      "rfc": "DEM010101AB1",
      "nombre": "DISTRIBUIDORA DEMO, S. DE R.L.",
      "subtotal": 890.00,
      "iva": 142.40,
      "total": 1032.40,
      "uuid": "44444444-4444-4444-8444-444444444444"
    },
    {
      "id": 90005,
      "serie": "A",
      "folio": 12003,
      "fecha": "2025-06-22 09:10:00",
      "rfc": "AAA010101AAA",
      "nombre": "ACME LOGÍSTICA, S.A. DE C.V.",
      "subtotal": 3200.00,
      "iva": 512.00,
      "total": 3712.00,
      "uuid": "55555555-5555-4555-8555-555555555555"
    }
  ],
  "meta": {
    "total": 7014,
    "page": 1,
    "limit": 25,
    "totalPages": 281,
    "sortBy": "id",
    "sortDir": "DESC"
  },
  "links": {
    "first": "/api/comprobantes?page=1&limit=25",
    "prev": null,
    "next": "/api/comprobantes?page=2&limit=25",
    "last": "/api/comprobantes?page=281&limit=25"
  }
}

# Response headers (resumen)
access-control-allow-origin: *
content-type: application/json; charset=utf-8
x-powered-by: Express

# Request duration
~1150 ms

Modo reporte (sin paginación):

curl -X 'GET' \
  'https://sandbox.pixcua.app/api/comprobantes?isReporte=1' \
  -H 'accept: application/json' \
  -H 'Authorization: ***'

📚 Documentación y Sandbox actualizados

Ya puedes consultar y probar los endpoints actualizados directamente en nuestro entorno de prueba:

🔗 Swagger Sandbox (API Pixcua)
👉 https://sandbox.pixcua.app/docs

El frontend del Sandbox ya utiliza esta nueva versión del API, por lo que puedes:

  • Navegar el entorno con tu cuenta de prueba.
  • Inspeccionar las llamadas en el navegador (DevTools → pestaña Network).
  • Ver cómo se aplican los parámetros de paginación, filtros y cómo luce la respuesta con data, meta y links.

✅ Acciones sugeridas para los usuarios

  1. Actualizar integraciones que consuman /comprobantes o /clientes para adaptarlas al nuevo formato paginado.
  2. Revisar las vistas en la UI que muestran listados, utilizando los nuevos objetos meta y links para la navegación.
  3. Usar el nuevo endpoint de envío /comprobantes/:uuid/enviar y mantener /envioComprobante solo durante el periodo de deprecación.
  4. Consultar la documentación actualizada en el Swagger Sandbox y observar las llamadas reales en el entorno de prueba.

📘 Estas mejoras preparan el terreno para nuevas funcionalidades y reportes más eficientes, manteniendo la compatibilidad con implementaciones actuales durante el periodo de transición.

Para cualquier duda o asistencia técnica, contacta a nuestro equipo en soporte@pixcua.com.

♥9