Guía de integración GraphQL

La integración del comercio consiste en conservar el identificador de redirección de Revclic y registrar y actualizar la transacción mediante GraphQL.

Endpoint y autenticación

Envía todas las operaciones mediante POST al endpoint GraphQL configurado. El cuerpo es un objeto JSON con query y variables.

Obtén un token con la mutación signin y envíalo en cada llamada protegida:

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

1. Capturar `revclic_rid`

Una visita procedente de Revclic puede llegar a una URL como esta:

https://merchant.example/product/123?revclic_rid=abc123

Valida el valor recibido y consérvalo en el servidor, dentro de la sesión o del carrito. No dependas únicamente de un parámetro presente al pagar.

2. Crear la transacción

mutation ReportTransaction($merchantId: ID!, $input: CreateTransactionInput!) {
  createTransaction(merchantId: $merchantId, input: $input) {
    id
    status { code label }
    createdAt
    basketItems { id gtin price quantity status { code label } }
  }
}

Variables con redirección:

{
  "merchantId": "1",
  "input": {
    "redirectId": "abc123",
    "basketItems": [
      {
        "name": "Auriculares",
        "gtin": "1234567890123",
        "price": "79.90",
        "quantity": 1,
        "commissionRate": "8.50",
        "status": "pending"
      }
    ]
  }
}

redirectId es opcional. Para un pedido sin redirección de Revclic, omite el campo.

Cada artículo requiere gtin, price, quantity y commissionRate. El nombre y el estado inicial son opcionales. Guarda el identificador de la transacción y los identificadores de los artículos devueltos.

3. Actualizar artículos

Utiliza updateTransaction para informar de una validación, cancelación o devolución:

mutation UpdateReportedTransaction(
  $merchantId: ID!
  $transactionId: ID!
  $input: UpdateTransactionInput!
) {
  updateTransaction(
    merchantId: $merchantId
    transactionId: $transactionId
    input: $input
  ) {
    id
    status { code label }
    basketItems { id status { code label } }
  }
}

{
  "merchantId": "1",
  "transactionId": "42",
  "input": {
    "basketItems": [
      { "id": "101", "status": "accepted" },
      { "id": "102", "status": "rejected" }
    ]
  }
}

Obtén los estados admitidos mediante transactionStatuses en lugar de fijarlos permanentemente en la integración.

Fiabilidad y seguridad

Realiza las llamadas desde el servidor y no expongas el token en el navegador.
Relaciona cada transacción con una referencia interna del pedido para evitar duplicados.
Registra los errores GraphQL y el campo errors, incluso cuando HTTP responda 200.
Reintenta con espera progresiva los errores temporales de red.
No repitas automáticamente una mutación si desconoces si la primera llamada fue procesada; comprueba antes la transacción.