Registrar evidência

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

Endpoint

POSThttps://api.rapidchargeback.com/api/v1/evidence

Autenticação

Basic Auth com client_id:client_secret. Ver Autenticação.

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:

// 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

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:

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)

{
  "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)

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

Erro: `type` inválido (422)

{
  "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)

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

Erro: payload acima do teto (422)

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