Integration Guide

This guide shows how to integrate ValidonX license validation and activation into your application using PHP and JavaScript.

PHP Integration

License Validation

<?php

class ValidonX
{
    private string $apiKey;
    private string $baseUrl;

    public function __construct(string $apiKey, string $baseUrl = 'https://api.validonx.com/api')
    {
        $this->apiKey = $apiKey;
        $this->baseUrl = $baseUrl;
    }

    public function validateLicense(string $licenseKey): array
    {
        $ch = curl_init("{$this->baseUrl}/v1/integration/licenses/{$licenseKey}/validate");
        curl_setopt_array($ch, [
            CURLOPT_POST => true,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => [
                "X-API-Key: {$this->apiKey}",
                'Content-Type: application/json',
            ],
        ]);

        $response = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        $data = json_decode($response, true);

        if ($status !== 200) {
            throw new \Exception($data['error']['message'] ?? 'License validation failed');
        }

        return $data['data'];
    }

    public function createActivation(string $licenseKey, string $fingerprint, array $metadata = []): array
    {
        $ch = curl_init("{$this->baseUrl}/v1/integration/activations");
        curl_setopt_array($ch, [
            CURLOPT_POST => true,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => [
                "X-API-Key: {$this->apiKey}",
                'Content-Type: application/json',
            ],
            CURLOPT_POSTFIELDS => json_encode([
                'license_key' => $licenseKey,
                'fingerprint' => $fingerprint,
                'metadata' => $metadata,
            ]),
        ]);

        $response = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        $data = json_decode($response, true);

        if ($status !== 201 && $status !== 200) {
            throw new \Exception($data['error']['message'] ?? 'Activation failed');
        }

        return $data['data'];
    }

    public function checkEntitlements(array $codes): array
    {
        $ch = curl_init("{$this->baseUrl}/v1/integration/entitlements/check");
        curl_setopt_array($ch, [
            CURLOPT_POST => true,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => [
                "X-API-Key: {$this->apiKey}",
                'Content-Type: application/json',
            ],
            CURLOPT_POSTFIELDS => json_encode(['entitlement_codes' => $codes]),
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        return json_decode($response, true)['data'] ?? [];
    }
}

// Usage
$vx = new ValidonX('VX-your-api-key');

// Validate license
$result = $vx->validateLicense('VALIDONX-XXXX-XXXX-XXXX-XXXX');
if ($result['valid']) {
    echo "License is valid!\n";
    echo "Plan: " . ($result['license']['entitlements']['plan'] ?? 'none') . "\n";
}

// Activate on this device
$activation = $vx->createActivation(
    'VALIDONX-XXXX-XXXX-XXXX-XXXX',
    md5(php_uname()),
    ['app_version' => '2.0.0']
);

JavaScript / Node.js Integration

class ValidonX {
  constructor(apiKey, baseUrl = 'https://api.validonx.com/api') {
    this.apiKey = apiKey;
    this.baseUrl = baseUrl;
  }

  async validateLicense(licenseKey) {
    const res = await fetch(
      `${this.baseUrl}/v1/integration/licenses/${licenseKey}/validate`,
      {
        method: 'POST',
        headers: {
          'X-API-Key': this.apiKey,
          'Content-Type': 'application/json',
        },
      }
    );

    const json = await res.json();
    if (!res.ok) throw new Error(json.error?.message || 'Validation failed');
    return json.data;
  }

  async createActivation(licenseKey, fingerprint, metadata = {}) {
    const res = await fetch(`${this.baseUrl}/v1/integration/activations`, {
      method: 'POST',
      headers: {
        'X-API-Key': this.apiKey,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ license_key: licenseKey, fingerprint, metadata }),
    });

    const json = await res.json();
    if (!res.ok) throw new Error(json.error?.message || 'Activation failed');
    return json.data;
  }

  async checkEntitlements(codes) {
    const res = await fetch(
      `${this.baseUrl}/v1/integration/entitlements/check`,
      {
        method: 'POST',
        headers: {
          'X-API-Key': this.apiKey,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ entitlement_codes: codes }),
      }
    );

    const json = await res.json();
    return json.data;
  }
}

// Usage
const vx = new ValidonX('VX-your-api-key');

const result = await vx.validateLicense('VALIDONX-XXXX-XXXX-XXXX-XXXX');
console.log('Valid:', result.valid);
console.log('Plan:', result.license?.entitlements?.plan);

const activation = await vx.createActivation(
  'VALIDONX-XXXX-XXXX-XXXX-XXXX',
  'device-fingerprint-hash',
  { app_version: '2.0.0', os: 'Linux' }
);
console.log('Activation ID:', activation.activation_id);

Error Handling

All errors follow the standard envelope format. Always check for error responses:

try {
  const result = await vx.validateLicense(key);
} catch (error) {
  // error.message contains the human-readable error
  // Common codes: LICENSE.NOT_FOUND, LICENSE.REVOKED, RATE_LIMIT.EXCEEDED
}

Rate Limiting

Check response headers to monitor your rate limit status:

const res = await fetch(url, options);
const remaining = res.headers.get('X-RateLimit-Remaining');
const limit = res.headers.get('X-RateLimit-Limit');
console.log(`${remaining}/${limit} requests remaining`);

If you receive a 429 response, wait for the Retry-After seconds before retrying.