Documentatie

Systeemvereisten

• WordPress 6.0 of nieuwer
• PHP 7.4 of nieuwer
• Een actieve installatie van WooCommerce
• Een geldige licentie voor Cart URL Generator Pro for WooCommerce
• WooCommerce Composite Products is alleen nodig wanneer je samengestelde producten wilt gebruiken

Installatie en activatie

1. Download het ZIP-bestand van Cart URL Generator Pro for WooCommerce.
2. Ga in WordPress naar Plugins > Nieuwe plugin toevoegen.
3. Kies Plugin uploaden en selecteer het ZIP-bestand.
4. Installeer en activeer de plugin.
5. Open Cart URL Generator Pro for WooCommerce in het WordPress-beheer.
6. Open indien nodig de pagina Account om je licentie te activeren.

Een winkelwagenlink maken

1. Selecteer één of meerdere producten.
2. Kies bij variabele producten de gewenste productvariatie.
3. Stel per product het gewenste aantal in.
4. Configureer waar nodig de onderdelen van een Composite Product.
5. Voeg optioneel een bestaande WooCommerce-kortingscode toe.
6. Kies of de klant naar de winkelwagen of direct naar de checkout wordt gestuurd.
7. Genereer de winkelwagenlink.
8. Kopieer, open of bewaar de gegenereerde link.

Ondersteunde producttypen

Eenvoudige producten

Variabele producten

WooCommerce Composite Products

Andere productuitbreidingen

Kortingscodes

Je kunt een bestaande WooCommerce-coupon aan een winkelwagenlink koppelen. Wanneer de klant de link opent, probeert WooCommerce de coupon automatisch op de samengestelde winkelwagen toe te passen.

De REST API kan uitsluitend een reeds bestaande couponcode gebruiken. Via de API kunnen geen nieuwe coupons worden aangemaakt en kunnen geen kortingsbedragen, kortingstypen, gebruikslimieten, vervaldata of andere couponvoorwaarden worden ingesteld.

WooCommerce voert bij het openen van de link de definitieve controle uit op basis van de daadwerkelijke winkelwagen en, waar relevant, de klantgegevens.

Daarbij blijven de normale WooCommerce-couponvoorwaarden gelden, waaronder:

• begin- en vervaldatum;
• minimale en maximale besteding;
• product- en categoriebeperkingen;
• gebruiksbeperkingen en gebruikslimieten;
• combinatie met andere coupons;
• beperkingen per klant of e-mailadres.

Opgeslagen winkelwagenlinks

REST API

Endpoint

POST https://jouwdomein.nl/wp-json/cart-url-generator/v1/create-link

Verplichte headers

Content-Type: application/json
X-CUG-API-Key: cug_live_JOUW_API_SLEUTEL

API-sleutels beheren

• De volledige sleutel wordt uitsluitend direct na het aanmaken getoond.
• Bewaar de sleutel meteen op een veilige plaats.
• De plugin bewaart de volledige sleutel daarna niet leesbaar in WordPress.
• Een afzonderlijke sleutel kan op ieder moment worden ingetrokken.
• Na intrekking werken aanvragen met die sleutel onmiddellijk niet meer.

Opbouw van een API-aanvraag

Beschikbare hoofdvelden

Velden per item

API-voorbeelden

Eenvoudig product

{
  "items": [
    {
      "product_id": 123,
      "quantity": 1
    }
  ],
  "redirect": "cart"
}

Meerdere producten

{
  "items": [
    {
      "product_id": 123,
      "quantity": 2
    },
    {
      "product_id": 456,
      "quantity": 1
    }
  ],
  "redirect": "checkout"
}

Productvariatie

{
  "items": [
    {
      "product_id": 789,
      "quantity": 1
    }
  ],
  "redirect": "checkout"
}

Bestaande coupon toepassen

{
  "items": [
    {
      "product_id": 123,
      "quantity": 1
    }
  ],
  "coupon_code": "WELKOM10",
  "redirect": "checkout"
}

WooCommerce Composite Product

{
  "items": [
    {
      "product_id": 16004,
      "quantity": 1,
      "type": "composite",
      "components": {
        "1780264036": {
          "product_id": 13007,
          "quantity": 1,
          "variation_id": 13043,
          "attributes": {
            "attribute_pa_kleur": "donkerblond"
          }
        }
      }
    }
  ],
  "redirect": "checkout"
}

cURL-voorbeeld

curl --request POST \
  --url "https://jouwdomein.nl/wp-json/cart-url-generator/v1/create-link" \
  --header "Content-Type: application/json" \
  --header "X-CUG-API-Key: cug_live_JOUW_API_SLEUTEL" \
  --data '{
    "items": [
      {
        "product_id": 123,
        "quantity": 1
      }
    ],
    "redirect": "checkout"
  }'

JavaScript-voorbeeld voor een beveiligde serveromgeving

const response = await fetch(
  "https://jouwdomein.nl/wp-json/cart-url-generator/v1/create-link",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-CUG-API-Key": process.env.CUG_API_KEY
    },
    body: JSON.stringify({
      items: [
        {
          product_id: 123,
          quantity: 1
        }
      ],
      redirect: "checkout"
    })
  }
);

const data = await response.json();

if (!response.ok) {
  throw new Error(data.message || "De winkelwagenlink kon niet worden gemaakt.");
}

console.log(data.url);

PHP-voorbeeld

$response = wp_remote_post(
    'https://jouwdomein.nl/wp-json/cart-url-generator/v1/create-link',
    [
        'timeout' => 20,
        'headers' => [
            'Content-Type'  => 'application/json',
            'X-CUG-API-Key' => getenv( 'CUG_API_KEY' ),
        ],
        'body' => wp_json_encode(
            [
                'items' => [
                    [
                        'product_id' => 123,
                        'quantity'   => 1,
                    ],
                ],
                'redirect' => 'checkout',
            ]
        ),
    ]
);

if ( is_wp_error( $response ) ) {
    throw new RuntimeException( $response->get_error_message() );
}

$status = wp_remote_retrieve_response_code( $response );
$data   = json_decode( wp_remote_retrieve_body( $response ), true );

if ( $status < 200 || $status >= 300 || empty( $data['url'] ) ) {
    throw new RuntimeException(
        isset( $data['message'] )
            ? $data['message']
            : 'De winkelwagenlink kon niet worden gemaakt.'
    );
}

$cart_url = $data['url'];

API-response

Succesvolle aanvraag

{
  "success": true,
  "url": "https://jouwdomein.nl/?cug_add=...",
  "meta": {
    "items": 1,
    "redirect": "checkout",
    "coupon_applied": false
  }
}

Foutresponse

{
  "code": "cug_invalid_items",
  "message": "Items array is required and must not be empty.",
  "data": {
    "status": 400
  }
}

Veelvoorkomende API-statussen

Rate limiting

API-verzoeklogboek

Beveiligingsrichtlijnen

• Gebruik uitsluitend HTTPS voor API-aanvragen en winkelwagenlinks.
• Maak voor iedere externe koppeling een aparte API-sleutel.
• Sla sleutels op in een beveiligde secret store of serverconfiguratie.
• Plaats API-sleutels nooit in publieke frontend-code.
• Trek een sleutel direct in wanneer deze mogelijk is uitgelekt.
• Geef externe systemen alleen toegang tot de sleutels die zij daadwerkelijk nodig hebben.
• Deel links met een coupon alleen met de bedoelde ontvangers.
• Gebruik de API niet om bestellingen of betalingen te simuleren.
• Valideer de API-response voordat je de teruggegeven URL gebruikt.

Cache en beveiligingsplugins

WooCommerce-compatibiliteit

• Eenvoudige WooCommerce-producten worden ondersteund.
• Concrete WooCommerce-productvariaties worden ondersteund.
• Bestaande WooCommerce-coupons kunnen worden toegepast.
• Doorverwijzing naar winkelwagen en checkout wordt ondersteund.
• WooCommerce HPOS wordt ondersteund.
• Traditionele WooCommerce-orderopslag blijft bruikbaar.
• Standaardconfiguraties van de officiële WooCommerce Composite Products-extensie worden ondersteund.

Probleemoplossing

De API retourneert geen winkelwagenlink

• Controleer of de plugin en WooCommerce actief zijn.
• Controleer of het endpoint op het juiste domein wordt aangeroepen.
• Controleer of de aanvraag met POST wordt verzonden.
• Controleer of Content-Type: application/json aanwezig is.
• Controleer de header X-CUG-API-Key.
• Controleer of de gebruikte API-sleutel nog actief is.
• Controleer of items een niet-lege array is.
• Controleer het API-verzoeklogboek in WordPress.

Een product wordt niet aan de winkelwagen toegevoegd

• Controleer of het product gepubliceerd en koopbaar is.
• Controleer de voorraadstatus.
• Gebruik bij een variabel product het concrete variatie-ID.
• Controleer of de gekozen variatie nog bestaat en actief is.
• Controleer bij een Composite Product alle verplichte componenten.
• Controleer of een andere plugin de WooCommerce add-to-cart-validatie beïnvloedt.

De coupon wordt niet toegepast

• Controleer of de couponcode exact overeenkomt.
• Controleer of de coupon gepubliceerd en niet verlopen is.
• Controleer minimale besteding, productbeperkingen en gebruikslimieten.
• Controleer of de coupon met andere actieve coupons gecombineerd mag worden.
• Controleer de WooCommerce-melding die na het openen van de link verschijnt.

De API geeft status 429

De link werkt bij de beheerder, maar niet bij bezoekers

• Test de link in een privévenster.
• Leeg de pagina- en objectcache.
• Sluit cug_add-URL's uit van caching en prefetching.
• Controleer firewall- en beveiligingsregels.
• Controleer of de producten voor gewone bezoekers koopbaar zijn.

Gegevens en verwijderen van de plugin

Support

• de gebruikte pluginversie;
• de WordPress- en WooCommerce-versie;
• het gebruikte endpoint zonder API-sleutel;
• de HTTP-status en foutcode;
• een geanonimiseerd voorbeeld van de JSON-body;
• relevante informatie uit het API-verzoeklogboek;
• de stappen waarmee het probleem kan worden gereproduceerd.