Reporte de Facturación

Facturación agregada por proveedor — total facturado, montos del proveedor, estado de pago y tasas de aprobación.

GET/apidev/v1/reports/portal/billing

PermisoAPICLI_RPTPORTALPROVEEDOR_FACTURACION

Límite de solicitudes10 req/min (ventana deslizante)

Caché300s (5 min)

Rango máximo93 días

---

Resumen

Agrega los datos de facturación por proveedor para el rango de fechas indicado. Cada fila representa un proveedor con los totales de montos facturados, montos reportados por el proveedor, estado de pago y cantidades de aprobaciones/rechazos.

• Resumen por proveedor — cantidad de tareas, totales facturados, estado de pago, tasa de aprobación
• Totales generales — agregados de todos los proveedores en la respuesta
• Filtrado por proveedor — restringí a proveedores específicos (hasta 100)

---

Solicitud

Encabezados de la solicitud

Every request to a protected endpoint requires these headers:

Header	Required	Description
Authorization	Yes	Bearer token obtained from the Login endpoint. Format: Bearer <token>
X-API-Key	Yes	Company integration key provided during onboarding. Format: gtk_xxx...
tenant	Yes	Your assigned tenant domain (default: geotareas.com) — always send your assigned tenant
Content-Type	Conditional	application/json — required for POST and PUT requests

Parámetros de consulta

Parámetro	Tipo	Obligatorio	Por defecto	Descripción
startdate	string	Sí	—	Fecha de inicio ISO 8601
enddate	string	Sí	—	Fecha de fin ISO 8601. Rango máximo 93 días
providers	string	No	Todos	IDs de proveedor separados por comas. Máximo 100

---

Ejemplos de código

cURL

curl -s "https://$TENANT/apidev/v1/reports/portal/billing?startdate=2026-01-01&enddate=2026-03-31" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

JavaScript

const response = await fetch(
  `https://${TENANT}/apidev/v1/reports/portal/billing?startdate=2026-01-01&enddate=2026-03-31`,
  { headers }
);
const { data } = await response.json();
console.log(`Total invoiced: ${data.grand_total.total_invoiced}`);

Python

response = requests.get(
    f"https://{TENANT}/apidev/v1/reports/portal/billing",
    headers=headers,
    params={"startdate": "2026-01-01", "enddate": "2026-03-31"},
)
result = response.json()
for row in result["data"]["rows"]:
    print(f"{row['provider_name']}: {row['total_invoiced']}")

---

Campos de la respuesta

Filas

Campo	Tipo	Descripción
provider_id	string	Identificador del proveedor
provider_name	string	Nombre visible del proveedor
task_count	number	Cantidad de tareas/servicios en el período
total_invoiced	number	Monto total facturado calculado por el sistema
total_provider	number	Monto total reportado por el proveedor
total_paid	number	Monto total ya pagado
pending_payment	number	Monto pendiente de pago
approval_rate	number	Tasa de aprobación como porcentaje (0–100)
approved_count	number	Cantidad de facturas aprobadas
rejected_count	number	Cantidad de facturas rechazadas
review_count	number	Cantidad de facturas en revisión

Total general

Campo	Tipo	Descripción
total_invoiced	number	Suma de los montos facturados de todos los proveedores
total_provider	number	Suma de los montos reportados de todos los proveedores
total_paid	number	Suma de todos los montos pagados
pending_payment	number	Suma de todos los pagos pendientes
task_count	number	Cantidad total de tareas de todos los proveedores

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "rows": [
      {
        "provider_id": "504210987600",
        "provider_name": "Transporte Rápido S.A.",
        "task_count": 42,
        "total_invoiced": 245800.00,
        "total_provider": 251200.00,
        "total_paid": 198400.00,
        "pending_payment": 47400.00,
        "approval_rate": 88.10,
        "approved_count": 37,
        "rejected_count": 2,
        "review_count": 3
      },
      {
        "provider_id": "504210987601",
        "provider_name": "Logística del Norte",
        "task_count": 35,
        "total_invoiced": 198300.00,
        "total_provider": 199100.00,
        "total_paid": 178500.00,
        "pending_payment": 19800.00,
        "approval_rate": 94.29,
        "approved_count": 33,
        "rejected_count": 1,
        "review_count": 1
      },
      {
        "provider_id": "504210987602",
        "provider_name": "ServiFlota Express",
        "task_count": 28,
        "total_invoiced": 167500.00,
        "total_provider": 169800.00,
        "total_paid": 142000.00,
        "pending_payment": 25500.00,
        "approval_rate": 85.71,
        "approved_count": 24,
        "rejected_count": 2,
        "review_count": 2
      }
    ],
    "grand_total": {
      "total_invoiced": 611600.00,
      "total_provider": 620100.00,
      "total_paid": 518900.00,
      "pending_payment": 92700.00,
      "task_count": 105
    }
  },
  "meta": {
    "total": 3
  }
}

---

Errores

Código	HTTP	Descripción
VALIDATION_ERROR	400	El rango de fechas supera los 93 días, > 100 proveedores
UNAUTHORIZED	401	tenant / Authorization / X-API-Key ausente, inválido o expirado
FORBIDDEN	403	El usuario no tiene el permiso APICLI_RPTPORTALPROVEEDOR_FACTURACION
RATE_LIMITED	429	Se superaron 10 req/min
INTERNAL_ERROR	500	Error inesperado del servidor

---

Relacionado

• Panel del Portal — KPIs ejecutivos y gráficos
• Reporte de Diferencias — Comparación por factura entre sistema y proveedor
• Reporte de Liquidaciones — Seguimiento y estado de liquidaciones
• Facturas del Portal — Endpoints de gestión de facturas