Guide d'intégration GraphQL

L'intégration marchand consiste à conserver l'identifiant de redirection Revclic puis à déclarer et mettre à jour la transaction via GraphQL.

Endpoint et authentification

Envoyez toutes les opérations avec POST vers l'endpoint GraphQL configuré. Le corps est un objet JSON contenant query et variables.

Obtenez un jeton avec la mutation signin, puis transmettez-le dans chaque appel protégé :

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

1. Capturer `revclic_rid`

Une visite provenant de Revclic peut arriver sur une URL comme :

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

Validez la valeur reçue, puis conservez-la côté serveur dans la session ou le panier. Ne dépendez pas uniquement d'un paramètre présent au moment du paiement.

2. Créer la transaction

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 avec redirection :

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

redirectId est facultatif. Pour une commande sans redirection Revclic, omettez simplement ce champ.

Chaque article exige gtin, price, quantity et commissionRate. Le nom et le statut initial sont facultatifs. Stockez l'identifiant de transaction et les identifiants d'articles renvoyés.

3. Mettre à jour les articles

Utilisez updateTransaction pour signaler une validation, une annulation ou un retour :

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

Récupérez les valeurs de statut acceptées avec transactionStatuses au lieu de les coder définitivement dans votre intégration.

Fiabilité et sécurité

Envoyez les appels depuis votre serveur ; n'exposez jamais le jeton dans le navigateur.
Associez chaque transaction à une référence de commande interne pour empêcher les doublons.
Journalisez les erreurs GraphQL et le champ errors de la réponse, même lorsque HTTP répond 200.
Prévoyez des tentatives avec temporisation pour les erreurs réseau temporaires.
Ne rejouez pas automatiquement une mutation si vous ignorez si le premier appel a été traité ; vérifiez d'abord la transaction.