> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ingerir señal de riesgo

> Ingerir un evento de señal de riesgo en bruto. Las señales de riesgo son la base del Firewall de Identidad Antifraude: representan una única observación sospechosa sobre un sujeto.

## Encabezados

## Respuesta

**signal\_id** `string`

UUID de la señal de riesgo creada.

**risk\_score** `integer`

La puntuación de riesgo ingerida (0-100).

**created\_at** `string`

Marca de tiempo de ingesta ISO 8601.


## OpenAPI

````yaml es/mint-openapi.yaml POST /v1/risk/signals
openapi: 3.0.3
info:
  title: Truthlocks API
  description: >
    Truthlocks es una infraestructura de verificación universal para documentos,
    credenciales y activos digitales.

    Esta especificación define la API canónica para interactuar con los
    servicios de Truthlocks.


    ## URLs Base

    - **Producción**: `https://api.truthlocks.com`

    - **Sandbox**: `https://sandbox-api.truthlocks.com`


    ## Autenticación

    - **Claves API**: Use el encabezado `X-API-Key` para operaciones máquina a
    máquina

    - **Tokens Bearer**: Use `Authorization: Bearer <jwt>` para operaciones
    iniciadas por el usuario


    ## Identidad del Inquilino

    En producción, la identidad del inquilino se deriva del contexto autenticado
    (clave API o JWT).

    El encabezado `X-Tenant-ID` se ignora en producción para evitar la
    suplantación de identidad.
  version: 1.0.0
  contact:
    name: Truthlocks Support
    url: https://truthlocks.com/support
    email: support@truthlocks.com
servers:
  - url: https://api.truthlocks.com
    description: API de producción
  - url: https://sandbox-api.truthlocks.com
    description: Entorno Sandbox
security:
  - APIKey: []
  - BearerAuth: []
tags:
  - name: Authentication
    description: Gestión de claves y tokens de API
  - name: Issuers
    description: Registro del emisor y gestión de la confianza
  - name: Keys
    description: Gestión de claves criptográficas para emisores
  - name: Attestations
    description: Ciclo de vida de la atestación (acuñar, revocar, reemplazar)
  - name: Verification
    description: Verificación de atestación y paquetes de prueba
  - name: Governance
    description: Flujos de trabajo de gobernanza del emisor (solo administrador)
  - name: Identity
    description: Gestión de organización, usuarios y roles
  - name: Audit
    description: Consultas de eventos de auditoría
  - name: Tenant Console
    description: Puntos finales de perfil y ciclo de vida del inquilino
  - name: Health
    description: Endpoints de estado y preparación del servicio
  - name: Risk
    description: Ingesta de señales de riesgo y detección de fraude
  - name: Risk Enforcement
    description: >-
      Acciones de aplicación de riesgos: bloqueo, desafío, cuarentena y
      configuración
  - name: Billing
    description: Gestión de facturación, suscripciones y complementos
  - name: Machine Identity
    description: >-
      Protocolo de Identidad de Agente de Máquina (MAIP) — registro de agentes,
      sesiones, confianza, testigo, cumplimiento, orquestación y observabilidad
externalDocs:
  description: API de transparencia de solo lectura (especificación de servicio separada)
  url: >-
    https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
  /v1/risk/signals:
    post:
      tags:
        - Risk
      summary: Ingerir señal de riesgo
      description: >-
        Envíe una señal de riesgo para una entidad específica. Las señales de
        riesgo son observaciones puntuadas de fuentes de detección de fraude,
        como huellas dactilares de dispositivos, servicios de reputación de IP,
        proveedores de verificación de correo electrónico o su propio motor de
        reglas interno. Cada señal se almacena con aislamiento total del
        inquilino (seguridad a nivel de fila) y se puede utilizar para informar
        decisiones de riesgo posteriores.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                idempotency_key:
                  type: string
                ip_address:
                  type: string
                payload: {}
                risk_score:
                  type: integer
                signal_source:
                  type: string
                signal_type:
                  type: string
                  description: Clasificación de la señal de riesgo
                  example: velocity_anomaly
                subject_id:
                  type: string
                subject_type:
                  type: string
                user_agent:
                  type: string
              type: object
              required:
                - signal_source
                - signal_type
                - subject_id
                - subject_type
      responses:
        '201':
          description: Señal de riesgo ingerida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskSignal'
        '400':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Autenticación requerida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Límite de velocidad excedido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
        - APIKey: []
components:
  schemas:
    RiskSignal:
      type: object
      properties:
        id:
          type: string
          format: uuid
        tenant_id:
          type: string
          format: uuid
        source:
          type: string
          description: >-
            Origen de la señal (por ejemplo, device_fingerprint, ip_reputation,
            email_verification, document_analysis, behavioral)
          example: device_fingerprint
        signal_type:
          type: string
          description: Clasificación de la señal de riesgo
          example: velocity_anomaly
        score:
          type: number
          format: float
          minimum: 0
          maximum: 1
          description: Puntuación de riesgo entre 0 (sin riesgo) y 1 (riesgo más alto)
          example: 0.85
        details:
          type: object
          additionalProperties: true
          description: Metadatos arbitrarios asociados con la señal
          example:
            ip: 203.0.113.42
            country: US
            reason: multiple_accounts_same_device
        entity_type:
          type: string
          description: El tipo de entidad a la que se refiere esta señal
          enum:
            - user
            - device
            - ip
            - document
            - session
          example: user
        entity_id:
          type: string
          description: Identificador de la entidad que se está evaluando
          example: usr_8f14e45f
        created_at:
          type: string
          format: date-time
    ErrorEnvelope:
      type: object
      required:
        - code
        - message
        - http_status
      properties:
        code:
          type: string
          description: Código de error legible por máquina
          enum:
            - AUTH_REQUIRED
            - AUTH_INVALID
            - PERMISSION_DENIED
            - TENANT_IDENTITY_UNVERIFIED
            - NOT_FOUND
            - VALIDATION_ERROR
            - CONFLICT
            - PAYLOAD_TOO_LARGE
            - RATE_LIMIT_EXCEEDED
            - QUOTA_EXCEEDED
            - SERVICE_UNAVAILABLE
            - INTERNAL_ERROR
        message:
          type: string
          description: Mensaje de error legible por humanos
        http_status:
          type: integer
          description: Código de estado HTTP
        retry_after_ms:
          type: integer
          description: Milisegundos a esperar antes de reintentar (para límites de tasa)
        details:
          type: object
          description: Contexto de error adicional
      example:
        code: AUTH_REQUIRED
        message: Authentication required
        http_status: 401
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Clave API para autenticación máquina a máquina
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT para operaciones iniciadas por el usuario

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.