Bhawk · Contrato de integración

Este contrato describe cómo tu sistema le pide a Bhawk que evalúe el riesgo — el halcón que vigila tu cumplimiento SARLAFT. Incluye operaciones, costos en Açaí, payloads y eventos.

Note

Las evaluaciones son asíncronas por defecto (202 Accepted + webhook). Para casos sincrónicos críticos (decisión inline durante checkout) usa el header X-Bjungle-Sync: true — incrementa el costo en 2× Açaí por respuesta inline.

Operaciones disponibles

Operación	Endpoint	Plano	Costo
Crear regla SARLAFT	POST /v1/rules	Control	0 Açaí
Evaluar un subject	POST /v1/evaluations	Data	8 Açaí (+ 5 Açaí por lista cruzada)
Evaluar transacción individual	POST /v1/evaluations/transaction	Data	1 Açaí
Sincronizar lista restrictiva	POST /v1/lists/{code}/sync	Control	0 Açaí
Consultar evaluación	GET /v1/evaluations/{id}	Data	1 Açaí

Flujo end-to-end

1. Definir reglas desde el Rule Builder (UI) o por API (POST /v1/rules).
2. Configurar listas restrictivas (OFAC, ONU, propias) en el Control Plane.
3. Tu app llama POST /v1/evaluations con la referencia al subject y datos contextuales.
4. Bhawk evalúa en background — ejecuta el motor de reglas + cruces de listas.
5. Recibes webhook bhawk.evaluation.completed con la decisión y los findings.
6. Tu lógica de negocio actúa según decision (approve / review / reject).

1. Solicitar evaluación

Request

POST /v1/evaluations HTTP/1.1
Host: api.digital-jungle.bjungle.com
X-API-Key: <api_key>
Content-Type: application/json

{
  "subject_ref": "0c4b5b32-3a89-4a45-9c2c-1a8c47e91234",
  "context": {
    "monto_solicitado":    5000000,
    "moneda":              "COP",
    "producto":            "microcredito",
    "canal":               "digital",
    "ip":                  "190.158.20.10"
  },
  "lists": ["ofac", "onu", "pep_colombia"],
  "rules_set": "originacion-v2"
}

Response — 202 Accepted

{
  "evaluation_id": "01J8G02H3M4P5Q6R7S8T9V0W1X",
  "status":        "pending",
  "acai_debited": 23
}

Webhook resultado — bhawk.evaluation.completed

{
  "event_id":   "5f8d1c3e-4c01-4d6e-8a9d-5e8c8b5f5678",
  "tenant_id":  "8a7b6c5d-1234-5678-9abc-def012345678",
  "module":     "bhawk",
  "event_type": "bhawk.evaluation.completed",
  "occurred_at":"2026-05-25T14:00:03Z",
  "payload": {
    "evaluation_id": "01J8G02H3M4P5Q6R7S8T9V0W1X",
    "subject_ref":   "0c4b5b32-3a89-4a45-9c2c-1a8c47e91234",
    "score":         42.5,
    "decision":      "review",
    "findings": [
      {
        "rule_code":  "monto-vs-ingreso",
        "severity":   "medium",
        "detail":     "Monto solicitado supera 3x ingresos declarados",
        "score_delta": 25
      },
      {
        "rule_code":  "list-match",
        "severity":   "low",
        "list":       "pep_colombia",
        "detail":     "Match parcial (apellido + ciudad)",
        "score_delta": 17.5
      }
    ]
  }
}

Snippets

cURL

curl -X POST https://api.digital-jungle.bjungle.com/v1/evaluations \
  -H "X-API-Key: $BHAWK_KEY" \
  -H "Content-Type: application/json" \
  -d @evaluation.json

TypeScript

import { BhawkClient } from '@bjungle/bhawk-client';

const bhawk = new BhawkClient({ apiKey: process.env.BHAWK_KEY! });

const res = await bhawk.evaluations.create({
  subject_ref: subjectId,
  context:     { monto_solicitado: 5_000_000, moneda: 'COP', producto: 'microcredito' },
  lists:       ['ofac', 'onu', 'pep_colombia'],
  rules_set:   'originacion-v2',
});

console.log(res.evaluation_id);

Go

client := bhawk.NewClient(os.Getenv("BHAWK_KEY"))
res, err := client.Evaluations.Create(ctx, &bhawk.EvaluationInput{
    SubjectRef: subjectID,
    Context:    map[string]any{"monto_solicitado": 5_000_000, "moneda": "COP"},
    Lists:      []string{"ofac", "onu", "pep_colombia"},
    RulesSet:   "originacion-v2",
})

Sync inline

# Evaluación sincrónica (decisión inline) — añade header X-Bjungle-Sync
curl -X POST https://api.digital-jungle.bjungle.com/v1/evaluations \
  -H "X-API-Key: $BHAWK_KEY" \
  -H "X-Bjungle-Sync: true" \
  -H "Content-Type: application/json" \
  -d @evaluation.json
# → 200 OK con el resultado completo (no 202)

2. Sincronizar listas restrictivas

POST /v1/lists/ofac/sync HTTP/1.1
Authorization: Bearer <admin_token>

{ "force": false }

Devuelve 202 y emite bhawk.list.synced cuando termina. Por defecto, las listas oficiales se sincronizan automáticamente con el cron declarado en el Control Plane.

Eventos emitidos

Evento	Cuándo
bhawk.evaluation.completed	La evaluación terminó (cualquiera sea la decisión)
bhawk.alert.raised	Un finding con severity=critical requiere atención inmediata
bhawk.list.synced	Una lista restrictiva fue actualizada

Errores típicos

Status	Caso
400	Payload inválido o rules_set desconocido
404	subject_ref no existe en Bmonkey (cuando se valida cross-app)
402	Sin Açaí disponibles para la operación
409	Evaluación pendiente para el mismo subject_ref con Idempotency-Key repetida
422	Una lista referenciada no está activa