Reporte de Liquidaciones

Seguimiento de liquidaciones con estado, montos, cantidad de comprobantes e indicadores de cierre forzado. Incluye agregados de resumen.

GET/apidev/v1/reports/portal/settlements

PermisoAPICLI_RPTPORTALPROVEEDOR_LIQUIDACIONES

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

Caché300s (5 min)

Rango máximo93 días

---

Resumen

Devuelve registros de liquidaciones paginados con estado, totales financieros, cantidad de comprobantes e indicadores de cierre forzado. Incluye un resumen con cantidades y montos agregados.

• Filtrado por estado — filtrá por códigos de estado de liquidación (200–204)
• Filtrado por proveedor — restringí a proveedores específicos (hasta 100)
• Detección de cierre forzado — identificá las liquidaciones que se cerraron de forma forzada
• Agregados del resumen — total de liquidaciones, cantidades de abiertas frente a cerradas, diferencias netas

---

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
states	string	No	Todos	Códigos de estado de liquidación separados por comas (200–204). Máximo 10
limit	integer	No	25	Registros por página (1–100)
offset	integer	No	0	Registros a omitir

---

Ejemplos de código

cURL

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

JavaScript

const response = await fetch(
  `https://${TENANT}/apidev/v1/reports/portal/settlements?startdate=2026-01-01&enddate=2026-03-31&limit=50`,
  { headers }
);
const { data, meta } = await response.json();
console.log(`Open settlements: ${data.summary.open}`);

Python

response = requests.get(
    f"https://{TENANT}/apidev/v1/reports/portal/settlements",
    headers=headers,
    params={"startdate": "2026-01-01", "enddate": "2026-03-31", "limit": 50},
)
result = response.json()
summary = result["data"]["summary"]

---

Campos de la respuesta

Filas

Campo	Tipo	Descripción
settlement_id	string	Identificador de la liquidación
provider_id	string	Identificador del proveedor
provider_name	string	Nombre visible del proveedor
date	string	Fecha de creación de la liquidación
state_id	number	Código de estado de la liquidación (200–204)
state_name	string	Nombre legible del estado
invoice_count	number	Cantidad de facturas en esta liquidación
total	number	Monto total de la liquidación
total_vouchers	number	Monto total de comprobantes
total_adjustments	number	Monto total de ajustes
difference	number	Diferencia (total − comprobantes − ajustes)
forced_close	boolean	Si la liquidación se cerró de forma forzada
payment_number	string | null	Número de referencia del pago
payment_notes	string | null	Notas u observaciones del pago
close_date	string | null	Fecha en que se cerró la liquidación. null si sigue abierta
voucher_count	number	Cantidad de comprobantes adjuntos

Resumen

Campo	Tipo	Descripción
total_settlements	number	Cantidad total de liquidaciones en el rango
total_system	number	Suma de todos los totales de liquidación
total_vouchers	number	Suma de todos los montos de comprobantes
total_difference	number	Diferencia neta de todas las liquidaciones
closed	number	Cantidad de liquidaciones cerradas
open	number	Cantidad de liquidaciones abiertas

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "rows": [
      {
        "settlement_id": "930120456700",
        "provider_id": "504210987600",
        "provider_name": "Transporte Rápido S.A.",
        "date": "2026-02-01",
        "state_id": 202,
        "state_name": "Closed",
        "invoice_count": 18,
        "total": 145200.00,
        "total_vouchers": 143800.00,
        "total_adjustments": 800.00,
        "difference": 600.00,
        "forced_close": false,
        "payment_number": "PAG-2026-0034",
        "payment_notes": "Wire transfer confirmed",
        "close_date": "2026-02-28",
        "voucher_count": 3
      },
      {
        "settlement_id": "930120456701",
        "provider_id": "504210987601",
        "provider_name": "Logística del Norte",
        "date": "2026-03-01",
        "state_id": 200,
        "state_name": "Open",
        "invoice_count": 12,
        "total": 98500.00,
        "total_vouchers": 0.00,
        "total_adjustments": 0.00,
        "difference": 98500.00,
        "forced_close": false,
        "payment_number": null,
        "payment_notes": null,
        "close_date": null,
        "voucher_count": 0
      }
    ],
    "summary": {
      "total_settlements": 14,
      "total_system": 876400.00,
      "total_vouchers": 712300.00,
      "total_difference": 164100.00,
      "closed": 9,
      "open": 5
    }
  },
  "meta": {
    "total": 14,
    "limit": 50,
    "offset": 0
  }
}

---

Errores

Código	HTTP	Descripción
VALIDATION_ERROR	400	El rango de fechas supera los 93 días, códigos de estado inválidos, > 100 proveedores
UNAUTHORIZED	401	tenant / Authorization / X-API-Key ausente, inválido o expirado
FORBIDDEN	403	El usuario no tiene el permiso APICLI_RPTPORTALPROVEEDOR_LIQUIDACIONES
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 Facturación — Facturación agregada por proveedor
• Liquidaciones del Portal — Endpoints de gestión de liquidaciones
• Paginación — Parámetros de paginación estándar