Documentacion API | Central de Riesgo

Modelo de acceso

La API key se resuelve en backend por hash y queda asociada atenantId,apiKeyId ypermissions.

Regla editorial

Solo se incluyen endpoints que realmente pueden operar por integracion. Si un endpoint depende de roles humanos del tenant, no se documenta aqui como API key.

Tenant scopePermission based

El alcance efectivo depende del tenant activo y de los permisos ligados a la API key. Por eso cada endpoint declara su permiso requerido y el tipo de request que espera.

Resumen rapido

Header directo: X-Api-Key
Header alterno: Authorization
Scope: Tenant + permisos
Rol humano: No aplica

Autenticacion

Dos formas validas de enviar la API key

Ambas variantes resuelven la misma identidad tecnica en backend. Usa la que mejor calce con tu cliente HTTP o con tu capa de autenticacion actual.

Header dedicado

Header

La integracion puede enviar la API key en un header propio. Es la forma mas directa cuando tu cliente HTTP soporta encabezados personalizados.

X-Api-Key: <tu_api_key>

Authorization header

Header

Tambien puedes enviar la credencial en Authorization cuando tu integracion ya centraliza autenticacion en ese header.

Authorization: ApiKey <tu_api_key>

Permisos

Mapa de permisos para integraciones

Cada credencial solo habilita lo que tenga enpermissions. Este resumen deja claro que esta disponible hoy y que aun no esta documentado para clientes.

audit.read

Permiso definido para lecturas de auditoria autenticadas por API key. No hay un endpoint publico documentado en esta pagina para ese permiso.

risk.evaluations.read

Permite consultar evaluaciones resumidas y el historial de evaluaciones de un sujeto de riesgo.

risk.evaluations.run

Permiso definido para ejecuciones de evaluacion. Si tu tenant requiere exponer ese flujo por API key, conviene habilitarlo y documentarlo de forma dedicada.

risk.subjects.write

Permite crear sujetos de riesgo y registrar sus transacciones mediante payload JSON.

risk.cases.read

Permiso disponible para lecturas de casos autenticadas por API key. Esta pagina no expone aun un endpoint publico documentado para ese permiso.

risk.cases.manage

Permiso disponible para gestion de casos por integracion. Debe documentarse por separado si ese flujo se habilita para clientes.

Formatos

Como leer el tipo de request de cada endpoint

La documentacion separa claramente endpoints con querystring, payload JSON y multipart/form-data para que la integracion no mezcle patrones incompatibles.

Endpoints con querystring

Se usan para lecturas, filtros y paginacion. Los parametros viajan en la URL y el body permanece vacio.

GET /api/RiskSubject/evaluations?pageIndex=1&pageSize=20&search=

Endpoints con application/json

Se usan cuando la integracion necesita enviar estructuras completas, por ejemplo un sujeto de riesgo con una lista de transacciones.

Content-Type: application/json

Endpoints con multipart/form-data

Se reservan para cargas mixtas de archivos y campos. En esta pagina se explica el patron, pero los endpoints documentados abajo no usan multipart actualmente.

curl -X POST https://tu-dominio.com/api/endpoint \
  -H "X-Api-Key: <tu_api_key>" \
  -F "file=@evidencia.pdf" \
  -F "caseId=123"

Endpoints

Referencia util para consumo por API key

Selecciona un endpoint en el menu lateral para abrir su ficha completa. Aqui tienes una vista rapida del catalogo soportado hoy.

GETQuerystring

Obtener suscripcion actual del tenant

/api/TenantSubscription/current

Devuelve el plan actual y los limites del tenant asociado a la API key. Sirve para que una integracion valide alcance, capacidad o estado del plan antes de ejecutar otros flujos.

Permiso requerido

Sin permiso adicional explicito

GETQuerystring

Listar evaluaciones resumidas de sujetos

/api/RiskSubject/evaluations?pageIndex=1&pageSize=20&search=

Recupera una vista paginada de evaluaciones para navegar historial, buscar coincidencias o construir un panel resumido desde un sistema externo.

Permiso requerido

risk.evaluations.read

GETQuerystring

Obtener evaluaciones de un sujeto especifico

/api/RiskSubject/{id}/evaluations

Consulta el historial de evaluaciones de un sujeto concreto para revisar cambios, reintentos o resultados asociados a un identificador ya conocido por la integracion.

Permiso requerido

risk.evaluations.read

POSTapplication/json

Crear un sujeto de riesgo con sus transacciones

/api/RiskSubject

Registra un sujeto de riesgo y una o varias transacciones en una sola operacion. Es el endpoint principal para integraciones que desean empujar datos operativos al motor de riesgo.

Permiso requerido

risk.subjects.write

GETQuerystringSin permiso adicional explicito

Obtener suscripcion actual del tenant

/api/TenantSubscription/current

Devuelve el plan actual y los limites del tenant asociado a la API key. Sirve para que una integracion valide alcance, capacidad o estado del plan antes de ejecutar otros flujos.

Notas de integracion

La API key debe pertenecer a un tenant activo.
No requiere un permiso explicito adicional.
La credencial representa tenant + permisos, no un usuario humano.

Resumen tecnico

Metodo: GET
Formato: Querystring
Permiso: Sin permiso adicional explicito

Request example

cURL

curl -X GET "https://tu-dominio.com/api/TenantSubscription/current" \
  -H "X-Api-Key: <tu_api_key>"

Path o payload

Querystring

GET /api/TenantSubscription/current

GETQuerystringrisk.evaluations.read

Listar evaluaciones resumidas de sujetos

/api/RiskSubject/evaluations?pageIndex=1&pageSize=20&search=

Recupera una vista paginada de evaluaciones para navegar historial, buscar coincidencias o construir un panel resumido desde un sistema externo.

Notas de integracion

Requiere el permiso risk.evaluations.read.
pageIndex y pageSize controlan la paginacion.
search permite filtrar por texto o criterio operativo definido por backend.

Resumen tecnico

Metodo: GET
Formato: Querystring
Permiso: risk.evaluations.read

Request example

cURL

curl -X GET "https://tu-dominio.com/api/RiskSubject/evaluations?pageIndex=1&pageSize=20&search=" \
  -H "Authorization: ApiKey <tu_api_key>"

Path o payload

Querystring

GET /api/RiskSubject/evaluations?pageIndex=1&pageSize=20&search=juan

GETQuerystringrisk.evaluations.read

Obtener evaluaciones de un sujeto especifico

/api/RiskSubject/{id}/evaluations

Consulta el historial de evaluaciones de un sujeto concreto para revisar cambios, reintentos o resultados asociados a un identificador ya conocido por la integracion.

Notas de integracion

Requiere el permiso risk.evaluations.read.
El id corresponde al sujeto de riesgo ya registrado en la plataforma.
Es util cuando tu sistema interno guarda la relacion entre su propio cliente y el sujeto creado en Risk Center.

Resumen tecnico

Metodo: GET
Formato: Querystring
Permiso: risk.evaluations.read

Request example

cURL

curl -X GET "https://tu-dominio.com/api/RiskSubject/123/evaluations" \
  -H "X-Api-Key: <tu_api_key>"

Path o payload

Querystring

GET /api/RiskSubject/123/evaluations

POSTapplication/jsonrisk.subjects.write

Crear un sujeto de riesgo con sus transacciones

/api/RiskSubject

Registra un sujeto de riesgo y una o varias transacciones en una sola operacion. Es el endpoint principal para integraciones que desean empujar datos operativos al motor de riesgo.

Notas de integracion

Requiere el permiso risk.subjects.write.
El body se envia como application/json.
Las transacciones deben mapear sourceSystem, sourceReferenceId y operationDateUtc con consistencia para facilitar trazabilidad.

Resumen tecnico

Metodo: POST
Formato: application/json
Permiso: risk.subjects.write

Request example

cURL

curl -X POST "https://tu-dominio.com/api/RiskSubject" \
  -H "X-Api-Key: <tu_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "occupationCategory": "string opcional",
    "occupation": "string opcional",
    "documentType": "DNI",
    "documentNumber": "12345678",
    "fullName": "NOMBRE COMPLETO",
    "email": "correo@dominio.com",
    "phone": "999999999",
    "nationality": "PERUANA",
    "isPEP": false,
    "transactions": [
      {
        "sourceSystem": "DEFI_PERU_EXTERNAL",
        "sourceReferenceId": "ABC123",
        "operationNumber": "OP-001",
        "operationType": "SELL",
        "asset": "USDT",
        "amount": 1000.50,
        "amountPen": 3700.00,
        "amountUsd": null,
        "operationDateUtc": "2026-07-25T18:30:00Z"
      }
    ]
  }'

Path o payload

application/json

{
  "occupationCategory": "string opcional",
  "occupation": "string opcional",
  "documentType": "DNI",
  "documentNumber": "12345678",
  "fullName": "NOMBRE COMPLETO",
  "email": "correo@dominio.com",
  "phone": "999999999",
  "nationality": "PERUANA",
  "isPEP": false,
  "transactions": [
    {
      "sourceSystem": "DEFI_PERU_EXTERNAL",
      "sourceReferenceId": "ABC123",
      "operationNumber": "OP-001",
      "operationType": "SELL",
      "asset": "USDT",
      "amount": 1000.50,
      "amountPen": 3700.00,
      "amountUsd": null,
      "operationDateUtc": "2026-07-25T18:30:00Z"
    }
  ]
}