> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kairoconnect.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Scoring por lote
> POST /score/batch — evaluar hasta 1.000 transacciones por petición
```http theme={null}
POST {BASE_URL}/api/v1/score/batch
X-API-Key:
Content-Type: application/json
{
"transactions": [
{
"transaction_id": "550e8400-e29b-41d4-a716-446655440000",
"merchant_reference": "MERCH-TX-001",
"user_token": "a3f2b8c9d1e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f901",
"merchant_id": "merchant_001",
"amount": "150000.00",
"currency": "COP",
"transaction_type": "PAYIN",
"payment_method": "CARD",
"card_bin": "411111",
"client_type": "MOBILE_APP",
"is_tax_applied": true,
"timestamp": "2025-06-15T14:30:00Z",
"ip_hash": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b201",
"transaction_country": "CO",
"mcc": "5812",
"merchant_risk_tier": "MEDIUM",
"merchant_age_days": 365
}
]
}
```
```http theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
{
"job_id": "batch-20250615-001",
"total": 2,
"completed": 2,
"failed": 0,
"results": [
{
"transaction_id": "550e8400-e29b-41d4-a716-446655440000",
"fraud_score": 0.15,
"risk_level": "LOW",
"decision": "APPROVE",
"decision_source": "MODEL",
"top_features": [
{"feature": "amount_log", "importance": 0.05},
{"feature": "channel_ord", "importance": -0.03}
],
"model_version": "kairo-shield",
"threshold_used": {
"low_max": 0.25,
"medium_max": 0.55,
"high_max": 0.80
},
"processing_time_ms": 38.2,
"scoring_timeout_ms": 500,
"request_id": "req-batch-001",
"uiaf_reportable": false
}
],
"errors": []
}
```
Evalúa múltiples transacciones en una sola petición (camino offline). Máximo **1.000** transacciones por request.
**Autenticación:** `X-API-Key`. Requiere `fraud_detection_consent=true` en su cliente.
## Cuerpo de la petición
El body es un objeto con el array `transactions`. Consulte la [referencia de campos de transacción](/docs/shield/reference/transaction-fields) para el detalle completo.
| Campo | Tipo | Descripción |
| -------------- | ----- | ----------------------------------------------- |
| `transactions` | array | Transacciones a evaluar. Mínimo 1, máximo 1.000 |
Cada elemento del array comparte el mismo esquema que `POST /score`. Campos obligatorios:
| Campo | Tipo | Descripción |
| --------------------- | -------- | --------------------------------------------------- |
| `transaction_id` | UUID | Identificador único por cliente (idempotencia 24 h) |
| `merchant_reference` | string | Su referencia interna (1–128 caracteres) |
| `user_token` | string | SHA-256 del usuario (64 hex) |
| `merchant_id` | string | ID del comercio en su plataforma |
| `amount` | decimal | Monto > 0 |
| `currency` | string | ISO 4217 (ej. `COP`, `USD`) |
| `transaction_type` | string | Ver [Enums](/docs/shield/reference/enums) |
| `payment_method` | string | Ver [Enums](/docs/shield/reference/enums) |
| `timestamp` | datetime | ISO 8601 UTC |
| `ip_hash` | string | SHA-256 de la IP (64 hex) |
| `transaction_country` | string | ISO 3166-1 alpha-2 |
| `mcc` | string | Merchant Category Code (4 dígitos) |
| `merchant_risk_tier` | string | `LOW`, `MEDIUM` o `HIGH` |
### Campos opcionales
Enriquecen el scoring (dispositivo, geo, comercio, balances). No son obligatorios, pero mejoran reglas y features del modelo.
| Campo | Tipo | Cuándo enviarlo |
| ---------------------------- | ------- | ------------------------------------------------------------- |
| `destination_account_token` | string | PAYOUT, TRANSFER, P2P, CASHOUT — SHA-256 de la cuenta destino |
| `card_bin` | string | Pagos con tarjeta — primeros 6 dígitos (BIN) |
| `is_tax_applied` | boolean | Si aplicó impuesto/VAT. Default `false` |
| `device_fingerprint_hash` | string | SHA-256 del fingerprint de dispositivo |
| `os_type` | string | `ANDROID`, `IOS`, `WINDOWS`, `MACOS`, … |
| `client_type` | string | `WEB`, `MOBILE_APP`, `API`, `POS`, … |
| `is_emulator` | boolean | `true` si el cliente detectó emulador |
| `is_vpn_proxy` | boolean | `true` si la IP es VPN o proxy |
| `is_datacenter_ip` | boolean | `true` si la IP es de datacenter/hosting |
| `ip_country` | string | País derivado de la IP (ISO alpha-2) |
| `destination_country` | string | Transferencias cross-border |
| `merchant_age_days` | integer | Días desde el onboarding del comercio |
| `origin_balance_before` | number | Saldo origen antes de la transacción |
| `origin_balance_after` | number | Saldo origen después (débitos: before − amount) |
| `destination_balance_before` | number | Saldo destino antes del crédito |
| `destination_balance_after` | number | Saldo destino después del crédito |
Detalle completo en [Campos de transacción](/docs/shield/reference/transaction-fields).
**No envíe PII en claro.** Use hashes SHA-256 para `user_token`, `ip_hash` y tokens de cuenta.
Consulte [Umbrales y decisiones](/docs/shield/reference/thresholds) y [Features SHAP](/docs/shield/reference/shap-features) para interpretar cada ítem en `results[]`.
## Campos de respuesta
| Campo | Descripción |
| ----------- | ---------------------------------------------------------------- |
| `job_id` | Identificador del job de lote |
| `total` | Transacciones enviadas |
| `completed` | Scoring exitoso |
| `failed` | Fallos (ver `errors`) |
| `results` | Array de respuestas de scoring (mismo esquema que `/score`) |
| `errors` | `{ "transaction_id": "...", "message": "..." }` por ítem fallido |
## Más ejemplos de petición
```json theme={null}
{
"transactions": [
{
"transaction_id": "660e8400-e29b-41d4-a716-446655440001",
"merchant_reference": "MERCH-BREB-001",
"user_token": "a3f2b8c9d1e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f901",
"merchant_id": "merchant_001",
"amount": "250000.00",
"currency": "COP",
"transaction_type": "PAYIN",
"payment_method": "BREB",
"is_tax_applied": false,
"timestamp": "2025-06-15T14:30:00Z",
"device_fingerprint_hash": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
"os_type": "ANDROID",
"client_type": "MOBILE_APP",
"is_emulator": false,
"ip_hash": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b201",
"transaction_country": "CO",
"mcc": "6012",
"merchant_risk_tier": "MEDIUM",
"merchant_age_days": 120
}
]
}
```
```json theme={null}
{
"transactions": [
{
"transaction_id": "770e8400-e29b-41d4-a716-446655440002",
"merchant_reference": "MERCH-PAYOUT-001",
"user_token": "a3f2b8c9d1e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f901",
"merchant_id": "merchant_001",
"destination_account_token": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
"amount": "500000.00",
"currency": "COP",
"transaction_type": "PAYOUT",
"payment_method": "BANK_TRANSFER",
"is_tax_applied": false,
"timestamp": "2025-06-15T15:00:00Z",
"client_type": "API",
"ip_hash": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b201",
"transaction_country": "CO",
"destination_country": "CO",
"mcc": "6010",
"merchant_risk_tier": "MEDIUM",
"merchant_age_days": 365
}
]
}
```
Incluya `destination_account_token` en desembolsos y transferencias hacia cuenta destino.
## Errores típicos
* **403** — Consentimiento de fraude no otorgado
* **409** — `transaction_id` duplicado en ventana de 24 h (en algún ítem)
* **422** — Array vacío, más de 1.000 ítems, o validación en algún elemento
* **504** — Timeout de scoring en algún ítem
## Ver también
* [Scoring en tiempo real](/docs/shield/api/score)
* [Campos de transacción](/docs/shield/reference/transaction-fields)
* [Enums permitidos](/docs/shield/reference/enums)