Custom form tracking přes REST API

Use case

Plugin umí trackovat konverze mimo WooCommerce — typicky kontaktní formuláře, lead generation, registrace na webinář, downloady. Komunikace probíhá přes REST endpoint, který volá vaše vlastní integrace (Contact Form 7, Gravity Forms, Fluent Forms, custom skripty).

API key

• Při aktivaci pluginu se vygeneruje 48-znakový API klíč.
• Klíč najdete v option affinite_wp_affiliate_api_key — získání:

wp option get affinite_wp_affiliate_api_key

Pro regeneraci klíče smažte option a reaktivujte plugin, NEBO:

wp eval 'update_option("affinite_wp_affiliate_api_key", wp_generate_password(48, false), false);'

Endpoint

• URL: POST /wp-json/affinite-affiliate/v1/track/conversion
• Required header: X-Affinite-API-Key: {your-key}
• Per-IP rate limit: 10 requestů / 60 sekund (transient counter)

Parametry

• affiliate_code (required, string) — kód affiliate, získává se z cookie affinite_affiliate na frontendu.
• amount (required, number) — částka konverze, rozsah 0–1 000 000 (limit override přes filter affinite_track_conversion_max_amount).
• form_id (optional, string) — identifikace formuláře pro reporting.
• customer_email (optional, string, email format) — pro audit a deduplikaci.

Příklad cURL

curl -X POST https://example.com/wp-json/affinite-affiliate/v1/track/conversion 
  -H "X-Affinite-API-Key: abc123...your-48-char-key" 
  -H "Content-Type: application/json" 
  -d '{
    "affiliate_code": "ABC123",
    "amount": 1500,
    "form_id": "contact-form-7",
    "customer_email": "customer@example.com"
  }'

Příklad JS (frontend)

// V handleru po úspěšném odeslání formuláře:
const affiliateCode = document.cookie
    .split('; ')
    .find(row => row.startsWith('affinite_affiliate='))
    ?.split('=')[1];

if (affiliateCode) {
    fetch('/wp-json/affinite-affiliate/v1/track/conversion', {
        method: 'POST',
        headers: {
            'X-Affinite-API-Key': 'YOUR_KEY_FROM_SERVER',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            affiliate_code: affiliateCode,
            amount: 1500,
            form_id: 'newsletter-signup'
        })
    });
}

Pozor: API klíč musí být na serveru, NIKDY ne v public JS bundle. Pro frontend tracking použijte buď server proxy, NEBO localizace klíče přes wp_localize_script jen pro authenticated users.

Response

{
  "success": true,
  "conversion_id": 1234,
  "commission_amount": 150
}

Error codes

• 401 — chybný nebo chybějící API key
• 400 — invalid_affiliate (kód neexistuje nebo není active), invalid_amount, future amount
• 429 — rate limit překročen
• 500 — internal error (DB insert failed)
• 503 — API key neexistuje v DB