# Registrar evidencia

> Adjunta un registro de evidencia a una transacción ya enviada a Rapid.

Página: https://doc.rapidchargeback.com/es/canais/evidence/registrar-evidencia/

Adjunta un registro de evidencia a una transacción ya enviada a Rapid.

## Endpoint

```
POST https://api.rapidchargeback.com/api/v1/evidence
```

## Autenticación

Basic Auth con `client_id:client_secret`. Ver [Autenticación](https://doc.rapidchargeback.com/es/referencia/autenticacao/).

```
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json
```

## Cuerpo de la solicitud

| Campo | Tipo | Descripción | Obligatorio |
|---|---|---|---|
| `transaction_id` | string (UUID) | ID de la transacción en Rapid, devuelto cuando la creaste | Sí, o `transaction_ref` |
| `transaction_ref` | objeto | Alternativa a `transaction_id`: apunta a la transacción por **tu** identificador. Ver abajo | Sí, o `transaction_id` |
| `type` | string (enum) | Naturaleza del hecho registrado. Valores aceptados abajo | Sí |
| `payload` | objeto | Los datos del hecho. Formato libre, tope de 32 KB | Sí |
| `captured_at` | string (ISO 8601 con offset) | Cuándo ocurrió el hecho en tu sistema, no cuándo lo envías | Sí |

Informa **uno** de los dos: `transaction_id` o `transaction_ref`. Si faltan los dos, la respuesta es `422`.

### Campo `transaction_ref`

| Campo | Tipo | Descripción | Obligatorio |
|---|---|---|---|
| `external_source` | string | El mismo origen que usaste al crear la transacción (ej.: `"shopify"`) | Sí |
| `external_id` | string | El mismo ID de tu sistema que usaste al crear la transacción | Sí |

### Valores de `type`

| Valor | Cuándo usar |
|---|---|
| `terms_acceptance` | El cliente aceptó términos, política o contrato |
| `access_log` | El cliente accedió al producto o al área con sesión iniciada |
| `delivery_confirmation` | Entrega confirmada |
| `usage_log` | Uso efectivo del producto o servicio |
| `communication` | Intercambio con el cliente (e-mail, chat, ticket) |
| `other` | Cualquier hecho que no encaje en los anteriores |

### Campo `payload`

Formato libre: tú decides las claves. La única regla es el **tope de 32 KB** en el JSON serializado: la evidencia es un registro, no un archivo.

Sugerencias por tipo, no obligatorias:

```json
// terms_acceptance
{ "accepted_at": "2026-04-01T15:29:40Z", "terms_version": "v3.2", "ip": "203.0.113.10" }

// access_log
{ "first_access_at": "2026-04-01T16:02:11Z", "sessions": 3 }

// delivery_confirmation
{ "carrier": "correios", "tracking": "AA123456789BR", "delivered_at": "2026-04-03T11:20:00Z" }
```

## Validaciones

| Regla | Respuesta |
|---|---|
| Ni `transaction_id` ni `transaction_ref` | `422 VALIDATION_ERROR`: *transaction_id or transaction_ref is required* |
| `type` fuera del enum | `422 VALIDATION_ERROR` con la lista de valores aceptados |
| `captured_at` sin offset de zona horaria | `422 VALIDATION_ERROR`: *Invalid datetime* |
| `payload` serializado de más de 32 KB | `422 VALIDATION_ERROR`: *payload exceeds 32KB: evidence is a record, not a file* |
| La transacción no existe, o no es de tu empresa | `404 TRANSACTION_NOT_FOUND` |
| Credencial ausente o inválida | `401 UNAUTHORIZED` |

La transacción siempre se resuelve **dentro de tu empresa**. Un ID de transacción de otra empresa responde `404`, nunca `403`: no confirmamos la existencia de datos ajenos.

## Ejemplo de solicitud

```bash
curl -X POST https://api.rapidchargeback.com/api/v1/evidence \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "00000000-0000-0000-0000-000000000042",
    "type": "terms_acceptance",
    "payload": {
      "accepted_at": "2026-04-01T15:29:40Z",
      "terms_version": "v3.2",
      "ip": "203.0.113.10"
    },
    "captured_at": "2026-04-01T15:29:41Z"
  }'
```

Por tu propio identificador, sin guardar el UUID de Rapid:

```bash
curl -X POST https://api.rapidchargeback.com/api/v1/evidence \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_ref": { "external_source": "shopify", "external_id": "TXN-2026-001" },
    "type": "access_log",
    "payload": { "first_access_at": "2026-04-01T16:02:11Z", "sessions": 3 },
    "captured_at": "2026-04-01T16:02:12Z"
  }'
```

## Ejemplos de respuesta

### Éxito (201)

```json
{
  "data": {
    "id": "00000000-0000-0000-0000-0000000000e1",
    "transaction_id": "00000000-0000-0000-0000-000000000042",
    "type": "terms_acceptance"
  }
}
```

El `id` devuelto es el de la evidencia. Guárdalo solo si vas a referenciarla; para listar, la clave es la transacción.

### Error: referencia de la transacción ausente (422)

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "transaction_id or transaction_ref is required"
  }
}
```

### Error: `type` inválido (422)

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid enum value. Expected 'terms_acceptance' | 'access_log' | 'delivery_confirmation' | 'usage_log' | 'communication' | 'other', received 'nao_existe'"
  }
}
```

### Error: transacción no encontrada (404)

```json
{
  "error": {
    "code": "TRANSACTION_NOT_FOUND",
    "message": "Transaction not found"
  }
}
```

### Error: payload por encima del tope (422)

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "payload exceeds 32KB: evidence is a record, not a file"
  }
}
```

## Próximos pasos

- [Consultar evidencias](https://doc.rapidchargeback.com/es/canais/evidence/consultar-evidencias/)
- [Códigos de respuesta](https://doc.rapidchargeback.com/es/referencia/codigos-de-resposta/)