API de NTL Events

Primeros pasos

1. En el panel de NTL Events, entra a Seguridad → API y webhooks. Solo el dueño de la cuenta crea llaves, y necesita el doble factor activo.
2. Elige los permisos que necesita la integración (leer y escribir van por separado) y, si quieres, un vencimiento. Copia la llave: se muestra una sola vez.
3. Mándala como token bearer en cada petición.

curl https://ntl.events/api/v1/events \
  -H "Authorization: Bearer ntl_live_…"

curl https://ntl.events/api/v1/registrations \
  -H "Authorization: Bearer ntl_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-2027-000123" \
  -d '{
    "event_id": "8c3f…",
    "registration_type_id": "1f0a…",
    "buyer": { "name": "Ingrid Halvorsen", "email": "ingrid@example.org" },
    "answers": { "organization": "Norwegian Defence Research Establishment" }
  }'

Autenticación y permisos

Manda Authorization: Bearer ntl_live_… (o X-API-Key). Una llave que falta, no es válida, venció o se revocó responde 401; una llave sin el permiso necesario responde 403. Las llaves se guardan como huella SHA-256: una llave perdida no se recupera, se revoca y se crea otra.

Paginación

Las listas devuelven { object: "list", data, has_more, next_cursor }, de lo más nuevo a lo más viejo. Manda next_cursor como starting_after para la página siguiente. limit va de 1 a 100 (25 por omisión). El cursor es estable aunque entren registros nuevos mientras paginas.

curl "https://ntl.events/api/v1/registrations?event_id=8c3f…&limit=100&starting_after=eyJ0Ijoi…" \
  -H "Authorization: Bearer ntl_live_…"

Errores

Todos los errores tienen la misma forma. type es la familia estable contra la que se programa; code es el caso concreto; request_id le sirve a soporte para encontrar la petición.

HTTP/1.1 409 Conflict
{
  "error": {
    "type": "conflict_error",
    "code": "sold_out",
    "message": "Not enough capacity left in this registration type.",
    "request_id": "req_3f9c…"
  }
}

Límites de uso

Cada llave permite 120 peticiones por minuto. Toda respuesta trae X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset; un 429 trae Retry-After.

Idempotencia

Manda el encabezado Idempotency-Key en los POST. Si la red falla y reintentas con la misma clave, recibes la respuesta original (con Idempotent-Replayed: true) en vez de un registro o check-in duplicado. Reusar la clave con otro cuerpo responde 422. Las claves se guardan 24 horas.

Montos y fechas. Los montos son enteros en unidades menores (centavos) con su moneda ISO 4217. Las fechas van en ISO 8601, UTC.

Webhooks

Registra en el panel una URL HTTPS y los eventos que te interesan. Cada entrega es un POST firmado con el mismo objeto que devuelve la API para ese recurso. Responde 2xx en menos de 10 segundos. Si falla, se reintenta a los 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h — 8 intentos en total — y cualquier entrega se puede reintentar a mano desde el panel.

Tipos de evento

• registration.created — Registro confirmado
• registration.cancelled — Registro cancelado o reembolsado
• payment.completed — Pago completado
• checkin.created — Check-in registrado
• abstract.decided — Decisión sobre un abstract

Cómo verificar la firma

NTL-Signature: t=<segundos unix>,v1=<hex> donde v1 = HMAC-SHA256(tu secreto whsec_, "<t>.<cuerpo crudo>"). Compara en tiempo constante y rechaza si la marca de tiempo difiere más de 5 minutos de tu reloj. Usa el cuerpo crudo, antes de interpretar el JSON.

// Node.js
import crypto from "node:crypto";

export function verifyNtlSignature(secret, header, rawBody, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = Buffer.from(crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex"), "hex");
  const received = Buffer.from(parts.v1 ?? "", "hex");
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

POST /your/endpoint
NTL-Signature: t=1789200000,v1=5f2b…
NTL-Event-Type: registration.created
NTL-Event-Id: evt_9a1c…

{
  "id": "evt_9a1c…",
  "object": "event",
  "type": "registration.created",
  "created": 1789200000,
  "data": { "object": { "id": "…", "object": "registration", "status": "confirmed", "attendees": [ … ] } }
}

Referencia de la API

La referencia está en inglés y se genera del mismo documento OpenAPI que sirve la API.

Objetos