Vigilae Connect

Una API que se puede leer antes de firmar.

La especificación es pública, las superficies son neutras, la firma de los webhooks puede verificarse en diez líneas de su lado. Esta página documenta lo que la API expone hoy — nada más, y es deliberado: lo que no está en producción no se documenta.

Especificación OpenAPI legible sin clave ni cuenta
Nunca una comunicación de operación sospechosa, nunca datos literales de clientes
Webhooks firmados, verificables fuera de Vigilae

Leer la especificación Referencia de errores

Servida por la propia API: el contrato que usted lee es el que se ejecuta.

El perímetro

Superficies neutras, por construcción.

La API expone lo que un integrador puede consumir sin tocar el secreto de los expedientes: el diario de seguimiento y los contadores. El contenido de un expediente de diligencia debida, los documentos, las comunicaciones de operación sospechosa no transitan por esta API — no es una limitación del plan, es la arquitectura.

Diario de seguimiento

Los eventos pKYC del despacho — documento caducado, cambio de titular real, recribado pendiente de revisión — en forma neutra: secuencia, tipo, severidad, fecha. Respuestas siempre acotadas a 500 eventos.

Agregados de cartera

Contadores, nunca un expediente: volúmenes por estado, plazos, completitud. Lo justo para pintar un panel en su herramienta sin que entre en ella un solo dato de cliente.

Calificación

La única escritura: calificar un evento del diario (estado qualifie o clos, disposición planifie, traite o ecarte). Requiere el scope de escritura — el mínimo privilegio es la regla, no una opción.

La API está pensada de servidor a servidor: una clave en código enviado al navegador es una clave publicada. Que la clave la custodie un proxy en su servidor, nunca la página.

Claves

Claves con scopes delimitados, mostradas una sola vez, revocables al instante.

Formato. Toda clave empieza por vgk_ y se envía como Authorization: Bearer vgk_…. El secreto se muestra solo en la creación: no conservamos más que su huella SHA-256.
Scopes. lecture (lectura, por defecto) y ecriture (escritura). Una clave sin el scope requerido recibe un 403 — véase #scopes.
Caducidad. Un año después de la creación (visible en la consola del despacho). Una clave caducada recibe un 401 explícito — véase #cle-expiree.
Límite de peticiones. 60 solicitudes por minuto y clave (ajustable clave por clave). Un 429 lleva Retry-After y las cabeceras X-RateLimit-Limit / -Remaining / -Reset.
Revocación. Inmediata, desde la consola. La resolución se hace por huella: las claves no pueden enumerarse.

Inicio rápido

Tres llamadas curl y lo ha visto todo.

# Salud + autenticación de la clave
curl -s https://vigilae.org/api/v1/sante \
  -H "Authorization: Bearer vgk_your_key"

# Diario de seguimiento, desde el principio, en páginas de 100
curl -s "https://vigilae.org/api/v1/evenements?depuisSeq=0&limite=100" \
  -H "Authorization: Bearer vgk_your_key"

# Calificar el evento 42 (scope de escritura)
curl -s -X POST https://vigilae.org/api/v1/evenements/42/qualifier \
  -H "Authorization: Bearer vgk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"statut":"qualifie","disposition":"traite"}'

La paginación, en una regla

Pase depuisSeq (0 en la primera llamada) y limite (con tope de 500): la respuesta viene ordenada por seq ascendente y devuelve prochainSeq, que se reenvía tal cual en la llamada siguiente. Una página más corta que limite significa el final del diario — prochainSeq se mantiene entonces estable y sirve de cursor de sondeo. Sin depuisSeq, obtiene la vista «lo más reciente primero», acotada a 500.

La cartera se consulta en /api/v1/portefeuille/agregats — contadores, una respuesta, sin paginación.

Webhooks

Firmados, con marca de tiempo, entregados al menos una vez.

En lugar de sondear el diario, recíbalo: Vigilae entrega los eventos en su URL, en orden, en lotes de 100 como máximo. La entrega es at-least-once — el cursor solo avanza con su 2xx, lote a lote — y la idempotencia va por seq: procese cada secuencia exactamente una vez (#idempotence).

Verificar la firma

Cada entrega lleva la cabecera x-vigilae-signature: t=<unix>,v1=HMAC-SHA256(secret, t + "." + body). Recalcule v1 a partir del cuerpo bruto recibido y rechace toda marca de tiempo t más allá de 5 min: ese es el anti-replay. Durante una rotación del secreto, la cabecera lleva un v1 por cada secreto aún válido (solapamiento de 24 h): acepte si cualquiera de ellos coincide.

// Node — verificación de la firma (sin dependencias)
import { createHmac, timingSafeEqual } from 'node:crypto';

export function signatureValid(header, rawBody, secrets, toleranceMs = 5 * 60 * 1000) {
  const t = Number((/(?:^|,)t=(\d+)/.exec(header) || [])[1]);
  if (!t || Math.abs(Date.now() - t * 1000) > toleranceMs) return false; // anti-replay
  const received = [...header.matchAll(/v1=([0-9a-f]{64})/g)].map((m) => m[1]);
  return [].concat(secrets).some((secret) => {
    const expected = createHmac('sha256', secret).update(t + '.' + rawBody).digest('hex');
    return received.some((r) => r.length === expected.length
      && timingSafeEqual(Buffer.from(r), Buffer.from(expected)));
  });
}

# Python — la misma verificación
import hmac, hashlib, re, time

def signature_valid(header: str, raw_body: bytes, secrets, tolerance_s: int = 300) -> bool:
    m = re.search(r"(?:^|,)t=(\d+)", header)
    if not m or abs(time.time() - int(m.group(1))) > tolerance_s:
        return False  # anti-replay
    received = re.findall(r"v1=([0-9a-f]{64})", header)
    for secret in secrets:
        expected = hmac.new(secret.encode(), m.group(1).encode() + b"." + raw_body,
                            hashlib.sha256).hexdigest()
        if any(hmac.compare_digest(expected, r) for r in received):
            return True
    return False

Transitorio: el formato antiguo sha256=HMAC(body) se sigue emitiendo en x-vigilae-signature-legacy para los receptores ya desplegados; su retirada está prevista con los webhooks v2. Los receptores nuevos verifican el esquema con marca de tiempo de arriba, no el antiguo.

La rotación se lanza desde la consola (POST /connect/webhook/rotation del lado de la aplicación): durante 24 h el secreto antiguo sigue firmando — tiempo para desplegar el nuevo de su lado sin ventana de fallo.

Entorno de pruebas

Sandbox: bajo petición.

Todavía no hay sandbox en autoservicio — preferimos decírselo aquí antes que dejar que lo descubra. Escriba a contact@vigilae.org (asunto «Acceso API»): abrimos un despacho de prueba con datos ficticios mientras dure su integración, y seguimos localizables mientras avanza.

Cada clase de error de la API tiene una dirección estable en la referencia de errores: #authentification, #scopes, #cloisonnement, #debit, #signature… Las respuestas de error de la API apuntarán a estas anclas.

La API no expone ni comunicaciones de operación sospechosa ni datos literales de clientes, por construcción (art. L.561-18 del CMF francés). Ninguna decisión de diligencia la toma la API: expone y califica eventos; el profesional decide.