Integración con la API de TimesFM

Este documento explica cómo consumir la API de predicción desde otro proyecto.

No incluye infraestructura, datos privados ni detalles internos de despliegue. Solo contratos de petición y respuesta, autenticación y ejemplos de uso.

1. Resumen

La API expone tres capacidades públicas:

1. Ejecutar una predicción de series temporales.

2. Consultar el estado de una ejecución concreta.

3. Verificar el estado de salud del servicio.

La API devuelve predicciones dentro de un recurso forecast run que guarda:

estado de la ejecución;

backend usado;

modelo usado;

horizonte;

serie de entrada;

predicción devuelta;

mensajes de error si falló;

marcas de tiempo;

referencias a la ejecución.

2. Autenticación

La API usa una clave de acceso.

2.1 Formas aceptadas

Puedes enviar la clave de dos maneras:

Cabecera X-API-Key

Cabecera Authorization: Bearer

2.2 Reglas

La clave debe existir y estar activa.

Si la clave no existe o fue revocada, la API devuelve 401.

Si falta la clave, la API devuelve 401.

2.3 Ejemplo

curl -X POST "https://tu-dominio/api/forecast" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tu_clave" \
  -d '{"series":[1,2,3,4,5],"horizon":3}'

3. Endpoints

3.1 Ejecutar predicción sincrónica

POST /api/forecast

Este endpoint ejecuta la predicción en la misma petición.

Devuelve:

201 Created

meta.mode = sync

3.2 Ejecutar predicción asíncrona

POST /api/forecast/async

Este endpoint encola la predicción para procesarla después.

Devuelve:

202 Accepted

meta.mode = async

3.3 Consultar una ejecución

GET /api/forecast-runs/{forecastRun}

Devuelve el estado actual de una ejecución concreta.

Devuelve:

200 OK

meta.mode = status

3.4 Salud del servicio

GET /api/health

No requiere API key.

Sirve para monitorización básica del stack.

4. Payload de predicción

4.1 Campos aceptados

{
  "series": [1, 2, 3, 4, 5],
  "horizon": 3,
  "frequency": "D",
  "model": "optional-model",
  "metadata": {}
}

4.2 Descripción de parámetros

`series`

Obligatorio

Array numérico no vacío

Representa la historia conocida que el modelo debe usar para inferir el futuro

Ejemplo:

[10, 12, 13, 15, 18]

`horizon`

Obligatorio

Entero entre 1 y 1024

Indica cuántos puntos futuros debe devolver el modelo

Ejemplo:

horizon = 3 devuelve tres valores futuros

`frequency`

Opcional

Cadena de hasta 32 caracteres

Describe la granularidad temporal de la serie

Valores habituales:

D = diario

W = semanal

M = mensual

Si no se define (null o ausente), el motor de TimeSSeract intentará calcular la frecuencia automáticamente usando Transformada Rápida de Fourier (FFT). Este proceso requiere obligatoriamente al menos 14 puntos de datos históricos en la serie. De lo contrario, se devolverá null por falta de muestras suficientes para encontrar un patrón estacional confiable.

`metadata`

Opcional

Objeto o array adicional

Útil para adjuntar contexto propio de tu aplicación

Actualmente no modifica el cálculo, pero puede viajar con la petición si tu integración lo necesita.

5. Qué devuelve la API

La respuesta normalizada devuelve un recurso de ejecución.

5.1 Campos principales

id

status

provider

backend

horizon

frequency

input_series

forecast

error_message

user_id

api_key_id

queued_at

started_at

completed_at

created_at

updated_at

links.self

5.2 Significado de los campos

`status`

Estado de la ejecución.

Valores posibles:

queued

running

completed

failed

`provider`

Proveedor lógico de la predicción.

En este proyecto se expone como timesfm.

`backend`

Backend real que produjo la respuesta.

Valores habituales:

timesfm

naive

`input_series`

Serie de entrada que se envió al sistema.

`forecast`

Resultado de predicción.

Suele contener:

horizon

forecast

backend

quantiles cuando estén disponibles

`error_message`

Mensaje de error si la ejecución falló.

Si la ejecución terminó bien, este campo suele ser null.

Timestamps

queued_at

started_at

completed_at

created_at

updated_at

Van en formato ISO 8601.

6. Ejemplos de respuesta

6.1 Respuesta sincrónica correcta

{
  "data": {
    "id": 123,
    "status": "completed",
    "provider": "timesfm",
    "backend": "timesfm",
    "horizon": 3,
    "frequency": "D",
    "input_series": [1, 2, 3, 4, 5],
    "forecast": {
      "horizon": 3,
      "forecast": [5.8, 6.1, 6.4],
      "backend": "timesfm"
    },
    "error_message": null,
    "user_id": 10,
    "api_key_id": 4,
    "queued_at": "2026-07-01T12:00:00+00:00",
    "started_at": "2026-07-01T12:00:01+00:00",
    "completed_at": "2026-07-01T12:00:02+00:00",
    "created_at": "2026-07-01T12:00:00+00:00",
    "updated_at": "2026-07-01T12:00:02+00:00",
    "links": {
      "self": "https://tu-dominio/api/forecast-runs/123"
    }
  },
  "meta": {
    "mode": "sync"
  }
}

6.2 Respuesta asíncrona

{
  "data": {
    "id": 124,
    "status": "queued",
    "provider": "timesfm",
    "backend": "unknown",
    "horizon": 24,
    "frequency": null,
    "input_series": [10, 20, 30],
    "forecast": null,
    "error_message": null,
    "user_id": 10,
    "api_key_id": 4,
    "queued_at": "2026-07-01T12:10:00+00:00",
    "started_at": null,
    "completed_at": null,
    "created_at": "2026-07-01T12:10:00+00:00",
    "updated_at": "2026-07-01T12:10:00+00:00",
    "links": {
      "self": "https://tu-dominio/api/forecast-runs/124"
    }
  },
  "meta": {
    "mode": "async"
  }
}

7. Errores comunes

7.1 Falta API key

{
  "message": "Missing API key."
}

HTTP:

401

7.2 API key invalida o revocada

{
  "message": "Invalid API key."
}

HTTP:

401

7.3 Validacion de payload

Si faltan campos obligatorios o el formato no es valido, Laravel devuelve errores de validacion.

Casos tipicos:

series vacia o no numerica;

horizon fuera de rango;

frequency demasiado larga;

model demasiado largo.

HTTP habitual:

422

8. Ejemplos de integracion

8.1 JavaScript / TypeScript

type ForecastResponse = {
  data: {
    id: number;
    status: 'queued' | 'running' | 'completed' | 'failed';
    provider: string;
    backend: string;
    model: string | null;
    horizon: number;
    frequency: string | null;
    input_series: number[];
    forecast: unknown;
    error_message: string | null;
    links: { self: string };
  };
  meta: { mode: 'sync' | 'async' | 'status' };
};

async function forecast(series: number[], horizon = 3) {
  const response = await fetch('/api/forecast', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.TIMESFM_API_KEY ?? '',
    },
    body: JSON.stringify({ series, horizon }),
  });

  if (!response.ok) {
    throw new Error(`Forecast failed: ${response.status}`);
  }

  return (await response.json()) as ForecastResponse;
}

8.2 PHP

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'X-API-Key' => config('services.timesfm.api_key'),
])->post('https://tu-dominio/api/forecast', [
    'series' => [1, 2, 3, 4, 5],
    'horizon' => 3,
    'frequency' => 'D',
]);

if (! $response->successful()) {
    throw new RuntimeException('Forecast request failed');
}

$payload = $response->json();

9. Recomendaciones de integracion

Guarda la API key en variables de entorno o en un vault, nunca en el frontend.

Maneja 401 y 422 de forma explícita.

Usa POST /api/forecast/async si tu proceso no necesita el resultado inmediato.

Usa GET /api/forecast-runs/{id} para poll de estado en flujos asincronos.

No asumas que forecast siempre sera una secuencia lineal perfecta; el modelo devuelve una continuation estadistica del patron.

10. Resumen rapido

Lo minimo para consumir la API es:

1. Enviar X-API-Key o Authorization: Bearer.

2. Hacer POST /api/forecast con series y horizon.

3. Leer data.forecast, data.backend, data.model y data.status.

4. Si usas asincrono, consultar GET /api/forecast-runs/{id}.