Guías

Guía de integración

Esta guía explica cómo integrar Revclic en tu plataforma de e-commerce. Para las especificaciones completas de los endpoints, consulta la Referencia de la API.

Visión general

La integración consiste en dos pasos:

  1. Capturar el ID de redirección cuando un visitante llega desde un enlace de afiliado
  2. Reportar la transacción cuando el visitante completa una compra

1. Capturar el ID de redirección

Cuando un comprador hace clic en un enlace de afiliado, es redirigido a tu sitio web con un parámetro revclic_rid en la URL.

Ejemplo de URL entrante:

https://yourstore.com/product/123?revclic_rid=42

Debes:

  • Extraer el revclic_rid de la URL
  • Almacenarlo en una cookie o sesión durante la visita

Ejemplo en JavaScript

const urlParams = new URLSearchParams(window.location.search);
const revclicRedirectId = urlParams.get('revclic_rid');

if (revclicRedirectId) {
  document.cookie = `revclic_rid=${revclicRedirectId}; max-age=2592000; path=/`;
}

Ejemplo en PHP

if (isset($_GET['revclic_rid'])) {
    $_SESSION['revclic_rid'] = $_GET['revclic_rid'];
}

2. Reportar una transacción

Después de una compra exitosa, envía la transacción a Revclic usando el endpoint Create Transaction.

Receta: transacción básica con redirección

Cuando dispongas del revclic_rid del enlace de afiliado, pásalo como redirect_id. El afiliado se resuelve automáticamente a partir de la redirección.

curl -X POST "https://api.revclic.com/merchants/{merchant_id}/transactions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_id": 1,
    "basket_items": [
      {
        "gtin": "1234567890123",
        "name": "Laptop Stand",
        "price": 49.99,
        "quantity": 2,
        "commission_rate": 10.0
      }
    ]
  }'

Receta: transacción básica sin redirección

Cuando no hay redirección disponible, debes proporcionar el affiliate_id explícitamente.

curl -X POST "https://api.revclic.com/merchants/{merchant_id}/transactions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "affiliate_id": 1,
    "basket_items": [
      {
        "gtin": "1234567890123",
        "name": "Laptop Stand",
        "price": 49.99,
        "quantity": 2,
        "commission_rate": 10.0
      }
    ]
  }'

Campos obligatorios por artículo:

Campo Descripción
gtin Código de identificación del producto (EAN o UPC)
price Precio unitario
quantity Número de unidades
commission_rate Porcentaje de comisión para este artículo

Campos opcionales:

Campo Descripción
redirect_id El ID de redirección capturado del enlace de afiliado. Cuando se proporciona, el afiliado se resuelve automáticamente.
affiliate_id El ID del afiliado. Obligatorio cuando redirect_id no se proporciona.
name Nombre del producto (para visualización)
status Estado inicial del artículo: pending (por defecto), accepted o rejected

Receta: transacción con artículos pre-aceptados

Si tu política de devoluciones no aplica (ej. productos digitales, pedidos no reembolsables), puedes reportar artículos como ya accepted al momento de la creación. Esto omite el período de validación y la comisión se incluye en la siguiente factura inmediatamente.

curl -X POST "https://api.revclic.com/merchants/{merchant_id}/transactions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_id": 1,
    "basket_items": [
      {
        "gtin": "9876543210987",
        "name": "Digital License",
        "price": 19.99,
        "quantity": 1,
        "commission_rate": 15.0,
        "status": "accepted"
      }
    ]
  }'

3. Validar o rechazar artículos

Tienes 3 meses para revisar cada artículo. Usa el endpoint Update Transaction para cambiar los estados de los artículos.

Receta: actualizar un solo artículo

Actualiza un artículo específico por su ID:

curl -X PUT "https://api.revclic.com/merchants/{merchant_id}/transactions/{transaction_id}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "basket_items": [
      { "id": 123, "status": "accepted" }
    ]
  }'

Receta: rechazar un artículo devuelto

Si el cliente devuelve un artículo:

curl -X PUT "https://api.revclic.com/merchants/{merchant_id}/transactions/{transaction_id}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "basket_items": [
      { "id": 456, "status": "rejected" }
    ]
  }'

Receta: actualizar varios artículos a la vez

Puedes actualizar varios artículos en una sola petición:

curl -X PUT "https://api.revclic.com/merchants/{merchant_id}/transactions/{transaction_id}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "basket_items": [
      { "id": 123, "status": "accepted" },
      { "id": 456, "status": "rejected" }
    ]
  }'

Estados de los artículos:

Estado Significado
pending En espera de validación (por defecto)
accepted Comisión confirmada
rejected Sin comisión (devuelto, cancelado, inválido)

Reglas de validación de artículos

  • Cada artículo debe incluir su id (devuelto cuando se creó la transacción)
  • Solo puedes actualizar el campo status
  • Puedes actualizar uno, varios o todos los artículos en una sola petición
  • Los artículos no revisados en 3 meses son aceptados automáticamente
  • La comisión solo se calcula para los artículos aceptados

Entender el campo status

Cada transacción incluye un campo status de solo lectura que se calcula automáticamente a partir de los estados de sus artículos. No se puede establecer directamente en la transacción.

Valor Condición
pending Al menos un artículo sigue pending
accepted Todos los artículos son accepted, o una mezcla de accepted y rejected
rejected Todos los artículos son rejected

El status de la transacción se recalcula cada vez que cambia el estado de un artículo.

Entender el campo reward

Cada transacción incluye un campo reward de solo lectura que refleja el ciclo de facturación y pago de la comisión. Es gestionado automáticamente por Revclic y no puede establecerse manualmente.

Valor Significado
pending La comisión está esperando a que se cierre el período de validación y se genere una factura
to_be_paid Se ha generado una factura y está pendiente de pago por el comercio
paid El comercio ha pagado la factura — la comisión ahora se debe al afiliado
complete El pago al afiliado ha sido emitido

El valor de reward progresa por estas etapas en orden y solo puede avanzar.

Buenas prácticas

  • Reporta las transacciones con prontitud — envíalas tan pronto como se confirme el pedido
  • Almacena el ID de seguimiento de forma fiable — usa sesiones del lado del servidor o cookies seguras
  • Valida los artículos regularmente — no esperes a la aceptación automática
  • Usa códigos EAN/UPC significativos — ayudan a identificar productos en los informes

Endpoints relacionados