Quickstart · SARLAFT con bhawk

bhawk es el módulo de cumplimiento del ecosistema. Te permite crear sets de reglas SARLAFT versionadas, cruzar contra OpenSanctions (OFAC, ONU, PEP, EU_SANCTIONS, FATF) y operar el workbench de casos para review/reject.

En este quickstart vas a:

1. Seed una validation con plantillas SARLAFT estándar.
2. Publicar la validation.
3. Probarla con dry-run (sin cobrar).
4. Correr un screening real (POST /v1/screenings) que persiste y debita 8 Açaí.
5. Gestionar los casos abiertos.

Consejo

Si ya completaste el quickstart de KYC, el flow default ya integra SARLAFT — los pasos siguientes son para customizar las reglas o llamar bhawk standalone (sin pasar por el flow engine de bmonkey).

---

Setup

export DJ_BASE=https://bhawk.qa.bjungle.net
export DJ_API_KEY=dj_test_...   # misma key que bmonkey

bhawk corre en su propio host (bhawk.qa.bjungle.net), pero usa la misma API key del tenant.

Opción recomendada · @bjungle/sdk (TypeScript)

El SDK enruta cada módulo a su host por separado a partir de baseUrl o moduleUrls. Para integraciones nuevas usá el SDK — tipa request + response, mapea 409/402/422 a errores con clase y agrega Idempotency-Key automático.

npm install @bjungle/sdk

import { BjungleClient } from '@bjungle/sdk';

const dj = new BjungleClient({
  apiKey:  process.env.DJ_API_KEY!,
  baseUrl: 'https://api.qa.bjungle.net',
  moduleUrls: {
    bhawk: 'https://bhawk.qa.bjungle.net',   // mismo tenant, host distinto
  },
});

Nota

Estado del paquete — preview. @bjungle/sdk@0.1.0 está completo y testeado, pero la publicación en npm pública sigue pendiente (TODO Wave E). Usá link local o el registry interno mientras tanto.

---

Paso 1 · Crear una validation draft

Una validation es un grupo versionado de reglas. Ciclo de vida: draft → published → deprecated. Solo los drafts se pueden mutar.

SDK

const validation = await dj.bhawk.validations.create({
  code:        'default',
  name:        'SARLAFT por defecto',
  description: 'Reglas baseline para personas naturales CO',
});
// { id, code, status: 'draft', version: 1, ... }

cURL

curl -X POST "$DJ_BASE/v1/validations" \
  -H "X-API-Key: $DJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code":        "default",
    "name":        "SARLAFT por defecto",
    "description": "Reglas baseline para personas naturales CO"
  }'

JavaScript

const res = await fetch(`${DJ_BASE}/v1/validations`, {
  method:  'POST',
  headers: {
    'X-API-Key':    DJ_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    code:        'default',
    name:        'SARLAFT por defecto',
    description: 'Reglas baseline para personas naturales CO',
  }),
});
const validation = await res.json();   // {id, code, status:'draft', version:1, ...}

Go

body, _ := json.Marshal(map[string]string{
    "code":        "default",
    "name":        "SARLAFT por defecto",
    "description": "Reglas baseline para personas naturales CO",
})
req, _ := http.NewRequest("POST", base+"/v1/validations", bytes.NewReader(body))
req.Header.Set("X-API-Key", apiKey)
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()

Capturá validation.id para el próximo paso.

---

Paso 2 · Seed reglas SARLAFT estándar

bhawk trae un catálogo de plantillas SARLAFT canónicas (PEP, OFAC hit, edad mínima, países de alto riesgo, etc.):

cURL

curl -X POST "$DJ_BASE/v1/rules/seed-defaults" \
  -H "X-API-Key: $DJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"validation_id\": \"$VALIDATION_ID\",
    \"subject_type\":  \"natural\"
  }"

JavaScript

await fetch(`${DJ_BASE}/v1/rules/seed-defaults`, {
  method:  'POST',
  headers: {
    'X-API-Key':    DJ_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    validation_id: validation.id,
    subject_type:  'natural',
  }),
});

Inspeccioná el catálogo crudo si querés filtrar antes de seedear:

curl "$DJ_BASE/v1/templates?subject_type=natural&group=sarlaft" \
  -H "X-API-Key: $DJ_API_KEY" | jq .

subject_type puede ser natural | legal | both. Las plantillas vienen pre-configuradas con severities (approve | review | reject) y scores.

---

Paso 3 · Publicar la validation

SDK

const published = await dj.bhawk.validations.publish(validation.id);
// { id, status: 'published', version: 1, ... }

cURL

curl -X POST "$DJ_BASE/v1/validations/$VALIDATION_ID/publish" \
  -H "X-API-Key: $DJ_API_KEY"

Esto hace dos cosas atómicamente:

• Transiciona la validation a published.
• Auto-deprecates cualquier validation publicada anterior con el mismo code.

A partir de acá POST /v1/screenings con validation_code: "default" la usa.

Precaución

Una vez publicada no se puede editar. Para evolucionarla: POST /v1/validations/{id}/clone → crea un draft version+1 → editás → publish.

---

Paso 4 · Probar con dry-run (gratis)

POST /v1/screenings/dry-run evalúa cualquier validation (draft, published, deprecated) sin persistir y sin cobrar Açaí. Ideal para tests en CI o para “probar este caso edge antes de publicar”.

SDK

const dryRun = await dj.bhawk.screenings.dryRun({
  validation_code: 'default',
  subject_ref:     'user-quickstart-001',
  subject_type:    'natural',
  payload: {
    full_name:       'Camila Rodríguez',
    birth_date:      '1992-04-18',
    document_type:   'CC',
    document_number: '1023456789',
    country_code:    'CO',
    subject_age:     33,
    kyc_status:      'approved',
    amount:          5000000,
    currency:        'COP',
  },
});

console.log(dryRun.decision, dryRun.findings);

cURL

curl -X POST "$DJ_BASE/v1/screenings/dry-run" \
  -H "X-API-Key: $DJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"validation_id\": \"$VALIDATION_ID\",
    \"facts\": {
      \"full_name\":       \"Camila Rodríguez\",
      \"birth_date\":      \"1992-04-18\",
      \"document_type\":   \"CC\",
      \"document_number\": \"1023456789\",
      \"country_code\":    \"CO\",
      \"subject_age\":     33,
      \"kyc_status\":      \"approved\",
      \"amount\":          5000000,
      \"currency\":        \"COP\"
    }
  }"

JavaScript

const dryRun = await fetch(`${DJ_BASE}/v1/screenings/dry-run`, {
  method:  'POST',
  headers: {
    'X-API-Key':    DJ_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    validation_id: validation.id,
    facts: {
      full_name:       'Camila Rodríguez',
      birth_date:      '1992-04-18',
      document_type:   'CC',
      document_number: '1023456789',
      country_code:    'CO',
      subject_age:     33,
      kyc_status:      'approved',
      amount:          5000000,
      currency:        'COP',
    },
  }),
}).then(r => r.json());

console.log(dryRun.decision, dryRun.findings);

Go

body, _ := json.Marshal(map[string]any{
    "validation_id": validationID,
    "facts": map[string]any{
        "full_name":       "Camila Rodríguez",
        "birth_date":      "1992-04-18",
        "document_type":   "CC",
        "document_number": "1023456789",
        "country_code":    "CO",
        "subject_age":     33,
        "kyc_status":      "approved",
        "amount":          5000000,
        "currency":        "COP",
    },
})
req, _ := http.NewRequest("POST", base+"/v1/screenings/dry-run", bytes.NewReader(body))
req.Header.Set("X-API-Key", apiKey)
req.Header.Set("Content-Type", "application/json")

Respuesta:

{
  "decision":  "approve",
  "score":     0,
  "findings":  [],
  "list_hits": []
}

Probá con un caso PEP — cambia full_name por el de un PEP conocido (el screener consulta OpenSanctions/Yente):

{
  "decision": "review",
  "score":    60,
  "findings": [
    {
      "rule_code": "pep",
      "node_id":   "a1",
      "decision":  "review",
      "score":     60,
      "reason":    "Subject identificado como PEP — DDR requerida."
    }
  ],
  "list_hits": ["PEP"]
}

---

Paso 5 · Screening real

Idéntico body al dry-run pero contra POST /v1/screenings (sin validation_id — usa la publicada del validation_code que pasés, default "default"). Debita 8 Açaí y persiste la evaluación en bhawk.risk_evaluations.

SDK

import { InsufficientAcaiError } from '@bjungle/sdk';

try {
  const screening = await dj.bhawk.screenings.create({
    validation_code: 'default',
    subject_ref:     'user-quickstart-001',
    subject_type:    'natural',
    payload: {
      full_name:       'Camila Rodríguez',
      birth_date:      '1992-04-18',
      document_type:   'CC',
      document_number: '1023456789',
      country_code:    'CO',
      subject_age:     33,
      kyc_status:      'approved',
    },
  });

  // screening.decision: 'approve' | 'review' | 'reject'
} catch (err) {
  if (err instanceof InsufficientAcaiError) {
    // 402 — balance < 8 Açaí. Bloquear + notificar ops.
  } else {
    throw err;
  }
}

cURL

curl -X POST "$DJ_BASE/v1/screenings" \
  -H "X-API-Key: $DJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_ref":     "user-quickstart-001",
    "validation_code": "default",
    "facts": {
      "full_name":       "Camila Rodríguez",
      "birth_date":      "1992-04-18",
      "document_type":   "CC",
      "document_number": "1023456789",
      "country_code":    "CO",
      "subject_age":     33,
      "kyc_status":      "approved"
    }
  }'

JavaScript

const screening = await fetch(`${DJ_BASE}/v1/screenings`, {
  method:  'POST',
  headers: {
    'X-API-Key':    DJ_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    subject_ref:     'user-quickstart-001',
    validation_code: 'default',
    facts: { /* ...mismo shape que dry-run */ },
  }),
}).then(r => r.json());

subject_ref es opaco — el ID que tu sistema asigna al usuario. bhawk lo guarda para correlación pero no comparte foreign keys con bmonkey (ver gotcha #5 de CLAUDE.md). Eso te deja libre de elegir el shape que quieras.

Decisiones agregadas: reject > review > approve. Si alguna regla dispara reject, el screening completo es reject.

Cuando la decisión es review o reject, bhawk auto-abre un caso en el workbench.

---

Paso 6 · Workbench — listar y resolver casos

SDK

// Listar casos abiertos
const page = await dj.bhawk.cases.list({ status: 'open', limit: 50 });
console.log(page.items.length, 'casos abiertos');

// Asignar a un analista
await dj.bhawk.cases.assign(caseId, { assignee: 'compliance@tufintech.co' });

// Resolver
await dj.bhawk.cases.resolve(caseId, {
  decision: 'approve',
  reason:   'PEP confirmado pero perfil de bajo riesgo',
});

// Escalar
await dj.bhawk.cases.escalate(caseId, { reason: 'monto excede umbral DDR' });

cURL

# Listar casos abiertos
curl "$DJ_BASE/v1/cases?status=open&limit=50" \
  -H "X-API-Key: $DJ_API_KEY" | jq .

# Dashboard KPIs
curl "$DJ_BASE/v1/cases/stats" \
  -H "X-API-Key: $DJ_API_KEY"

# Asignar a un analista
curl -X POST "$DJ_BASE/v1/cases/$CASE_ID/assign" \
  -H "X-API-Key: $DJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assignee_email":"compliance@tufintech.co"}'

# Resolver
curl -X POST "$DJ_BASE/v1/cases/$CASE_ID/resolve" \
  -H "X-API-Key: $DJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decision":"approve","note":"PEP confirmado pero perfil de bajo riesgo"}'

# Escalar a supervisor
curl -X POST "$DJ_BASE/v1/cases/$CASE_ID/escalate" \
  -H "X-API-Key: $DJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"monto excede umbral DDR"}'

# Exportar ROS (formato SARLAFT)
curl "$DJ_BASE/v1/cases/export?from=2026-01-01&to=2026-06-01" \
  -H "X-API-Key: $DJ_API_KEY" -o casos.csv

JavaScript

// Listar
const { items } = await fetch(
  `${DJ_BASE}/v1/cases?status=open&limit=50`,
  { headers: { 'X-API-Key': DJ_API_KEY } },
).then(r => r.json());

// Resolver
await fetch(`${DJ_BASE}/v1/cases/${caseId}/resolve`, {
  method:  'POST',
  headers: {
    'X-API-Key':    DJ_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    decision: 'approve',
    note:     'PEP confirmado pero perfil de bajo riesgo',
  }),
});

Endpoints del caso:

Verbo	Path	Acción
GET	/v1/cases?status=	Listar (cursor pagination)
GET	/v1/cases/stats	KPIs (count por estado)
GET	/v1/cases/export?from=&to=	CSV ROS
GET	/v1/cases/{id}	Detalle + timeline auditable
POST	/v1/cases/{id}/assign	Asignar a analista
POST	/v1/cases/{id}/comment	Comentar
POST	/v1/cases/{id}/resolve	Resolver con `approve
POST	/v1/cases/{id}/escalate	Escalar a supervisor
POST	/v1/cases/{id}/reopen	Reabrir resuelto

---

Integración con KYC flow

El flow default de bmonkey ya incluye un step sarlaft que llama a bhawk vía S2S internamente. Si querés que tu flow customizado lo haga:

# 1. Clonar el flow default para editar
curl -X POST "$BMONKEY_BASE/v1/flows/$FLOW_ID/clone" -H "X-API-Key: $DJ_API_KEY"

# 2. PUT steps con sarlaft en la posición que quieras
curl -X PUT "$BMONKEY_BASE/v1/flows/$NEW_FLOW_ID/steps" \
  -H "X-API-Key: $DJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "steps": [
      { "step_type": "consent",         "required": true, "config": {} },
      { "step_type": "document_upload", "required": true, "config": {} },
      { "step_type": "face_match",      "required": true, "config": {} },
      { "step_type": "sarlaft",         "required": true, "config": {"validation_code":"default"} }
    ]
  }'

# 3. Publicar
curl -X POST "$BMONKEY_BASE/v1/flows/$NEW_FLOW_ID/publish" -H "X-API-Key: $DJ_API_KEY"

El validation_code por default es "default". Si querés correr distintas reglas según país, podés tener default, default-mx, default-ar y referenciar la apropiada al crear la sesión.

Nota

S2S internamente. El step sarlaft llama a POST /v1/internal/screenings de bhawk con X-Internal-Token (no expuesto a tenants). El payload corre síncrono — si bhawk decide reject el flow KYC también se rechaza.

---

Esquema de reglas (avanzado)

Cada regla es un grafo de Condition + Action nodes con edges dirigidas. Semantics AND: una action dispara cuando todas sus conditions entrantes son true. Para OR usá actions separadas.

{
  "code":      "alto-monto-pais-riesgo",
  "severity":  "review",
  "score":     50,
  "subject_type": "natural",
  "definition": {
    "nodes": [
      { "id":"c1", "type":"condition", "predicate":"amount_gte",        "value": 10000000 },
      { "id":"c2", "type":"condition", "predicate":"country_in",        "value": ["VE","KP","IR"] },
      { "id":"a1", "type":"action",    "decision":"review",             "score": 50,
        "reason":"Monto alto desde país de riesgo — DDR requerida."     }
    ],
    "edges": [
      { "from":"c1", "to":"a1" },
      { "from":"c2", "to":"a1" }
    ]
  }
}

Predicados disponibles (parcial):

• Identidad: subject_age_gte, subject_age_lt, country_in, country_not_in
• Listas: on_restrictive_list (codes: OFAC | ONU | PEP | EU_SANCTIONS | FATF)
• Transacción: amount_gte, currency_in
• KYC: kyc_status_in

El catálogo completo + schema vive en shared-libs/go-bjungle-bhawk-evaluator.

---

Troubleshooting

Síntoma	Causa típica	Fix
Screening siempre devuelve approve sin hits	OpenSanctions sidecar no configurado en sandbox	Esperable en QA; para prod, contactar para activar
409 en publish	Otra validation con mismo code ya está publicada	Es el flujo correcto — la auto-deprecada queda en histórico
400 validation-not-draft al editar regla	Estás editando una validation publicada	Cloná → editás el draft → publish
402 insufficient-acai en /v1/screenings	Balance < 8 Açaí	Sandbox arranca con 1000 simulados
Análisis con dry-run difiere de screening real	OpenSanctions hits dependen del momento (catálogo se actualiza)	Esperado; dry-run es snapshot del momento

---

Siguientes pasos

Reglas avanzadas

Concepto completo del motor de reglas, predicados y semantics.

Concepto →

API Reference Bhawk

Spec OpenAPI 3.1 completo, interactivo con Scalar.

Abrir →