Reporte de Puntaje de Calidad

Puntaje de calidad de finalización por grupo basado en los campos de formulario capturados, las fotos y la firma en las tareas finalizadas.

GET/apidev/v1/reports/gt/quality-score

PermisoAPICLI_RPTGT_QUALITYSCORE

Límite de tasa10 req/min

Caché300s

Rango máximo92 días

---

Resumen

Puntúa qué tan completamente se documentó cada tarea finalizada y promedia ese puntaje por grupo. El puntaje de calidad combina tres componentes por tarea:

• 40% — campos de formulario completados versus los campos esperados para el producto de la tarea.
• 30% — al menos una foto adjunta.
• 30% — una firma capturada.

Una tarea con todos los campos esperados completados, una foto y una firma obtiene 100. El reporte devuelve el puntaje promedio por grupo junto con la cantidad de soporte (tareas con fotos, tareas con firma, total de campos de formulario completados versus esperados), para que puedas ver qué componente está bajando el puntaje. Elegí cómo se agrupan las filas con group_by (por defecto es prestador).

---

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	Requerido	Por defecto	Descripción
startdate	string	Sí	—	Fecha-hora de inicio en ISO 8601 (ej. 2026-03-01T00:00:00).
enddate	string	Sí	—	Fecha-hora de fin en ISO 8601. Rango máximo de 92 días desde startdate.
group_by	string	No	provider	Cómo se agrupan las filas. Uno de: provider, device, driver, cause, subcause, service_type, product, origin, shift, end_code, comm_media, route, country, department, city, zone, client, telephonist, operator, resource_type, date, month, weekday, hour.
devices	string	No	—	IDs de dispositivos separados por coma. Máx 500.
drivers	string	No	—	IDs de conductores separados por coma. Máx 500.
providers	string	No	—	IDs de prestadores separados por coma. Máx 100.
service_types	string	No	—	IDs de tipos de servicio separados por coma. Máx 100.
causes	string	No	—	IDs de causas separados por coma. Máx 100.
subcauses	string	No	—	IDs de subcausas separados por coma. Máx 100.
statuses	string	No	—	Códigos de estado de tarea separados por coma. Máx 100.
device_groups	string	No	Todos	Ids de tipo de dispositivo separados por comas (el catálogo device_group que expone Flota / Dispositivos). Acota las tareas a los dispositivos de esos tipos; se combina con devices como intersección. Máximo 100
origins	string	No	—	IDs de orígenes separados por coma. Máx 100.
route_ids	string	No	—	IDs de rutas separados por coma. Máx 100.
operators	string	No	—	IDs de operadores separados por coma. Máx 100.
client_id	string	No	—	ID de un solo cliente.
account_id	string	No	—	ID de una sola cuenta.
shift_id	string	No	—	ID de un solo turno.
limit	integer	No	25	Cantidad de registros por página (1–100).
offset	integer	No	0	Cantidad de registros a omitir para la paginación.

Cómo se combina device_groups con devices

device_groups se expande a todos los dispositivos de esos tipos, y si además mandás devices, se quedan solo los dispositivos que están en las dos listas. Si esa intersección queda vacía, el reporte no devuelve filas.

---

Ejemplos de código

cURL

curl -s -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  "https://$TENANT/apidev/v1/reports/gt/quality-score?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&group_by=driver&limit=25"

JavaScript

const res = await fetch(
  `https://${TENANT}/apidev/v1/reports/gt/quality-score?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&group_by=driver&limit=25`,
  {
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'X-API-Key': APIKEY,
      'tenant': TENANT,
    },
  }
);
const data = await res.json();

Python

import requests

response = requests.get(
    f"https://{TENANT}/apidev/v1/reports/gt/quality-score",
    headers={"Authorization": f"Bearer {TOKEN}", "X-API-Key": APIKEY, "tenant": TENANT},
    params={
        "startdate": "2026-03-01T00:00:00",
        "enddate": "2026-03-15T23:59:59",
        "group_by": "driver",
        "limit": 25,
    },
)
data = response.json()

---

Respuesta

Campos de la respuesta

Campo	Tipo	Descripción
group_label	string	Nombre visible del grupo (ej. conductor, dispositivo, prestador).
group_id	string | null	ID interno del grupo, o null cuando no se puede resolver.
total	number	Total de tareas finalizadas en el grupo.
score_promedio	number	Puntaje de calidad promedio (0–100) de las tareas del grupo.
con_fotos	number	Tareas que tienen al menos una foto adjunta.
con_firma	number	Tareas que tienen una firma capturada.
oav_completos_total	number	Total de campos de formulario completados en el grupo.
oav_esperados_total	number	Total de campos de formulario esperados para las tareas del grupo.

Ejemplo de respuesta

{
  "success": true,
  "data": [
    {
      "group_label": "Carlos Martinez",
      "group_id": "10293",
      "total": 120,
      "score_promedio": 87.34,
      "con_fotos": 112,
      "con_firma": 98,
      "oav_completos_total": 540,
      "oav_esperados_total": 600
    }
  ],
  "meta": {
    "total": 1,
    "limit": 25,
    "offset": 0
  }
}

---

Errores

Código	HTTP	Descripción
VALIDATION_ERROR	400	Parámetros inválidos: fechas faltantes, rango > 92 días, valores de enum inválidos.
UNAUTHORIZED	401	tenant / Authorization / X-API-Key faltante, inválido o expirado
FORBIDDEN	403	El usuario no tiene el permiso requerido.
RATE_LIMITED	429	Se superó el límite de 10 req/min.
INTERNAL_ERROR	500	Error inesperado del servidor.

---

Relacionados

• Reporte de Cumplimiento de Ventana Horaria
• Reporte de Revisitas
• Reporte de Formularios Avanzados
• Paginación