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.

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:

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

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:

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)

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

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

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

Error: transacción no encontrada (404)

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

Error: payload por encima del tope (422)

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