# Registrar evidência

> Anexa um registro de evidência a uma transação já enviada à Rapid.

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

Anexa um registro de evidência a uma transação já enviada à Rapid.

## Endpoint

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

## Autenticação

Basic Auth com `client_id:client_secret`. Ver [Autenticação](https://doc.rapidchargeback.com/referencia/autenticacao/).

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

## Corpo da requisição

| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| `transaction_id` | string (UUID) | ID da transação na Rapid, devolvido quando você a criou | Sim, ou `transaction_ref` |
| `transaction_ref` | objeto | Alternativa ao `transaction_id`: aponta a transação pelo **seu** identificador. Ver abaixo | Sim, ou `transaction_id` |
| `type` | string (enum) | Natureza do fato registrado. Valores aceitos abaixo | Sim |
| `payload` | objeto | Os dados do fato. Formato livre, teto de 32 KB | Sim |
| `captured_at` | string (ISO 8601 com offset) | Quando o fato aconteceu no seu sistema, não quando você o envia | Sim |

Informe **um** dos dois: `transaction_id` ou `transaction_ref`. Se faltarem os dois, a resposta é `422`.

### Campo `transaction_ref`

| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| `external_source` | string | A mesma origem que você usou ao criar a transação (ex: `"shopify"`) | Sim |
| `external_id` | string | O mesmo ID do seu sistema que você usou ao criar a transação | Sim |

### Valores de `type`

| Valor | Quando usar |
|---|---|
| `terms_acceptance` | Cliente aceitou termos, política ou contrato |
| `access_log` | Cliente acessou o produto ou a área logada |
| `delivery_confirmation` | Entrega confirmada |
| `usage_log` | Uso efetivo do produto ou serviço |
| `communication` | Troca com o cliente (e-mail, chat, ticket) |
| `other` | Qualquer fato que não se encaixe nos anteriores |

### Campo `payload`

Formato livre: você decide as chaves. A única regra é o **teto de 32 KB** no JSON serializado: evidência é registro, não arquivo.

Sugestões por tipo, não obrigatórias:

```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" }
```

## Validações

| Regra | Resposta |
|---|---|
| Nem `transaction_id` nem `transaction_ref` | `422 VALIDATION_ERROR`: *transaction_id ou transaction_ref é obrigatório* |
| `type` fora do enum | `422 VALIDATION_ERROR` com a lista dos valores aceitos |
| `captured_at` sem offset de fuso | `422 VALIDATION_ERROR`: *Invalid datetime* |
| `payload` serializado acima de 32 KB | `422 VALIDATION_ERROR`: *payload excede 32KB: evidência é registro, não arquivo* |
| Transação não existe, ou não é da sua empresa | `404 TRANSACTION_NOT_FOUND` |
| Credencial ausente ou inválida | `401 UNAUTHORIZED` |

A transação é sempre resolvida **dentro da sua empresa**. ID de transação de outra empresa responde `404`, nunca `403`: não confirmamos a existência de dado alheio.

## Exemplo de requisição

```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"
  }'
```

Pelo seu próprio identificador, sem guardar o UUID da 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"
  }'
```

## Exemplos de resposta

### Sucesso (201)

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

O `id` devolvido é o da evidência. Guarde-o só se você for referenciá-la; para listar, a chave é a transação.

### Erro: referência da transação ausente (422)

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "transaction_id ou transaction_ref é obrigatório"
  }
}
```

### Erro: `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'"
  }
}
```

### Erro: transação não encontrada (404)

```json
{
  "error": {
    "code": "TRANSACTION_NOT_FOUND",
    "message": "Transação não encontrada"
  }
}
```

### Erro: payload acima do teto (422)

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "payload excede 32KB: evidência é registro, não arquivo"
  }
}
```

## Próximos passos

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