> ## 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.

# Enviar feedback

> POST /feedback — etiquetas confirmadas de fraude o transacciones legítimas

<Tabs>
  <Tab title="Petición">
    ```http theme={null}
    POST {BASE_URL}/api/v1/feedback
    X-API-Key: <su-api-key>
    Content-Type: application/json

    {
      "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
      "is_fraud": true,
      "fraud_type": "ATO",
      "confirmed_by": "analyst_001",
      "notes": "Account takeover confirmado por mismatch de device fingerprint"
    }
    ```
  </Tab>

  <Tab title="Respuesta">
    ```http theme={null}
    HTTP/1.1 201 Created
    Content-Type: application/json

    {
      "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
      "is_fraud": true,
      "fraud_type": "ATO",
      "confirmed_by": "analyst_001",
      "confirmed_at": "2025-06-15T16:00:00Z"
    }
    ```
  </Tab>
</Tabs>

Envía una etiqueta confirmada (fraude o legítimo) para una transacción previamente evaluada con `POST /score` o `POST /score/batch`. Cierra el ciclo de retroalimentación para monitoreo y mejora del modelo.

**Autenticación:** `X-API-Key`.

## Cuerpo de la petición

| Campo            | Tipo    | Descripción                                                                                    |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `transaction_id` | UUID    | UUID de la transacción evaluada                                                                |
| `is_fraud`       | boolean | `true` = fraude confirmado; `false` = legítimo                                                 |
| `fraud_type`     | string  | Obligatorio si `is_fraud=true`. Ver [fraud\_type](/docs/shield/reference/enums#fraud_type-feedback) |
| `confirmed_by`   | string  | ID del analista o sistema (1–64 caracteres)                                                    |

### Campos opcionales

| Campo   | Tipo   | Cuándo enviarlo                                      |
| ------- | ------ | ---------------------------------------------------- |
| `notes` | string | Contexto de la investigación (máx. 2.000 caracteres) |

<Note>
  Si `is_fraud=false`, **no incluya** `fraud_type`. La transacción debe existir previamente en Kairo Shield (haber sido evaluada).
</Note>

## Campos de respuesta

| Campo            | Descripción                              |
| ---------------- | ---------------------------------------- |
| `transaction_id` | UUID de la transacción etiquetada        |
| `is_fraud`       | Etiqueta confirmada                      |
| `fraud_type`     | Tipo de fraude (solo si `is_fraud=true`) |
| `confirmed_by`   | Quién registró la etiqueta               |
| `confirmed_at`   | Marca de tiempo UTC de persistencia      |

Si tiene webhooks suscritos a `feedback.received`, recibirá un POST con el evento correspondiente.

## Más ejemplos de petición

<Tabs>
  <Tab title="Fraude confirmado — ATO">
    ```json theme={null}
    {
      "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
      "is_fraud": true,
      "fraud_type": "ATO",
      "confirmed_by": "analyst_001",
      "notes": "Account takeover confirmado por mismatch de device fingerprint"
    }
    ```
  </Tab>

  <Tab title="Transacción legítima">
    ```json theme={null}
    {
      "transaction_id": "660e8400-e29b-41d4-a716-446655440001",
      "is_fraud": false,
      "confirmed_by": "analyst_002",
      "notes": "Revisión manual: comportamiento habitual del usuario"
    }
    ```
  </Tab>

  <Tab title="Fraude confirmado — friendly fraud">
    ```json theme={null}
    {
      "transaction_id": "770e8400-e29b-41d4-a716-446655440002",
      "is_fraud": true,
      "fraud_type": "FRIENDLY_FRAUD",
      "confirmed_by": "chargeback_team",
      "notes": "Chargeback infundado tras entrega confirmada"
    }
    ```
  </Tab>
</Tabs>

## Errores típicos

* **401** — API Key inválida
* **404** — Transacción no encontrada para su cliente
* **422** — `fraud_type` ausente cuando `is_fraud=true`, o enum inválido

## Ver también

* [Scoring en tiempo real](/docs/shield/api/score)
* [fraud\_type](/docs/shield/reference/enums#fraud_type-feedback)
* [Eventos de webhook](/docs/shield/webhooks/events)