API IQ Suite

Quick start

En menos de 2 minutos podés hacer tu primera llamada. El flujo es:

1. Iniciá sesión en tu portal y andá a /cliente/integraciones
2. Click Crear API Key, ponele un nombre y elegí los scopes
3. Copiá el valor que empieza con iqs_live_... (se muestra una sola vez)
4. Probala:

curlcurl https://www.iqsuite.lat/v1/me \
  -H "X-API-Key: iqs_live_TUKEYAQUI"

Si todo está OK vas a recibir tu tenant context:

json{
  "tenant": {
    "id": "a9d9...",
    "name": "IQ Suite Demo",
    "slug": "demo",
    "type": "BARRIO",
    "status": "ACTIVE",
    "products": ["IQ_ENTRY", "IQ_VISIT", "IQ_ACCESS"]
  },
  "api_key": {
    "prefix": "iqs_live_xxx",
    "scopes": ["visitors.read"],
    "rate_limit_per_min": 60
  }
}

Autenticación

Todas las requests requieren el header X-API-Key: iqs_live_.... Las keys se crean por tenant y se asocian a un set de scopes que limitan qué pueden hacer.

Scopes disponibles

Errores de auth

• 401 Missing X-API-Key header — falta el header
• 401 Invalid API key — key inválida, revocada o expirada
• 403 Missing scope: ... — la key no tiene el scope requerido

Códigos de error

Todas las respuestas non-2xx devuelven JSON con un campo { "error": "..." }.

Rate limits

Cada API Key tiene un límite configurable (default: 60 req/min). Cuando se excede, recibís HTTP 429 y debés esperar antes de reintentar.

Para clientes enterprise con alto volumen el límite puede subirse hasta 10000 req/min editando la key desde el panel.

Visitors

Listar (GET /v1/visitors)

Query params:

• limit 1–100, default 25
• offset default 0
• status PENDING | ACTIVE | USED | EXPIRED | REVOKED
• site_id filtrar por sitio
• q búsqueda por nombre/dni/email
• from / to rango de created_at (ISO date)

curlcurl "https://www.iqsuite.lat/v1/visitors?limit=10&status=ACTIVE" \
  -H "X-API-Key: iqs_live_..."

Crear (POST /v1/visitors)

Body:

json{
  "visitor_name": "Juan Pérez",        // requerido
  "site_id": "uuid",                    // requerido
  "qr_type": "SINGLE_USE",              // SINGLE_USE | TIME_WINDOW | RECURRING | PERMANENT
  "visitor_dni": "30123456",            // opcional
  "visitor_email": "juan@example.com",  // opcional
  "visitor_phone": "+5491155667788",    // opcional
  "company_name": "Proveedor X",        // opcional
  "destination": "Oficina 302",         // opcional
  "valid_from": "2026-04-26T10:00:00Z", // requerido si TIME_WINDOW/RECURRING
  "valid_until": "2026-04-26T18:00:00Z" // requerido si TIME_WINDOW/RECURRING
}

Respuesta 201:

json{
  "data": {
    "id": "uuid",
    "qr_code": "uuid",
    "visitor_name": "Juan Pérez",
    "status": "ACTIVE",
    "..." : "..."
  },
  "qr_url": "https://iqsuite.lat/v/<qr_code>"
}

Side effect: dispara el webhook visitor.created a todos los endpoints suscriptos.

Access Logs

Query params adicionales: event_type, method, visitor_id, user_id.

curlcurl "https://www.iqsuite.lat/v1/access-logs?from=2026-04-01&event_type=GRANTED" \
  -H "X-API-Key: iqs_live_..."

Devices

Status posibles: ONLINE, OFFLINE, ERROR, UNLINKED, PRE_PROVISIONED.

curlcurl "https://www.iqsuite.lat/v1/devices?status=ONLINE" \
  -H "X-API-Key: iqs_live_..."

Webhooks salientes

Configurá un endpoint HTTPS en tu sistema y suscribite a eventos. IQ Suite te enviará un POST cada vez que ocurra el evento, firmado con HMAC-SHA256 usando un secret per-suscripción.

Eventos disponibles

• visitor.created, visitor.updated, visitor.revoked
• access.granted, access.denied
• device.online, device.offline, device.command.executed
• payment.succeeded, payment.failed
• incident.created, incident.resolved
• subscription.created, subscription.cancelled

Headers que recibís

POST https://tu-endpoint.com/iq-webhooks
Content-Type: application/json
User-Agent: IQSuite-Webhooks/1.0
X-IQ-Event: visitor.created
X-IQ-Signature: sha256=abc123...
X-IQ-Delivery-Id: uuid-...
X-IQ-Timestamp: 2026-04-25T17:24:12.591Z

Verificar la firma (Node.js)

javascriptimport crypto from 'crypto'
import express from 'express'

const app = express()
app.use(express.raw({ type: 'application/json' }))

app.post('/iq-webhooks', (req, res) => {
  const signature = req.headers['x-iq-signature']
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.IQ_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex')

  if (signature !== expected) {
    return res.status(401).send('invalid signature')
  }

  const event = JSON.parse(req.body.toString())
  console.log(event.event, event.data)

  // Procesar el evento aquí (push to Slack, save in SAP, etc)

  res.status(200).send('ok')
})

Verificar la firma (Python)

pythonimport hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)

@app.post('/iq-webhooks')
def webhook():
    signature = request.headers.get('X-IQ-Signature', '')
    expected = 'sha256=' + hmac.new(
        os.environ['IQ_WEBHOOK_SECRET'].encode(),
        request.data,
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        abort(401)

    event = request.get_json()
    # Procesar event['event'], event['data']
    return ('', 200)

Política de retries

Si tu endpoint responde algo distinto de 2xx, IQ Suite reintenta con backoff exponencial:

Intento 1: inmediato
Intento 2: +1 minuto
Intento 3: +5 minutos
Intento 4: +30 minutos
Intento 5: +2 horas
Intento 6: +12 horas
→ después marca DEAD_LETTER

Tras 10 fallos consecutivos en una suscripción, ésta queda paused automáticamente y el cliente debe reactivarla manualmente desde el panel.

SDKs

Próximamente publicamos SDKs oficiales para los lenguajes más comunes. Mientras tanto, cualquier HTTP client funciona — la API es estándar REST.

• Node.js / TypeScript — @iqsuite/sdk (Q3 2026)
• Python — iqsuite (Q3 2026)
• Go — github.com/iqsuite/go-sdk (Q4 2026)
• PHP — iqsuite/php-sdk (Q4 2026)