Reportes

GET`/api/v1/reportes`

Métricas operativas agregadas de tu empresa para un período dado. Por defecto retorna el mes en curso (desde las 00:00 del día 1 hasta las 23:59:59 del último día del mes).

Query params

Parámetro	Tipo	Default	Descripción
`fechaDesde`	`YYYY-MM-DD`	Inicio del mes actual	Inicio del período de análisis
`fechaHasta`	`YYYY-MM-DD`	Fin del mes actual	Fin del período (inclusive, hasta las 23:59:59 UTC)

Ejemplos

curl


# Mes actual (default)
curl https://api.tpcxpress.com/api/v1/reportes \
  -H "Authorization: Bearer TOKEN"
 
# Período personalizado
curl "https://api.tpcxpress.com/api/v1/reportes?fechaDesde=2026-06-01&fechaHasta=2026-06-30" \
  -H "Authorization: Bearer TOKEN"
 
# Semana actual
curl "https://api.tpcxpress.com/api/v1/reportes?fechaDesde=2026-06-30&fechaHasta=2026-07-06" \
  -H "Authorization: Bearer TOKEN"

JavaScript


const BASE = 'https://api.tpcxpress.com/api/v1'
const headers = { 'Authorization': `Bearer ${process.env.TPC_API_TOKEN}` }
 
// Mes actual (default)
const res = await fetch(`${BASE}/reportes`, { headers })
const { data } = await res.json()
 
// Período personalizado
const params = new URLSearchParams({ fechaDesde: '2026-06-01', fechaHasta: '2026-06-30' })
const res2 = await fetch(`${BASE}/reportes?${params}`, { headers })
const { data: data2 } = await res2.json()
 
// Semana actual
const params3 = new URLSearchParams({ fechaDesde: '2026-06-30', fechaHasta: '2026-07-06' })
const res3 = await fetch(`${BASE}/reportes?${params3}`, { headers })
const { data: data3 } = await res3.json()

Python


import httpx, os
 
client = httpx.Client(
    base_url="https://api.tpcxpress.com/api/v1",
    headers={"Authorization": f"Bearer {os.environ['TPC_API_TOKEN']}"},
)
 
# Mes actual (default)
data = client.get("/reportes").raise_for_status().json()["data"]
 
# Período personalizado
data2 = client.get("/reportes", params={
    "fechaDesde": "2026-06-01",
    "fechaHasta": "2026-06-30",
}).raise_for_status().json()["data"]
 
# Semana actual
data3 = client.get("/reportes", params={
    "fechaDesde": "2026-06-30",
    "fechaHasta": "2026-07-06",
}).raise_for_status().json()["data"]

Respuesta 200


{
  "success": true,
  "data": {
    "periodo": {
      "desde": "2026-07-01T00:00:00.000Z",
      "hasta": "2026-07-31T23:59:59.000Z"
    },
    "totalGuias": 150,
    "entregadasPeriodo": 130,
    "tasaEntrega": 86.7,
    "porEstado": {
      "SIN_RECOLLECTAR": 5,
      "RECOLECTADO": 8,
      "EN_BODEGA": 2,
      "EN_RUTA": 5,
      "ENTREGADO": 120,
      "DEVOLUCION": 3,
      "DEVOLUCION_ENTREGADO": 2,
      "ANULADA": 4,
      "ENTREGADO_LIQUIDADO": 1
    },
    "montoCODEntregado": 12500.00
  }
}

Métricas explicadas

Campo	Tipo	Descripción
`totalGuias`	integer	Total de guías creadas en el período (independiente del estado actual)
`entregadasPeriodo`	integer	Guías con estado `ENTREGADO` creadas en el período
`tasaEntrega`	number	`entregadasPeriodo / totalGuias × 100` redondeado a 1 decimal
`porEstado`	object	Conteo de guías del período por cada estado
`montoCODEntregado`	number	Suma de `montoTotal` de guías COD en estado `ENTREGADO` (en Quetzales)

Nota sobre totalGuias vs porEstado: totalGuias es la suma de todos los valores en porEstado. Las guías con estados activos (ej. EN_RUTA) están incluidas en el total aunque no estén entregadas todavía.

Calcular métricas derivadas


async function obtenerReporte(fechaDesde, fechaHasta) {
  const params = new URLSearchParams()
  if (fechaDesde) params.set('fechaDesde', fechaDesde)
  if (fechaHasta) params.set('fechaHasta', fechaHasta)
 
  const res = await fetch(
    `https://api.tpcxpress.com/api/v1/reportes?${params}`,
    { headers: { 'Authorization': `Bearer ${process.env.TPC_API_TOKEN}` } }
  )
  const { data } = await res.json()
 
  // Métricas adicionales derivadas
  const enTransito = (data.porEstado.RECOLECTADO ?? 0)
    + (data.porEstado.EN_BODEGA ?? 0)
    + (data.porEstado.EN_RUTA ?? 0)
 
  const devoluciones = (data.porEstado.DEVOLUCION ?? 0)
    + (data.porEstado.DEVOLUCION_ENTREGADO ?? 0)
 
  const tasaDevolucion = data.totalGuias > 0
    ? (devoluciones / data.totalGuias * 100).toFixed(1)
    : 0
 
  return {
    ...data,
    enTransito,
    devoluciones,
    tasaDevolucion: parseFloat(tasaDevolucion),
  }
}

Monto COD y liquidaciones

El campo montoCODEntregado representa el monto total cobrado a los destinatarios por guías COD que fueron entregadas en el período. Este valor es útil para:

Verificar el monto que TPC debe liquidarte
Conciliar contra el estado de cuenta
Proyecciones de flujo de caja

montoCODEntregado es el valor bruto. La liquidación neta que recibes es este monto menos la comisión COD (porcentajeCOD) y el costo del servicio de mensajería. Ver GET /api/v1/empresa para los porcentajes de tu cuenta.

Dashboard simple con reportes


async function generarResumenMensual() {
  const hoy = new Date()
  const inicio = new Date(hoy.getFullYear(), hoy.getMonth(), 1)
  const fin = new Date(hoy.getFullYear(), hoy.getMonth() + 1, 0)
 
  const formatDate = d => d.toISOString().slice(0, 10)
 
  const reporte = await obtenerReporte(
    formatDate(inicio),
    formatDate(fin)
  )
 
  console.log(`📦 Total guías: ${reporte.totalGuias}`)
  console.log(`✅ Entregadas: ${reporte.entregadasPeriodo} (${reporte.tasaEntrega}%)`)
  console.log(`🚚 En tránsito: ${reporte.enTransito}`)
  console.log(`↩️  Devoluciones: ${reporte.devoluciones} (${reporte.tasaDevolucion}%)`)
  console.log(`💰 COD cobrado: Q ${reporte.montoCODEntregado.toFixed(2)}`)
}