Documentación de Prynt Gate

Referencia de la API

URL base `https://api.pryntid.com`. JSON en camelCase; la entrada de eventos también acepta snake_case.

Autenticación

Authorization: Bearer <token> con un token de sensor (gk_<env>_…, limitado a /v1/gate/* de ese sensor) o la clave secreta del entorno (sk_<env>_…, con sensor en el cuerpo; un nombre nuevo da de alta el sensor).

EstadoSignificado
401 unauthorizedtoken inválido o sensor desactivado
402 product_requiredla cuenta no tiene plan de Gate
413 payload_too_largecuerpo de más de 1 MB
422 validation_errorcuerpo mal formado
429 rate_limited · quota_exceeded600 peticiones/min por sensor, o eventos del mes agotados

POST /v1/gate/events

Hasta 500 eventos por petición, como {sensor, events: […]}, un array JSON o NDJSON. Idempotente por eventId (se deriva del evento si falta).

POST https://api.pryntid.com/v1/gate/events
Authorization: Bearer gk_live_YOUR_SENSOR_TOKEN
Content-Type: application/json

{
  "sensor": "gps-01",
  "events": [{
    "eventId": "tr-5027-0001",
    "ts": "2026-11-15T18:02:11Z",
    "host": "gps-gateway",
    "port": 5027,
    "protocol": "teltonika",
    "transport": "tcp",
    "srcIp": "203.0.113.7",
    "srcPort": 51234,
    "claimedIdentity": {"type": "imei", "value": "356307042441013"},
    "outcome": "unknown_id",
    "metadata": {"parser": "traccar"}
  }]
}
CampoNotas
srcIpobligatorio; IPv4 o IPv6
tsISO 8601 o epoch (s o ms); por defecto, la hora de recepción
claimedIdentity{type, value}: imei, panel_account, username, email, ssh_key_fp, turn_user, device_id, mac, other…
port · protocol · transportpuerto local, nombre del protocolo, tcp o udp
metadataobjeto libre de hasta 4 KB (payloadPrefix alimenta el detector de escáneres)
`outcome`Significado
connectsesión TCP/UDP abierta
auth_okla identidad declarada fue aceptada
auth_failcontraseña, clave o firma incorrecta
unknown_idla identidad no existe en tu servidor
disconnectsesión cerrada
data · errortráfico o error de protocolo en una sesión abierta

Respuesta:

{
  "accepted": 1, "duplicates": 0, "rejected": [],
  "decisions": [{"eventId": "tr-5027-0001", "decision": "block", "score": 90,
                 "reasons": ["enumeration:6"], "srcIp": "203.0.113.7"}],
  "blocks": [{"id": 12, "ip": "203.0.113.7", "expiresAt": "2026-11-15T19:02:11Z", "reason": "enumeration"}]
}

decisions solo lista los eventos marcados o bloqueados. Cada evento aceptado cuenta uno de la cuota mensual.

POST /v1/gate/logs

Líneas de log en crudo, procesadas en el servidor: ver Fuentes de logs.

GET /v1/gate/blocks

La lista completa de bloqueos activos para el bouncer, el modo del sensor y la lista de permitidos. version solo cambia cuando cambia la lista.

GET https://api.pryntid.com/v1/gate/blocks
Authorization: Bearer gk_live_YOUR_SENSOR_TOKEN

{
  "mode": "enforce",
  "blocks": [{"id": 12, "ip": "203.0.113.7", "reason": "enumeration",
              "expiresAt": "2026-11-15T19:02:11Z", "createdAt": "2026-11-15T18:02:11Z"}],
  "allowlist": ["192.168.1.0/24", "10.0.0.1/32"],
  "version": "b3f1…",
  "serverTime": "2026-11-15T18:05:00Z"
}

POST /v1/gate/heartbeat

POST https://api.pryntid.com/v1/gate/heartbeat
Authorization: Bearer gk_live_YOUR_SENSOR_TOKEN

{"agentVersion": "0.1.0", "hostname": "gps-gateway", "mode": "dry_run", "backend": "nftables",
 "appliedBlocks": 3, "parsers": ["traccar"], "spooled": 0}

Detectores y puntuación

Cada evento se enriquece sin conexión externa (país, ciudad, ASN y su operador, VPN, hosting, Tor, listas de abuso) y pasa por estos detectores. Umbrales, ventanas y acciones se editan en Gate → Ajustes.

DetectorSe activa cuandoPor defecto
enumerationun origen prueba ≥ 5 identidades desconocidas en 10 minblock
authFailBurst≥ 10 fallos de autenticación desde un origen en 5 minblock
identityAuthFail≥ 5 fallos contra una misma identidad en 10 minflag
concurrentSourcesla misma identidad conectada desde 2+ orígenes a la vezflag
newAsn · newCountryuna identidad vista desde una red o país nuevoflag
impossibleTravel> 900 km/h entre dos ubicaciones a más de 500 kmflag
firstSeenuna identidad nunca vistaseñal
portScanun origen toca ≥ 4 puertos en 10 minblock
scannerredes de escáneres conocidas, cargas de escáner, listas de abusoflag
torOrHostinguna identidad de equipo (IMEI, cuenta de panel) desde Tor, VPN o hostingflag
identityBlockeduna identidad que marcaste como bloqueadablock

La puntuación va de 0 a 100 con los motivos que la forman: block desde 80 o cuando un detector o regla bloquea, flag desde 40. Una IP de la lista de permitidos siempre es allow (sus señales se registran igual).

Reglas

Las mismas reglas declarativas que Identify: un campo, un operador (eq, ne, gt, lt, gte, lte, in), un valor y una acción (allow, flag, block), por prioridad; el modo evaluate solo cuenta coincidencias. Campos: idType, outcome, port, protocol, sensor, country, asn, asnType, vpn, tor, hosting, firstSeen, newAsn, newCountry, concurrentSources, unknownIdsFromSource, authFailsFromSource, distinctPortsFromSource, travelKmh, riskScore e identityStatus.

{"name": "Connection from a datacenter", "field": "asnType", "op": "eq", "value": "hosting", "action": "block", "priority": 10}
{"name": "Stricter enumeration", "field": "unknownIdsFromSource", "op": "gte", "value": "3", "action": "block", "priority": 20}
{"name": "Alarm panel abroad", "field": "newCountry", "op": "eq", "value": "true", "action": "flag", "priority": 30}

Una decisión block bloquea la IP de origen durante blockTtlMinutes (60 por defecto; una regla puede fijar el suyo). Las IPs permitidas y las privadas nunca se bloquean automáticamente.

Registro inalterable

Cada evento lleva seq, prevHash y hash = sha256(prevHash + JSON canónico del evento y su decisión), una cadena por cuenta y entorno. No hay API para editar ni borrar eventos. La retención borra los más antiguos y deja un punto de control; la verificación del registro en la consola (GET /admin/gate/log/verify) recalcula la cadena.

Webhooks

Suscribe un endpoint en Webhooks a gate.decision, gate.block.created, gate.block.revoked o gate.alert. Los envíos se firman como todos los webhooks de Prynt: X-Prynt-Signature: sha256=HMAC(secreto, "<X-Prynt-Timestamp>." + cuerpo).

{
  "type": "gate.decision",
  "createdAt": "2026-11-15T18:02:12Z",
  "data": {"eventId": "tr-5027-0001", "decision": "flag", "score": 70,
           "reasons": ["concurrentSources:2"], "identity": {"type": "imei", "value": "356307042441013"},
           "srcIp": "198.51.100.23", "port": 5027, "sensor": "gps-01"}
}
// Node.js: verify X-Prynt-Signature (same scheme as every Prynt webhook)
import crypto from 'node:crypto';

function verify(rawBody, headers, secret) {
  const ts = headers['x-prynt-timestamp'];
  const sig = (headers['x-prynt-signature'] || '').replace('sha256=', '');
  const want = crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  return fresh && sig.length === want.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(want));
}

Siguiente: Ejemplo: GPS y alarmas

Actualizado 2026-11-15 · Referencia de la API