Conversiones y sesiones, fila a fila

En Business y Agency, un conector propio puede copiar fila a fila las conversiones y las sesiones de un proyecto en tu almacén de datos. TraceLog no ofrece ningún conector ni envía las filas a ningún sitio: lo construyes tú y lee cuando lo ejecutas.

La clave de conector

Una clave de conector lee las filas de un proyecto y no escribe nada. No llega a otros proyectos ni a nada más de tu cuenta.

La crea la persona propietaria de la cuenta, en Ajustes → Instalación y claves → Crear clave de conector; hasta que tu proyecto se verifique por primera vez, el botón está en Otras claves. Un miembro ve la clave, pero no puede cambiarla. La clave solo se muestra al crearla: cópiala entonces.

Rótala desde el mismo lugar: la clave actual sigue funcionando 24 horas y después deja de hacerlo, así que la siguiente ejecución de tu conector no falla porque la clave haya cambiado. Una clave revocada deja de funcionar al instante.

Las dos lecturas

Las dos son GET y las dos llevan la clave en esta cabecera:

Authorization: Bearer tl_ck_xxxxxxxxxxxxxxxxxxxxxxxxxx

curl "https://api.tracelog.io/v1/connector/conversions" \
  --header "Authorization: Bearer tl_ck_xxxxxxxxxxxxxxxxxxxxxxxxxx"

Cada página trae cinco campos:

• rows, las filas;
• cursor, lo que envía la lectura siguiente;
• more, true si la página está llena;
• timezone, la zona horaria del proyecto;
• unverifiableDays, los días que se explican más abajo, en Coincidir con Analítica.

Las filas

Una fila de conversión es una conversión, con name e identifier como clave:

{
  "name": "purchase",
  "identifier": "order-1042",
  "firstBrowserAt": "2026-10-03T09:41:12.000Z",
  "firstServerAt": "2026-10-03T09:41:15.000Z",
  "value": 89.5,
  "currency": "EUR",
  "items": [
    {
      "id": "sku-7",
      "name": "Trail shoe",
      "category": null,
      "quantity": 1,
      "price": 89.5
    }
  ],
  "sessionId": "6f1c2a54-8f3b-4d7e-9a10-2c4b7e1d9f03",
  "channel": "paid_search",
  "aiPlatform": null,
  "utmSource": "google",
  "utmMedium": "cpc",
  "utmCampaign": "autumn",
  "utmTerm": null,
  "utmContent": null,
  "landingPage": "https://shop.example/shoes?utm_source=google&utm_medium=cpc&utm_campaign=autumn&gclid",
  "referrer": "https://www.google.com/",
  "device": "mobile",
  "country": "ES"
}

firstBrowserAt o firstServerAt es null si esa parte nunca envió la conversión. value, currency e items pueden ser null por separado, si la conversión no llevaba ese campo: una fila puede tener artículos sin valor, o un valor sin moneda. Una conversión que solo vio tu servidor no tiene sesión: su sessionId y los once campos que le siguen son null.

Una fila de sesión es una sesión, con sessionId como clave:

{
  "sessionId": "6f1c2a54-8f3b-4d7e-9a10-2c4b7e1d9f03",
  "startedAt": "2026-10-03T09:32:48.000Z",
  "channel": "paid_search",
  "aiPlatform": null,
  "utmSource": "google",
  "utmMedium": "cpc",
  "utmCampaign": "autumn",
  "utmTerm": null,
  "utmContent": null,
  "landingPage": "https://shop.example/shoes?utm_source=google&utm_medium=cpc&utm_campaign=autumn&gclid",
  "referrer": "https://www.google.com/",
  "device": "mobile",
  "country": "ES"
}

En los dos tipos de fila, aiPlatform, los campos utm, referrer y country son null si la visita no los traía.

Las dos lecturas excluyen el tráfico de staging, interno, de bots, sintético y de verificación, igual que Analítica.

La página de entrada de una fila nombra los identificadores de clic de la visita, nunca sus valores. Si necesitas un valor, guárdalo con tu propio pedido y une por identifier.

Leer página a página

Una lectura sin cursor empieza por la primera fila. Cada página tiene como máximo 1.000 filas; envía su cursor en la lectura siguiente, como ?cursor=, y sigue leyendo mientras more sea true. Guarda el último cursor: la siguiente ejecución lo envía y retoma donde se quedó esta. El cursor es opaco, así que guárdalo tal como llegó y no construyas ninguno. Cada endpoint tiene el suyo.

Las filas llegan en el orden en que cambiaron por última vez, no por fecha, así que una página no equivale a un día. Una página sin filas devuelve el cursor que enviaste: si la última página salió justo llena, la siguiente llega vacía y ahí termina la lectura.

Cada clave admite 60 solicitudes por minuto. Por encima, la lectura responde 429 con una cabecera retry-after que indica los segundos que hay que esperar.

Fusionar lo que lees

La fila de una conversión aparece en menos de una hora, cuando TraceLog ha contado su día; la de una sesión, al momento. Cada una vuelve a aparecer, completa, cada vez que cambia. Las filas no llevan fecha de modificación, así que fusiona por su clave, name con identifier en una fila de conversión y sessionId en una de sesión: gana la fila leída después.

Un día pasado aún puede cambiar si le llega un evento tardío, y una conversión puede pasar a otro día, así que agrupa después de fusionar.

Coincidir con Analítica

Agrupa las filas fusionadas por el día local del proyecto en timezone: el del más temprano de firstBrowserAt y firstServerAt en una conversión y el de startedAt en una sesión. En las conversiones, suma value por currency. Esos recuentos y sumas coinciden con Analítica en cada día pasado ya contado, salvo en los que indica unverifiableDays. Las filas de esos días son lo que llegó y pueden quedarse cortas.

Dónde empieza el registro

El registro de un proyecto creado antes de que se publicara esta lectura empieza 30 días antes de esa publicación; lo ves en el día más antiguo de tus filas fusionadas. Los días anteriores quedan fuera, porque su valor y sus artículos ya no se pueden leer con la regla que usó Analítica. Un proyecto creado después se lee entero.

Una pausa

Las lecturas de una cuenta en pausa se rechazan con la frase que indica qué las reanuda. Mientras tanto no se pierde nada: al reanudarse, el mismo cursor continúa.

Rechazos

Cuando la clave es válida, un rechazo indica su código y qué ha pasado, en inglés:

{
  "refused": "tier",
  "sentence": "Copying this project's conversions and sessions, row by row, into your data store is included in Business and Agency."
}

• 401, sin cuerpo: falta la clave, tiene otro formato, no existe o es de otro tipo.
• tier (403): el plan del proyecto no es Business ni Agency.
• paused (402): la cuenta está en pausa; su frase indica qué la reanuda.
• cursor_unknown (400): este cursor no lo ha generado TraceLog. Vuelve a leer sin cursor, desde el principio, fusionando sobre lo que ya tienes.
• cursor_restored (410): TraceLog ha restaurado sus datos desde una copia de seguridad. Sigue los pasos de Después de una restauración, más abajo.

Después de una restauración

Con una restauración pueden perderse filas o cambios que ya habías copiado. Esas filas no se vuelven a leer, así que, si fusionas una nueva lectura con lo que ya tienes, conservas filas que TraceLog ya no tiene y tus sumas superan las de su registro.

1. Lee sin cursor, desde el principio, en un destino vacío, fusionando por la clave de cada fila como siempre.
2. Cuando more sea false, sustituye lo que tenías de ese endpoint por ese resultado y sigue desde su último cursor.
3. Haz lo mismo en cada endpoint: cada uno rechaza su propio cursor.