# Ingesta

> El protocolo que usan los SDK para enviar eventos, trozos de grabación y capturas de página, para quien escribe su propio cliente.

Aplica a: el motor de Sypnia (código abierto, en tu propia infraestructura) y Sypnia Cloud (servicio pago). Estado: al lanzar.  
Fuente: https://docs.sypnia.com/es/api/ingest/

Para agentes: Referencia de los endpoints de ingesta de la API HTTP de Sypnia: sobre del lote de eventos, trozos de grabación, capturas de página, configuración para el SDK y el script del SDK; límites, reintentos y errores.

Los SDK llaman a estos endpoints por ti. Lee esta página si escribes tu propio cliente, si envías eventos desde una plataforma sin SDK, o si quieres saber exactamente qué sale del navegador.

En Sypnia Cloud el servidor es `https://ingest.sypnia.com`. Un motor alojado por ti sirve las mismas rutas desde su propia URL base.

## Autenticación

Los endpoints de ingesta reciben una llave de ingesta (`spk_…`). Es pública y solo de escritura: puede enviar datos y no puede leer nada. Envíala de una de dos formas:

- el encabezado `Authorization: Bearer spk_…`, o
- el parámetro `key=spk_…`, para `navigator.sendBeacon`, que no puede poner encabezados.

Un token de API (`sps_…`) se rechaza aquí con `403 wrong_credential`, así un secreto nunca termina por error en un navegador.

## Cuerpos

Todo cuerpo es JSON. Lo puedes comprimir con gzip: el motor detecta gzip por los dos primeros bytes (`1f 8b`), diga lo que diga el `Content-Type`, porque `sendBeacon` no puede poner `Content-Encoding`. Los límites se revisan después de descomprimir.

## Límites

| Límite                                                     | Valor                                                                                                                                           |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Eventos en un lote                                         | 200                                                                                                                                             |
| Cuerpo de un lote                                          | 2 MiB después de descomprimir. El SDK del navegador mantiene un lote por debajo de 40.800 caracteres para que quepa en una petición `keepalive` |
| Cuerpo de un trozo de grabación o de una captura de página | 4.000.000 de bytes después de descomprimir                                                                                                      |
| Trozos de grabación en una sesión                          | 720 (dos horas a un trozo cada 10 segundos)                                                                                                     |
| Capturas de página en una sesión                           | 5, una por ruta (son la imagen que va debajo de un mapa de clics)                                                                               |
| Pila de un error                                           | 4.000 caracteres                                                                                                                                |
| Mensaje de un error                                        | 500 caracteres                                                                                                                                  |
| Etiqueta y contexto de un clic                             | 80 caracteres cada uno                                                                                                                          |
| Selector                                                   | 200 caracteres                                                                                                                                  |

Las cadenas más largas se cortan, no se rechazan. Los eventos que no pasan la validación se descartan uno por uno y se cuentan en la respuesta; el resto del lote se guarda.

## Reintentos

Reintenta una falla de red, `408`, `429` y `5xx`, con el mismo `batch_id` (eventos) o el mismo `seq` (grabación). Los dos son idempotentes: un lote o un trozo repetido se reemplaza a sí mismo. No reintentes ningún otro `4xx`. Con `429`, espera lo que diga `Retry-After`.

## Cuando se llega a un límite

Nada se descarta en silencio. Cada respuesta dice cuántos eventos se guardaron y cuántos no, y por qué. Cuando el proyecto llega a un límite (el de un plan en Sypnia Cloud, una cuota que tú pusiste en tu motor), la respuesta trae `slow_down`: qué debe seguir enviando el SDK y hasta cuándo. Los SDK oficiales lo obedecen. El dueño del proyecto recibe una alerta al 80 % y al 100 %. Mira [uso](https://docs.sypnia.com/es/api/projects-keys-and-tokens).

## Orígenes

Un proyecto puede listar los orígenes que pueden enviar datos desde un navegador (`settings.allowed_origins`). Cuando la lista está vacía se acepta cualquier origen. Las peticiones sin encabezado `Origin` (servidores, apps móviles) siempre se aceptan.

## Enviar un lote de eventos

`POST /v1/ingest/events` \[Motor, Nube]

Guarda hasta 200 eventos. La forma de cada evento está en el [esquema de eventos](https://docs.sypnia.com/es/reference/event-schema) (`spec/events.schema.json`); este endpoint solo define el sobre que los envuelve.

El motor valida cada evento por separado. Un evento válido se guarda; uno inválido se descarta y se cuenta en `dropped`, con la razón en `dropped_reasons`. Los campos que el motor no conoce se conservan, así un SDK más nuevo nunca rompe un motor más viejo. El motor le pone a cada evento el proyecto y la hora en que llegó, y nunca los toma de quien envía.

El entorno es distinto: solo tu app lo sabe, así que viene en el evento (`env`), y es `production` cuando el evento no trae ninguno. Un proyecto guarda hasta 20 nombres de entorno. Un evento que agregaría el número veintiuno se descarta y se cuenta en `environment_limit`, para que un error en tu código no cree entornos sin fin.

Envía `batch_id` y reutilízalo al reintentar: un lote que llega dos veces se guarda una sola vez.

**Autenticación:** Llave de ingesta

**Cuerpo:**

- `batch_id` (string, hasta 64 caracteres, opcional): Un id que quien envía elige para este lote, un UUID. Un reintento lo reutiliza: un lote que llega dos veces se guarda una.
- `sent_at` (timestamp, opcional): Cuándo salió el lote, según el reloj de quien envía, en ISO 8601 y UTC. El motor lo compara con su propio reloj para notar un dispositivo con la hora mal.
- `sdk` (object, opcional): Qué SDK armó el lote.
- `sdk.name` (string, hasta 40 caracteres): El nombre del paquete, por ejemplo `@sypnia/browser`.
- `sdk.version` (string, hasta 20 caracteres): La versión del paquete, por ejemplo `1.0.0`.
- `events` (lista de object, hasta 200 elementos, obligatorio): Los eventos, en el orden en que ocurrieron. Máximo 200. Una lista vacía se acepta y no guarda nada.

**Petición:**

```bash
curl -X POST "https://ingest.sypnia.com/v1/ingest/events" \
  -H "Authorization: Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e" \
  -H "Content-Type: application/json" \
  --data @batch.json
```

**Cuerpo de la petición:**

```json
{
  "batch_id": "0b9f6c3e-2a41-4d7e-9c1b-6f2e8a4d7c10",
  "sent_at": "2026-03-12T10:31:48Z",
  "sdk": {
    "name": "@sypnia/browser",
    "version": "1.0.0"
  },
  "events": [
    {
      "v": 1,
      "type": "click",
      "ts": 1773311503000,
      "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
      "url": "/checkout",
      "route": "/checkout",
      "sel": "#pay-button",
      "txt": "Pay $64.00",
      "crole": "button",
      "ctx": "Your order"
    },
    {
      "v": 1,
      "type": "error",
      "ts": 1773311507004,
      "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
      "url": "/checkout",
      "route": "/checkout",
      "name": "ApiError",
      "msg": "POST /api/checkout failed with 400 (amount_required)"
    }
  ]
}
```

Los eventos de arriba están recortados para mostrar el sobre. El esquema de eventos lista cada campo de cada tipo de evento.

**Respuesta: Todo guardado (200):**

```json
{
  "accepted": 2,
  "dropped": 0
}
```

**Respuesta: El proyecto llegó a su límite de eventos (200):**

```json
{
  "accepted": 1,
  "dropped": 1,
  "dropped_reasons": {
    "limit_reached": 1
  },
  "slow_down": {
    "reason": "events_limit",
    "send": "failures",
    "replay": false,
    "until": "2026-04-01T00:00:00Z"
  }
}
```

**Errores:**

- `400` `invalid_body`: El cuerpo no es JSON, no es gzip válido, o `events` no es una lista.
- `400` `too_many_events`: Más de 200 eventos en el lote. No se guarda nada. Divide el lote.
- `401` `unauthorized`: Falta la llave de ingesta, es desconocida o está revocada.
- `403` `wrong_credential`: Se envió un token de API o el token raíz. La ingesta solo recibe una llave de ingesta.
- `403` `origin_not_allowed`: La petición trae un `Origin` que no está en `allowed_origins` del proyecto.
- `413` `payload_too_large`: El cuerpo pesa más de 2 MiB después de descomprimirlo.
- `429` `rate_limited`: Demasiadas peticiones desde esta dirección con esta llave. Espera lo que diga `Retry-After` y envía el mismo lote otra vez.
- `503` `unavailable`: El motor no pudo escribir en el almacenamiento. Reintenta con el mismo `batch_id`.

## Enviar un trozo de grabación

`POST /v1/ingest/replay` \[Motor, Nube]

Guarda un trozo de la grabación de una sesión. El SDK envía un trozo cada 10 segundos, o antes si el trozo pasa de 200 KB. `seq` empieza en 0 y sube de a uno por trozo; enviar el mismo `seq` otra vez reemplaza el trozo.

El motor no mira dentro de `events`: el enmascarado ocurre en el navegador, antes de enviar nada. Lo que sí hace el motor es rechazar un trozo cuya `route` coincide con una de las `replay.blocked_routes` del proyecto, así una ruta que apagaste sigue apagada aunque alguien tenga abierta una pestaña con un SDK viejo.

**Autenticación:** Llave de ingesta

**Cuerpo:**

- `sid` (string, obligatorio): Id de sesión: 32 caracteres hex aleatorios en minúscula, creados por el SDK del navegador y compartidos por todas las pestañas del mismo navegador (`localStorage`, clave `sypnia:session`). Uno nuevo tras 30 minutos sin actividad, o cuando se identifica a otra persona.
- `seq` (integer, 0 a 719, obligatorio): El número del trozo en la sesión, desde 0. Enviar el mismo número otra vez reemplaza el trozo.
- `ts_start` (number, opcional): Hora del primer cambio grabado en el trozo, en milisegundos desde 1970-01-01 UTC.
- `ts_end` (number, opcional): Hora del último cambio grabado en el trozo.
- `route` (string, hasta 500 caracteres, opcional): La ruta con los ids reemplazados por `:id`, para que `/orders/8841` y `/orders/8842` sean una sola ruta. Un segmento se vuelve `:id` cuando es todo dígitos, un UUID, un texto hex de 16 caracteres o más, un token de 20 caracteres o más que contiene un dígito, o contiene `%`.
- `url` (string, hasta 500 caracteres, opcional): La ruta de la página cuando se abrió el trozo.
- `vw` (number, opcional): Ancho de la ventana cuando se abrió el trozo.
- `vh` (number, opcional): Alto de la ventana cuando se abrió el trozo.
- `full` (boolean, opcional): True cuando el trozo trae una copia completa de la página.
- `mask` (integer, 1 a 9, opcional): Qué reglas de enmascarado aplicó el SDK antes de enviar: 1 las de siempre (todo lo escrito se enmascara, el texto de la página como se ve, los elementos marcados se enmascaran o se dejan fuera), 2 `maskAllText` (además, todo el texto de la página).
- `events` (lista de object, obligatorio): Los cambios grabados, en el formato propio de la grabadora (eventos de rrweb). Opacos para el motor.

**Petición:**

```bash
curl -X POST "https://ingest.sypnia.com/v1/ingest/replay?key=spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e" \
  -H "Content-Type: application/json" \
  --data-binary @chunk.json.gz
```

**Cuerpo de la petición:**

```json
{
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "seq": 3,
  "ts_start": 1773311497000,
  "ts_end": 1773311507000,
  "route": "/checkout",
  "url": "/checkout",
  "vw": 1440,
  "vh": 900,
  "full": false,
  "mask": 1,
  "events": [
    {
      "type": 3,
      "timestamp": 1773311503000,
      "data": {
        "source": 2,
        "type": 2,
        "id": 418,
        "x": 912,
        "y": 640
      }
    }
  ]
}
```

**Respuesta (200):**

```json
{
  "stored": true
}
```

**Errores:**

- `400` `invalid_body`: El cuerpo no es JSON, o falta `sid`, `seq` o `events`, o están mal formados.
- `401` `unauthorized`: Falta la llave de ingesta, es desconocida o está revocada.
- `403` `not_recordable`: La `route` del trozo está en las `replay.blocked_routes` del proyecto. No reintentes.
- `413` `payload_too_large`: El cuerpo pesa más de 4.000.000 de bytes después de descomprimirlo.
- `422` `session_full`: La sesión ya tiene 720 trozos. El SDK deja de grabar esta sesión.
- `429` `limit_reached`: El proyecto llegó a su límite de grabaciones. La respuesta trae `slow_down`. Los eventos se siguen aceptando.

## Enviar una captura de página

`POST /v1/ingest/snapshot` \[Motor, Nube]

Guarda una captura de una página, con el mismo enmascarado que las grabaciones. Sobre ella se dibujan los mapas de clics. El SDK toma como máximo una por ruta en una sesión, en una parte de las sesiones (`snapshots.sample_rate`, 0.5 por defecto), dos segundos después de que la página queda quieta.

**Autenticación:** Llave de ingesta

**Cuerpo:**

- `sid` (string, obligatorio): Id de sesión: 32 caracteres hex aleatorios en minúscula, creados por el SDK del navegador y compartidos por todas las pestañas del mismo navegador (`localStorage`, clave `sypnia:session`). Uno nuevo tras 30 minutos sin actividad, o cuando se identifica a otra persona.
- `route` (string, hasta 500 caracteres, obligatorio): La ruta con los ids reemplazados por `:id`, para que `/orders/8841` y `/orders/8842` sean una sola ruta. Un segmento se vuelve `:id` cuando es todo dígitos, un UUID, un texto hex de 16 caracteres o más, un token de 20 caracteres o más que contiene un dígito, o contiene `%`.
- `url` (string, hasta 500 caracteres, opcional): La ruta de la página.
- `dev` (string, opcional, por defecto `desktop`): Clase de dispositivo del navegador que la tomó. Uno de: `mobile`, `tablet`, `desktop`.
- `vw` (number, opcional): Ancho de la ventana.
- `vh` (number, opcional): Alto de la ventana.
- `ph` (number, opcional): Alto completo de la página, en píxeles.
- `ts` (number, opcional): Cuándo se tomó, en milisegundos desde 1970-01-01 UTC.
- `mask` (integer, 1 a 9, opcional): Qué reglas de enmascarado aplicó el SDK antes de enviar: 1 las de siempre (todo lo escrito se enmascara, el texto de la página como se ve, los elementos marcados se enmascaran o se dejan fuera), 2 `maskAllText` (además, todo el texto de la página).
- `snapshot` (object, obligatorio): El árbol de la página, en el formato propio de la grabadora (una captura de rrweb). Opaco para el motor.

**Petición:**

```bash
curl -X POST "https://ingest.sypnia.com/v1/ingest/snapshot?key=spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e" \
  -H "Content-Type: application/json" \
  --data-binary @snapshot.json.gz
```

**Cuerpo de la petición:**

```json
{
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "route": "/checkout",
  "url": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "ph": 1630,
  "ts": 1773311490000,
  "mask": 1,
  "snapshot": {
    "type": 0,
    "childNodes": [],
    "id": 1
  }
}
```

**Respuesta (200):**

```json
{
  "stored": true
}
```

**Errores:**

- `400` `invalid_body`: El cuerpo no es JSON, o falta `sid`, `route` o `snapshot`, o están mal formados.
- `403` `not_recordable`: La `route` de la captura está en las `replay.blocked_routes` del proyecto.
- `413` `payload_too_large`: El cuerpo pesa más de 4.000.000 de bytes después de descomprimirlo. El SDK descarta por su cuenta las capturas de más de 3 MB.

## Leer lo que debe hacer el SDK

`GET /v1/ingest/config` \[Motor, Nube]

El SDK llama a este endpoint una vez por sesión para conocer las reglas de grabación del proyecto, así las puedes cambiar sin volver a publicar tu app. Pasa la persona y la cuenta cuando las sepas: una regla de «grabar siempre» para cualquiera de las dos pone `replay.mode` en `record`.

`replay.mode` es la decisión para esta sesión:

| Modo     | Qué hace el SDK                                                                                                                                                                                                               |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `record` | Sube la grabación desde el comienzo. Se elige para la parte de `sample_rate` y para las reglas de «grabar siempre»                                                                                                            |
| `buffer` | Guarda en memoria los últimos 30 segundos y los sube, junto con todo lo que sigue, en el momento en que la sesión tiene un error, un clic de rabia o un clic muerto. Así es como toda sesión con un error queda con grabación |
| `off`    | No graba nada. El proyecto apagó la grabación, o llegó a su límite de grabaciones                                                                                                                                             |

Si esta llamada falla, el SDK usa `buffer`.

**Autenticación:** Llave de ingesta

**Parámetros de consulta:**

- `sid` (string, obligatorio): El id de la sesión. La decisión es estable para una sesión: el mismo `sid` siempre recibe la misma respuesta.
- `person` (string, hasta 128 caracteres, opcional): El id de la persona, si tu app la identificó.
- `account` (string, hasta 128 caracteres, opcional): El id de la cuenta, si tu app envió una.

**Petición:**

```bash
curl "https://ingest.sypnia.com/v1/ingest/config?sid=8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0&person=u_1042" \
  -H "Authorization: Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e"
```

**Respuesta (200):**

```json
{
  "replay": {
    "mode": "buffer",
    "sample_rate": 0.1,
    "mask_all_text": false,
    "blocked_routes": [
      "/account/cards"
    ]
  },
  "snapshots": {
    "sample_rate": 0.5
  },
  "slow_down": null
}
```

## Cargar el SDK del navegador

`GET /v1/sdk.js` \[Motor, Nube]

El SDK del navegador en un solo script, para una página sin paso de build. Es el archivo que carga la etiqueta script: `<script async src="https://ingest.sypnia.com/v1/sdk.js" data-project="spk_…"></script>`. Es el mismo código del paquete de npm `@sypnia/browser`, armado para correr directo. Lo sirve el propio motor, así que un motor alojado por ti no necesita otro servidor: usa `<tu URL base>/v1/sdk.js`.

No necesita credencial y se puede cargar desde cualquier origen. La llave de ingesta no va en la petición: el script la lee de su propio atributo `data-project`, o de tu llamada a `init`.

**Versiones.** Sin `v` recibes el SDK más nuevo de la versión mayor 1 que tenga el motor. Dentro de una versión mayor el SDK solo agrega, igual que el contrato de eventos, así que una página nunca tiene que cambiar su etiqueta. Sypnia Cloud tiene todas las versiones 1.x publicadas; un motor alojado por ti tiene aquella con la que salió. Para fijar una versión, pídela con `v`.

**Caché.** El archivo sin versión fija se guarda en caché una hora (`Cache-Control: public, max-age=3600, stale-while-revalidate=86400`) y trae un `ETag`. Una versión fija nunca cambia y se guarda un año (`immutable`). El encabezado de respuesta `Sypnia-SDK-Version` dice qué versión se sirvió.

La grabadora para grabaciones y capturas de página es un segundo archivo, `/v1/sdk-recorder.js`, que el SDK carga por su cuenta cuando el navegador está desocupado, con las mismas reglas. Tú nunca lo referencias.

**Autenticación:** Ninguna. Es público

**Parámetros de consulta:**

- `v` (string, opcional): Una versión exacta del SDK, como `1.4.2`, para fijar el archivo. Sin ella se sirve la 1.x más nueva.

**Petición:**

```bash
curl -I "https://ingest.sypnia.com/v1/sdk.js"
```

**Respuesta (200):**

```http
HTTP/2 200
content-type: text/javascript; charset=utf-8
cache-control: public, max-age=3600, stale-while-revalidate=86400
etag: "1.4.2-9f3c2a"
sypnia-sdk-version: 1.4.2
access-control-allow-origin: *
```

**Errores:**

- `404` `not_found`: `v` nombra una versión que este motor no tiene. Un motor alojado por ti solo tiene la versión con la que salió.

Los errores que cualquier endpoint puede responder (`401`, `403`, `429`, `500`, `503`) están en [Errores, límites, paginación](https://docs.sypnia.com/es/api/errors-limits-pagination).
