Interpretación de los informes y extracción de datos

Actualizado hace 28 días

1. Página de resumen

Después de guardar la configuración del flujo, se abre una página de resumen que presenta toda la información necesaria para la extracción de datos.

Modificar la configuración

Puede modificar la información introducida previamente haciendo clic en la pestaña «Editar la configuración del flujo».

También puede acceder a esta página desde la pestaña «Configuraciones de flujo» haciendo clic en el símbolo del ojo de la columna «Acciones» de la tabla.

2. Elementos de extracción

Las condiciones de extracción del origen elegido se muestran en forma de tres elementos obligatorios que deben combinarse:

Método

GET: protocolo de solicitud utilizado para recuperar los datos.

Autorización

Bearer Token: clave de seguridad necesaria para acceder al contenido.

URL del punto final

URL en formato JSON o CSV:

https://gate.teeptrak.net/api/....json
https://gate.teeptrak.net/api/....csv

3. Notas importantes

Paginación y límites de solicitudes

Los datos se devuelven por bloques para garantizar un rendimiento óptimo.

Límites de solicitudes

  • Máximo: 1 solicitud cada 2 segundos por token
  • Cuota horaria: 500 solicitudes por hora por token

Si se supera este límite, la API devuelve un error 429 Too Many Requests.

Recomendación: espacie sus solicitudes al menos 8 segundos para mantenerse holgadamente dentro de ambos límites.

Resultados por página

Cada solicitud devuelve un máximo de 2000 resultados por página (2000 líneas). Para una exportación de 5000 resultados, es necesario realizar varias solicitudes, ya que los resultados se reparten en bloques de 2000 líneas.

Excepción: el conteo de productos está limitado a 1000 resultados por página.

4. Ejemplo de recuperación de datos

Mediante el método GET, la autorización Bearer Token y la URL proporcionada, puede exportar sus datos en formato JSON y/o CSV.

Procedimiento con Postman

  1. Introduzca la información de la API en los campos correspondientes de Postman
  2. Los datos exportados en formato JSON se muestran en la sección inferior

5. Parámetros opcionales y paginación

Es posible aplicar filtros a las exportaciones para afinar y optimizar sus necesidades de extracción.

Uso en Postman

  1. Haga clic en «Params»
  2. Introduzca las claves y los valores correspondientes
  3. Haga clic en «Send» para validar el filtro

Lista de parámetros disponibles

N.º Parámetro Descripción
1 page Definir el número de página devuelto por la API
2 created_at_gte Definir el umbral «mayor o igual que» (creado el…)
3 created_at_lte Definir el umbral «menor o igual que» (creado el…)
4 updated_at_lte Definir el umbral «menor o igual que» (actualizado el…)
5 with_custom_fields Permitir la visualización de los campos personalizados
6 machine_ids Filtrar la solicitud por una o varias máquinas

6. Datos brutos - Alternativa V2 con paginación por cursor

Presentación

Para la API de datos brutos, está disponible una alternativa opcional: la API Performance Logs V2. Esta API ofrece una paginación por cursor más robusta que la paginación clásica por número de página, lo que garantiza que cada registro se devuelva exactamente una vez, aunque los datos cambien entre sus solicitudes.

Endpoints V2:

GET /api/v1/external/performance_logs.json
GET /api/v1/external/performance_logs.csv
GET /api/v1/external/performance_logs/simplified_losses.json
GET /api/v1/external/performance_logs/simplified_losses.csv

Endpoints V1 clásicos (siguen disponibles):

GET /api/v1/external/raw_data
GET /api/v1/external/simplified_losses

Puede seguir utilizando la paginación clásica por page o adoptar la paginación por cursor según sus necesidades.

¿Cuándo utilizar V2 (cursor)?

  • Tiene una sincronización periódica de datos (diaria, horaria, etc.)
  • Quiere garantizar cero pérdidas o duplicaciones de datos
  • Gestiona grandes volúmenes y quiere una exportación CSV en una sola solicitud

¿Cuándo permanecer en V1 (página)?

  • Realiza exportaciones puntuales sencillas
  • Prefiere la paginación clásica por número de página
  • Su integración existente funciona bien con V1

Paginación por cursor: instrucciones de uso

Parámetros específicos de V2

Parámetro Descripción
since Fecha ISO 8601 para la primera solicitud (p. ej., 2025-01-01T00:00:00Z).
cursor Clave de paginación para las solicitudes siguientes. Véase más abajo.
limit Número de resultados por página (valor por defecto: 2000, máx.: 2000)

Concepto

El cursor es una clave de paginación que garantiza que cada registro se devuelva exactamente una vez, aunque los datos cambien entre sus solicitudes. Esto ofrece una mejor integridad de los datos en comparación con la paginación simple por número de página.

Primera solicitud (sincronización inicial)

Lance su primera solicitud sin cursor, utilizando el parámetro since o sin ningún parámetro:

GET /api/v1/external/performance_logs?since=2025-01-01T00:00:00Z

La respuesta JSON incluye un objeto meta que contiene un next_cursor:

{
  "data": [ ... ],
  "meta": {
    "next_cursor": "eyJ1cGRhdGVkX2F0IjoiMjAyNS0wNi0wMVQxMDoxNTowMC4wMDAwMDBaIiwiaWQiOjJ9"
  },
  "links": {
    "next": "https://gate.teeptrak.net/api/v1/external/performance_logs?cursor=eyJ1cGRhdGVkX2F0Ij..."
  }
}

Solicitudes siguientes (sincronización incremental)

Guarde el último next_cursor recibido. Para la siguiente solicitud, utilice este cursor como parámetro:

GET /api/v1/external/performance_logs?cursor=eyJ1cGRhdGVkX2F0IjoiMjAyNS0wNi0wMVQxMDoxNTowMC4wMDAwMDBaIiwiaWQiOjJ9

La respuesta devuelve un nuevo next_cursor para la solicitud siguiente. Repita este ciclo hasta que next_cursor sea null, lo que indica que ha obtenido todos los datos disponibles.

Fin de la paginación

Cuando meta.next_cursor vale null o el número de resultados es inferior al límite, ha recuperado todos los registros disponibles.
Para continuar la solicitud más adelante y obtener los nuevos datos, se recomienda conservar el último cursor que no sea null.

Caso de error: cursor perdido

Si pierde su último cursor guardado, vuelva a lanzar una solicitud con el parámetro since y una fecha aproximada de su última sincronización correcta. Recuperará entonces los datos a partir de esa fecha.

Ejemplo completo de una sincronización en tres solicitudes

  1. Sincronización inicial
Solicitud 1: GET /api/v1/external/performance_logs?since=2025-01-01T00:00:00Z
Respuesta: 2000 registros + next_cursor = "cursor_ABC"
Guarde "cursor_ABC"
  1. Sincronización incremental
Solicitud 2: GET /api/v1/external/performance_logs?cursor=cursor_ABC
Respuesta: 2000 registros + next_cursor = "cursor_XYZ"
Guarde "cursor_XYZ"
  1. Última sincronización incremental
Solicitud 3: GET /api/v1/external/performance_logs?cursor=cursor_XYZ
Respuesta: 1500 registros + next_cursor = "cursor_qsd"
Guarde "cursor_qsd"
Sincronización terminada

7. Gestión del cursor con Postman (variables de entorno)

Para automatizar la gestión del cursor en Postman, utilice las variables de entorno.

Configuración inicial

  1. Abra Postman y vaya a «Manage Environments» (icono de engranaje)
  2. Cree o modifique su entorno Gate
  3. Añada dos variables:
    • Clave: cursor | Valor: (dejar vacío)
    • Clave: token | Valor: su Bearer Token

Primera solicitud

En la pestaña Params, añada:

Clave Valor
since 2025-01-01T00:00:00Z

En la pestaña Authorization, seleccione Bearer Token e introduzca su token.

Haga clic en Send.

Actualización del cursor después de cada respuesta

  1. Vaya a la pestaña Tests
  2. Añada este script para guardar automáticamente el next_cursor:
if (pm.response.code === 200) {
  const responseData = pm.response.json();
  if (responseData.meta && responseData.meta.next_cursor) {
    pm.environment.set("cursor", responseData.meta.next_cursor);
    console.log("Cursor guardado:", responseData.meta.next_cursor);
  } else {
    console.log("Fin de la paginación: next_cursor es null");
  }
}

Solicitudes siguientes

  1. En la pestaña Params, elimine el parámetro since
  2. Añada el parámetro cursor con el valor {{cursor}}
  3. Haga clic en Send

Postman sustituirá automáticamente {{cursor}} por el último valor guardado. Después de cada respuesta, el script actualiza la variable con el nuevo cursor.

Repetir hasta el final

Siga enviando la solicitud. El cursor se actualiza automáticamente después de cada llamada. Cuando next_cursor es null, la sincronización ha terminado.

8. Estructura de la respuesta V2

Respuesta JSON

{
  "data": [
    {
      "id": 1,
      "duration": 300,
      "machine_id": 10,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T11:00:00Z",
      "custom_fields": {
        "Team": "Morning",
        "Line": "L3"
      }
    }
  ],
  "meta": {
    "next_cursor": "eyJ1cGRhdGVkX2F0IjoiMjAyNS0wNi0wMVQxMDoxNTowMC4wMDAwMDBaIiwiaWQiOjJ9"
  },
  "links": {
    "next": "https://gate.teeptrak.net/api/v1/external/performance_logs?cursor=eyJ..."
  }
}

Elementos clave

Elemento Descripción
data Tabla que contiene los registros de rendimiento
meta.next_cursor Cursor para la solicitud siguiente. null si es el fin de la paginación
links.next URL preconstruida para la solicitud siguiente (opcional)
data.custom_fields Objeto que contiene los campos personalizados (si están activados)

Formato de las fechas

Todas las fechas se devuelven en formato ISO 8601 en UTC (p. ej., 2025-01-15T10:30:00Z).

10. Ejemplos de integraciones con V2

Exportación CSV completa

Para exportar todos los datos en CSV de una sola vez:

GET /api/v1/external/performance_logs.csv?since=2025-01-01T00:00:00Z

Esta única solicitud devuelve todos los resultados en un solo archivo CSV, sin necesidad de paginación. Ideal para las exportaciones puntuales.

Filtrado por máquinas

Para extraer los datos de máquinas específicas:

GET /api/v1/external/performance_logs?cursor=...&machine_ids=10,20,30

Campos personalizados

Para incluir los campos personalizados en la respuesta:

GET /api/v1/external/performance_logs?cursor=...&with_custom_fields=true

Aparecerán en el objeto with_custom_fields de cada registro.