API Server-a-Server (IT)

Informazioni chiave :
Base URL: https://a.pwspace.com
Metodo: GET
Formato: Parametri della stringa di query
Autenticazione: Click ID fornito da Powerspace

1. Panoramica

L'API Server-to-Server (S2S) di Powerspace consente agli inserzionisti di notificare in tempo reale le conversioni generate dopo un clic pubblicitario. Sono supportati due tipi di conversioni:

• Lead: Generazione di un prospect qualificato
• Order: Finalizzazione di un ordine con valore

📘 Principio di funzionamento
Quando un utente clicca sulla tua pubblicità Powerspace, viene reindirizzato al tuo sito con un parametro clickId univoco. Questo parametro deve essere conservato e utilizzato per notificare le conversioni tramite l'API S2S.

2. Flusso di conversione

Passo 1: Clic pubblicitario
L'utente clicca sulla tua pubblicità Powerspace e arriva sul tuo sito con l'URL:
https://tuo-sito.com/landing?clickId=abc123xyz789&utm_source=powerspace

Passo 2: Conservazione del Click ID
Il tuo sito deve conservare il clickId (cookie, sessione, database) per associarlo alle azioni dell'utente.

Passo 3: Notifica di conversione
Quando si verifica una conversione, chiama l'API S2S corrispondente con il clickId conservato.

3. Endpoint disponibili

Notifica Lead
GET https://a.pwspace.com/ld?qci={clickId}
Notifica la generazione di un lead (prospect qualificato).

Notifica Order
GET https://a.pwspace.com/ord?qci={clickId}&ov={order-value}
Notifica la finalizzazione di un ordine con il suo valore.

📘 Importanza del valore dell'ordine
Sebbene opzionale, il parametro ov (order value) è fortemente raccomandato. Permette di riportare il valore nelle tue statistiche Powerspace e di ottimizzare la gestione delle tue campagne pubblicitarie.

4. Esempi di implementazione

Scenario Lead

# L'utente si iscrive alla tua newsletter  
curl "https://a.pwspace.com/ld?qci=abc123xyz789"  

Scenario Lead

# L'utente finalizza un acquisto di 89.99€  
curl "https://a.pwspace.com/ord?qci=abc123xyz789&ov=89.99"  

PHP - Gestione completa

<?php  
// 1. Recupero del clickId all'arrivo sul sito  
if (isset($_GET['clickId'])) {  
    $_SESSION['powerspace_click_id'] = $_GET['clickId'];  
}  

// 2. Notifica di un lead  
function notifyLead($clickId) {  
    $url = "https://a.pwspace.com/ld?qci=" . urlencode($clickId);  
    file_get_contents($url);  
}  

// 3. Notifica di un ordine  
function notifyOrder($clickId, $orderValue) {  
    $url = "https://a.pwspace.com/ord?qci=" . urlencode($clickId) . "&ov=" . $orderValue;  
    file_get_contents($url);  
}  

// Esempio di utilizzo  
if (isset($_SESSION['powerspace_click_id'])) {  
    // Lead generato  
    notifyLead($_SESSION['powerspace_click_id']);  
      
    // O ordine finalizzato  
    notifyOrder($_SESSION['powerspace_click_id'], 129.99);  
}  
?>  

Python

import requests  
from urllib.parse import urlencode  

def notify_lead(click_id):  
    """Notifica un lead generato"""  
    url = f"https://a.pwspace.com/ld?qci={click_id}"  
    try:  
        response = requests.get(url, timeout=5)  
        return response.status_code == 200  
    except requests.RequestException:  
        return False  

def notify_order(click_id, order_value):  
    """Notifica un ordine finalizzato"""  
    params = {'qci': click_id, 'ov': order_value}  
    url = f"https://a.pwspace.com/ord?{urlencode(params)}"  
    try:  
        response = requests.get(url, timeout=5)  
        return response.status_code == 200  
    except requests.RequestException:  
        return False  

# Esempio di utilizzo  
click_id = "abc123xyz789"  
notify_lead(click_id)  
notify_order(click_id, 89.99)  

5. Codici di risposta

6. Buone pratiche

Gestione del Click ID

• Conserva il clickId fin dall'arrivo dell'utente
• Associalo alla sessione o al profilo utente
• Persistilo in database per conversioni differite
• Pulisci i vecchi clickId (scadenza ~30 giorni)

Chiamate API

• Chiama immediatamente dopo la conversione
• Gestisci i timeout (max 5 secondi raccomandato)
• Non bloccare l'esperienza utente in caso di fallimento
• Logga le chiamate per il debug

Valore dell'ordine

• Invia sempre il valore reale dell'ordine
• Usa il formato decimale (es: 49.99, non 4999)
• Escludi le spese di spedizione se richiesto
• Includi le tasse secondo la tua configurazione

7. Casi d'uso avanzati

Conversioni multiple
Lo stesso clickId può generare più conversioni:

# Prima un lead  
curl "https://a.pwspace.com/ld?qci=abc123xyz789"  

# Poi un ordine (stesso clickId)  
curl "https://a.pwspace.com/ord?qci=abc123xyz789&ov=159.99"  

Attribuzione differita Per conversioni che arrivano giorni dopo il clic:

// Memorizzazione in database al clic  
$pdo->prepare("INSERT INTO user_attribution (user_id, click_id, created_at) VALUES (?, ?, NOW())")  
    ->execute([$userId, $clickId]);  

// Recupero alla conversione  
$stmt = $pdo->prepare("SELECT click_id FROM user_attribution WHERE user_id = ?");  
$stmt->execute([$userId]);  
$clickId = $stmt->fetchColumn();  

if ($clickId) {  
    notifyOrder($clickId, $orderValue);  
}  

8. Debug e monitoring

Verifica delle chiamate

• Logga tutte le chiamate S2S con timestamp
• Monitora il tasso di successo delle chiamate
• Allerta sui fallimenti ripetuti

Test in sviluppo

# Test con clickId fittizio  
curl "https://a.pwspace.com/ld?qci=test_click_id_123"  
curl "https://a.pwspace.com/ord?qci=test_click_id_123&ov=99.99"  

9. Check-list di integrazione

• ✅ Recupero e memorizzazione del clickId dall'URL
• ✅ Conservazione del clickId per tutta la sessione utente
• ✅ Chiamata lead alla generazione di un prospect
• ✅ Chiamata order con valore a un ordine
• ✅ Gestione timeout ed errori di rete
• ✅ Logging delle chiamate per monitoring
• ✅ Test in ambiente di sviluppo
• ✅ Validazione in produzione con conversioni reali

Supporto tecnico
Per qualsiasi domanda sull'integrazione S2S:

• Documentazione: Questa pagina
• Supporto: Contatta il tuo account manager Powerspace
• Test: Usa clickId di test in sviluppo