Reporte de Diferencias

Comparación del monto del sistema frente al del proveedor por factura — resalta discrepancias con diferencias porcentuales y absolutas.

GET/apidev/v1/reports/portal/differences

PermisoAPICLI_RPTPORTALPROVEEDOR_DIFERENCIAS

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

Caché300s (5 min)

Rango máximo93 días

---

Resumen

Compara los montos calculados por el sistema con los montos reportados por el proveedor para cada factura. Devuelve filas paginadas con las diferencias por factura y un resumen con totales agregados.

• Detalle por factura — diferencia absoluta y porcentual de cada factura
• Filtrado por proveedor — restringí a proveedores específicos (hasta 100)
• Filtrado por estado — filtrá por códigos de estado de factura (100–106)
• Agregados del resumen — montos totales del sistema frente al proveedor, diferencia neta, cantidad de facturas con discrepancias

---

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 separados por comas (100–106). 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/differences?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/differences?startdate=2026-01-01&enddate=2026-03-31&limit=50`,
  { headers }
);
const { data, meta } = await response.json();
console.log(`Net difference: ${data.summary.net_difference}`);

Python

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

---

Campos de la respuesta

Filas

Campo	Tipo	Descripción
invoice_id	string	Identificador de la factura
provider_id	string	Identificador del proveedor
provider_name	string	Nombre visible del proveedor
service_id	string	Identificador del servicio asociado
service_number	string	Número de servicio (legible)
invoice_date	string	Fecha de la factura
system_amount	number	Monto calculado por el sistema
provider_amount	number | null	Monto reportado por el proveedor. null si no se envió
difference	number	Diferencia absoluta (sistema − proveedor)
difference_pct	number	Diferencia porcentual
state_code	string | null	Código de estado de la factura
state_name	string | null	Nombre legible del estado
provider_invoice_number	string | null	Número de factura propio del proveedor
provider_invoice_date	string | null	Fecha de la factura del proveedor

Resumen

Campo	Tipo	Descripción
total_system	number	Suma de todos los montos del sistema
total_provider	number	Suma de todos los montos del proveedor
net_difference	number	Total del sistema − total del proveedor
avg_variation_pct	number	Porcentaje de variación promedio
total_invoices	number	Cantidad total de facturas en el rango
invoices_with_difference	number	Cantidad de facturas donde la diferencia ≠ 0

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "rows": [
      {
        "invoice_id": "710450328800",
        "provider_id": "504210987600",
        "provider_name": "Transporte Rápido S.A.",
        "service_id": "820134567800",
        "service_number": "SRV-2026-00142",
        "invoice_date": "2026-02-15",
        "system_amount": 12500.00,
        "provider_amount": 13100.00,
        "difference": -600.00,
        "difference_pct": -4.80,
        "state_code": "101",
        "state_name": "In Review",
        "provider_invoice_number": "FAC-2026-0087",
        "provider_invoice_date": "2026-02-14"
      },
      {
        "invoice_id": "710450328801",
        "provider_id": "504210987601",
        "provider_name": "Logística del Norte",
        "service_id": "820134567801",
        "service_number": "SRV-2026-00158",
        "invoice_date": "2026-02-18",
        "system_amount": 8700.00,
        "provider_amount": 8700.00,
        "difference": 0.00,
        "difference_pct": 0.00,
        "state_code": "102",
        "state_name": "Approved",
        "provider_invoice_number": "LN-0234",
        "provider_invoice_date": "2026-02-17"
      }
    ],
    "summary": {
      "total_system": 842300.00,
      "total_provider": 856720.00,
      "net_difference": -14420.00,
      "avg_variation_pct": 1.71,
      "total_invoices": 253,
      "invoices_with_difference": 87
    }
  },
  "meta": {
    "total": 253,
    "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_DIFERENCIAS
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 Tolerancia — Análisis de reglas de tolerancia por factura
• Facturas del Portal — Endpoints de gestión de facturas
• Paginación — Parámetros de paginación estándar