Documentazione & API Reference

Guida tecnica esaustiva, architettura di sicurezza e specifiche API REST per l'intero ecosistema di moduli WordPress, WooCommerce e microservizi cloud BeraLabs.

⚡ Architettura BeraLabs & Quickstart

L'ecosistema BeraLabs combina moduli software on-premise per WordPress / WooCommerce (gestiti con rigore architetturale e conformità HPOS) con microservizi cloud headless su protocolli ad alta frequenza (WhatsApp Cloud API basata su runtime Baileys, Cart Recovery Engine e Analytics POAS).

⚡
Base URL API

Tutte le chiamate API di produzione transitano su endpoint protetti HTTPS:
https://beralabs.it/api

🔒
Autenticazione Sicura

Supporto nativo per API Key individuali con token di test e produzione (blk_live_... / blk_test_...).

🛡️
Integrità HMAC SHA-256

Firma crittografica bidirezionale su tutti i payload dei webhook per eliminare ogni rischio di replay attack.

Standard dei Payload

Tutte le richieste API devono essere inviate con metodo POST (o GET per le letture) con intestazione Content-Type: application/json; charset=utf-8. Le risposte sono sempre formattate in JSON con codifica UTF-8 nativa.

Autenticazione con API Key

Ogni richiesta verso i servizi cloud di BeraLabs (WhatsApp Gateway, Cart Recovery, Newsletter Engine) deve contenere la propria chiave API valida in uno dei due header HTTP supportati:

  • Header personalizzato raccomandato: X-Bera-API-Key: blk_live_xxxxxxxxxxxxxxxxxxxxxxxx
  • Header standard OAuth/Bearer: Authorization: Bearer blk_live_xxxxxxxxxxxxxxxxxxxxxxxx
Prefisso Chiave Ambiente Descrizione Invio Messaggi Reali
blk_live_... Produzione Invia messaggi WhatsApp ed elabora carrelli reali degli utenti Sì (consegna immediata)
blk_test_... Sandbox / Staging Simula le risposte API, convalida i payload e logga gli eventi senza recapito effettivo No (mock response 200 OK)

Sicurezza & Firme HMAC SHA-256

Quando BeraLabs invia un webhook verso il tuo e-commerce (es. notifica di avvenuto recupero carrello o conferma di verifica OTP), la richiesta contiene due header di sicurezza critici:

  • X-Bera-Timestamp: Timestamp UNIX (secondi) in cui è stato generato l'evento. Rifiuta richieste con una differenza superiore a 300 secondi (5 minuti) per prevenire attacchi di tipo replay.
  • X-Bera-Signature: Firma esadecimale generata con algoritmo HMAC-SHA256 applicato alla concatenazione $timestamp . '.' . $raw_payload usando il tuo Webhook Secret.
function verify_beralabs_webhook() {
    $secret = get_option('beralabs_webhook_secret');
    $signature = $_SERVER['HTTP_X_BERA_SIGNATURE'] ?? '';
    $timestamp = $_SERVER['HTTP_X_BERA_TIMESTAMP'] ?? '';
    $raw_body  = file_get_contents('php://input');

    // 1. Controllo anti-replay (max 5 minuti di scarto)
    if (abs(time() - intval($timestamp)) > 300) {
        wp_send_json_error(['error' => 'Timestamp expired or clock skew detected'], 401);
    }

    // 2. Calcolo firma attesa
    $expected_sig = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $raw_body, $secret);

    // 3. Comparazione temporale costante (anti timing-attack)
    if (!hash_equals($expected_sig, $signature)) {
        wp_send_json_error(['error' => 'Invalid HMAC signature'], 403);
    }

    // Payload autenticato e integro
    $data = json_decode($raw_body, true);
    return $data;
}
const crypto = require('crypto');

function verifyBeraWebhook(req, res, next) {
    const secret = process.env.BERALABS_WEBHOOK_SECRET;
    const signature = req.headers['x-bera-signature'];
    const timestamp = req.headers['x-bera-timestamp'];
    const rawBody = req.rawBody; // Assicurati di catturare il buffer o raw string

    if (!signature || !timestamp) {
        return res.status(401).json({ error: 'Missing security headers' });
    }

    if (Math.abs(Date.now() / 1000 - parseInt(timestamp, 10)) > 300) {
        return res.status(401).json({ error: 'Timestamp expired' });
    }

    const hmac = crypto.createHmac('sha256', secret);
    const expectedSig = 'sha256=' + hmac.update(`${timestamp}.${rawBody}`).digest('hex');

    if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSig))) {
        return res.status(403).json({ error: 'Invalid HMAC signature' });
    }

    next();
}
import hmac
import hashlib
import time

def verify_bera_signature(raw_body: bytes, signature_header: str, timestamp_header: str, secret: str) -> bool:
    try:
        ts = int(timestamp_header)
        if abs(time.time() - ts) > 300:
            return False
            
        expected = "sha256=" + hmac.new(
            secret.encode('utf-8'),
            f"{ts}.".encode('utf-8') + raw_body,
            hashlib.sha256
        ).hexdigest()
        
        return hmac.compare_digest(expected, signature_header)
    except Exception:
        return False

Rate Limiting & Intestazioni HTTP

Le API di BeraLabs adottano un algoritmo di token bucket con finestre scorrevoli al minuto. Ogni risposta restituisce i metadati sul consumo residuo del piano:

Header HTTP Descrizione Esempio Valore
X-RateLimit-Limit Numero massimo di richieste permesse nella finestra corrente (60s) 120
X-RateLimit-Remaining Richieste ancora disponibili prima dell'attivazione del blocco 118
X-RateLimit-Reset Timestamp UNIX in cui la finestra temporale viene ripristinata 1731683400
Retry-After Restituito solo in caso di risposta 429: numero di secondi di attesa obbligatoria 45

🔒 Woo COD Anti-Fraud (WCCAF)

Woo COD Anti-Fraud è il plugin di riferimento per WooCommerce per eliminare le perdite legate agli ordini in contrassegno (Cash on Delivery). Protegge il merchant da pacchi rifiutati, indirizzi fake e acquirenti seriali fraudolenti combinando un motore predittivo di Risk Scoring con la verifica istantanea via OTP su WhatsApp.

⚡
Requisiti di Sistema

WordPress 6.0+, WooCommerce 7.0+, PHP 7.4 - 8.3. Pienamente compatibile con WooCommerce HPOS (High-Performance Order Storage).

🛡️
Zero Modifiche al Tema

Si inietta tramite hook nativi di WooCommerce (woocommerce_review_order_before_submit o modale AJAX).

📲
Gateway Baileys Incluso

Invio OTP su WhatsApp a costo zero o tramite WhatsApp Cloud API ufficiale.

Algoritmo di Risk Scoring & Logica Euristica

A ogni checkout in cui viene selezionato il metodo "Contrassegno", il motore di WCCAF calcola un punteggio di rischio (Risk Score) da 0 a 100 aggregando molteplici vettori:

Vettore di Analisi Impatto Score Descrizione & Criterio di Calcolo
Phone Carrier & Format +15 a +35 Rileva prefissi VoIP virtuali non associati a SIM fisiche, numeri temporanei o discordanza con il prefisso internazionale del Paese di spedizione.
CAP & Geospatial Mismatch +20 a +40 Verifica la coerenza tra il Codice di Avviamento Postale (CAP), la città e la provincia dichiarata nei campi di fatturazione/spedizione.
Order Frequency / Velocity +25 a +50 Rileva tentativi multipli di checkout ravvicinati dallo stesso indirizzo IP o cookie di sessione nelle ultime 24 ore.
Blacklist Check +80 a +100 Verifica istantanea del telefono, dell'email o del range IP contro la blacklist locale e la threat intelligence BeraLabs.
Soglie di Azione Configurate

0 - 30 (Basso Rischio): Ordine autorizzato direttamente senza interruzioni.
31 - 70 (Medio Rischio): Attivazione obbligatoria della modale OTP WhatsApp prima dell'invio ordine.
71 - 100 (Alto Rischio): Metodo di contrassegno nascosto automaticamente con invito a pagare con Carta di Credito, oppure blocco immediato.

Verifica OTP WhatsApp al Checkout

Quando il cliente seleziona il Contrassegno e clicca su "Effettua Ordine", il plugin intercetta la richiesta via JavaScript e presenta una modale responsive elegante e dark:

  • Invio automatico di un messaggio WhatsApp con codice a 6 cifre: "Il tuo codice di verifica per l'ordine #10482 è: 849201. Valido per 5 minuti."
  • Countdown di 60 secondi prima di consentire la richiesta di un nuovo invio (rate-limiting anti-abuso).
  • Possibilità di fallback automatico via SMS nel caso in cui il numero non risulti registrato su WhatsApp.
  • Al superamento di 3 tentativi errati, la sessione viene invalidata e il metodo contrassegno viene temporaneamente sospeso.

Regole Avanzate CAP & Sovrapprezzo (Surcharge) Dinamico

WCCAF consente di applicare un costo accessorio al contrassegno per coprire le tariffe del corriere o disincentivare i clienti rischiosi:

  • Sovrapprezzo Fisso o Percentuale: es. €3.50 fissi oppure 2.5% del totale carrello.
  • Zone Remote & Isole: Possibilità di definire una lista di CAP (es. 30100, 30124, 07020-07029, 92010) a cui applicare un sovrapprezzo maggiorato o inibire del tutto il contrassegno per via dell'elevato tasso di giacenza.

Action & Filter Hooks PHP per Sviluppatori

Il plugin espone un'architettura estensibile basata sugli hook standard di WordPress. Puoi inserire questi filtri nel functions.php del tema child o in un mu-plugin personalizzato:

/**
 * Modifica dinamicamente il sovrapprezzo del contrassegno in base al totale o al ruolo cliente
 */
add_filter('wccaf_cod_surcharge_amount', function ($fee_amount, $cart) {
    // Se l'utente è un rivenditore B2B (ruolo 'wholesale'), azzera il supplemento contrassegno
    if (current_user_can('wholesale_customer')) {
        return 0.00;
    }
    
    // Se il carrello supera i 150€, riduci la commissione al 50%
    if ($cart->get_subtotal() > 150.00) {
        return $fee_amount * 0.5;
    }

    return $fee_amount;
}, 10, 2);
/**
 * Personalizza le soglie di rischio del Risk Engine
 */
add_filter('wccaf_fraud_score_thresholds', function ($thresholds, $order_data) {
    // Rendi il controllo più permissivo per i clienti già registrati con ordini completati
    $customer_id = $order_data['customer_id'] ?? 0;
    if ($customer_id > 0 && wc_get_customer_order_count($customer_id) >= 3) {
        $thresholds['otp_required_min'] = 60; // Richiedi OTP solo sopra 60 anziché 30
    }
    return $thresholds;
}, 10, 2);
/**
 * Esegue un'azione non appena l'OTP WhatsApp viene confermato con successo
 */
add_action('wccaf_otp_verified', function ($order_id, $phone, $timestamp) {
    // Salva metadato personalizzato nell'ordine HPOS
    $order = wc_get_order($order_id);
    if ($order) {
        $order->update_meta_data('_wccaf_whatsapp_verified_at', current_time('mysql'));
        $order->add_order_note(sprintf(
            __('Verifica OTP WhatsApp completata con successo per il numero %s alle %s.', 'woo-cod-antifraud'),
            $phone,
            date('d/m/Y H:i:s', $timestamp)
        ));
        $order->save();
    }
}, 10, 3);

📊 Profit Warden — Motore POAS & Margine Reale

Profit Warden è il CFO digitale nativo per WooCommerce. Supera la metrica obsoleta e ingannevole del ROAS (Return On Ad Spend) per implementare il vero POAS (Profit On Ad Spend), calcolando il margine netto reale in tempo reale per ogni singolo ordine e prodotto.

La Formula Matematica di Profit Warden

Utile Netto = Fatturato Lordo - COGS (Costo Merci) - Costi Spedizione - Commissioni Gateway - Spesa Adv (Meta/Google) - Imposte
POAS = Profitto Lordo Reale / Spesa Pubblicitaria

Gestione COGS & Commissioni Gateway

Profit Warden consente di mappare con precisione tutti i costi vivi che erodono il margine dell'e-commerce:

  • COGS a Livello Prodotto & Variazione: campo dedicato nei dati di prodotto WooCommerce (_profit_warden_cogs) per impostare il costo di acquisto/produzione per ogni SKU. Supporto per import/export massivo via CSV.
  • Costi di Spedizione Vivi: differenza tra quanto pagato dal cliente in cassa e il costo contrattuale effettivo concordato con il corriere (es. GLS, BRT, DHL).
  • Commissioni Gateway di Pagamento: calcolo automatico della quota fissa e percentuale per ogni gateway (Stripe 1.5% + €0.25, PayPal 3.4% + €0.35, Klarna, Scalapay, Nexi, Contrassegno).
  • WooCommerce HPOS Nativo: tutti i dati matematici vengono salvati direttamente nella tabella degli ordini HPOS ad alte prestazioni, con zero query N+1 e zero impatto sulle performance del database.

Action & Filter Hooks PHP di Profit Warden

Sviluppatori e software house possono integrare gestionali ERP esterni o regole di calcolo complesse tramite i filtri PHP:

/**
 * Sovrascrive il COGS leggendolo in tempo reale da un gestionale ERP esterno o tabella personalizzata
 */
add_filter('profit_warden_custom_cogs', function ($cogs, $product_id, $variation_id) {
    $target_id = $variation_id ? $variation_id : $product_id;
    $sku = get_post_meta($target_id, '_sku', true);

    // Esempio: recupero costo dinamico da cache Redis o DB ERP
    $erp_cost = get_transient('erp_cogs_' . $sku);
    if ($erp_cost !== false) {
        return floatval($erp_cost);
    }

    return $cogs;
}, 10, 3);
/**
 * Applica una tariffa gateway contrattualizzata personalizzata per Stripe Italia
 */
add_filter('profit_warden_gateway_fee', function ($calculated_fee, $payment_method, $order_total) {
    if ($payment_method === 'stripe') {
        // Accordo enterprise: 1.1% + 0.18€ fisso per transazione UE
        return ($order_total * 0.011) + 0.18;
    }
    return $calculated_fee;
}, 10, 3);
/**
 * Invia il profitto netto dell'ordine alla piattaforma di BI o Google Sheets
 */
add_action('profit_warden_profit_computed', function ($order_id, $profit_breakdown) {
    // $profit_breakdown contiene: ['net_profit', 'gross_profit', 'cogs', 'shipping_cost', 'gateway_fee']
    if ($profit_breakdown['net_profit'] < 0) {
        // Notifica immediata su Telegram se un ordine chiude con margine negativo
        do_action('send_telegram_alert', sprintf("⚠️ Ordine #%d in perdita! Margine: €%.2f", $order_id, $profit_breakdown['net_profit']));
    }
}, 10, 2);

✨ GeoSchemaForge & BeraLab GEO Engine

GeoSchemaForge (noto anche come BeraLab GEO Engine) è il sistema di Generative Engine Optimization (GEO) e Answer Engine Optimization (AEO) per WordPress e Joomla. Permette a portali, e-commerce e brand di essere indicizzati e citati come fonte primaria nei motori di ricerca generativi di nuova generazione: ChatGPT Search, Perplexity AI, Claude 3.5, Google AI Overviews (SGE).

🧠
Grafo Semantico @graph

Iniezione automatica di grafi JSON-LD Schema.org nidificati e interconnessi: WebSite, Organization, LocalBusiness, FAQPage, Speakable.

🤖
LLMs.txt Ready

Esposizione automatica degli standard web /llms.txt e /llms-full.txt per il consumo machine-readable da parte dei crawler AI.

📍
Precisione Geospaziale

Coordinate GPS ad alta definizione (latitudine, longitudine, GeoCoordinates), poligoni GeoShape e orari multiriga ISO 8601.

Integrazione Endpoint Machine-Readable /llms.txt

Il plugin genera e serve nativamente alla root del sito gli standard proposti per l'interazione diretta con i Large Language Model:

  • /llms.txt: file Markdown sintetico e ad altissima densità informativa per consentire ad agenti e crawler AI di comprendere il business con il minimo consumo di token di contesto.
  • /llms-full.txt: esportazione completa di documentazione, schede tecniche e conoscenza aziendale formattata per procedure RAG (Retrieval-Augmented Generation).
/**
 * Aggiunge nodi personalizzati o certificazioni aziendali al grafo JSON-LD iniettato
 */
add_filter('geoschemaforge_jsonld_output', function ($graph_data, $post_id) {
    // Aggiungi una certificazione ISO al nodo Organization
    foreach ($graph_data['@graph'] as &$node) {
        if ($node['@type'] === 'Organization') {
            $node['hasCredential'] = [
                '@type' => 'EducationalOccupationalCredential',
                'name'  => 'ISO 27001 Certified Security'
            ];
        }
    }
    return $graph_data;
}, 10, 2);

[geoschema_business layout="card" show_map="yes" show_hours="yes"]


[geoschema_faq category="e-commerce" limit="5"]

🛒 WhatsApp Cart Recovery (OBJ-11)

WhatsApp Cart Recovery consente di recuperare fino al 45% dei carrelli abbandonati su WooCommerce sfruttando il canale più diretto ed efficace in assoluto: WhatsApp (98% Open Rate, 45-60% CTR). Il sistema include la tecnologia di Live Checkout Capture che registra i dati prima ancora che il cliente abbandoni la pagina.

POST https://beralabs.it/api/cart-recovery

L'endpoint riceve il payload dell'evento di carrello orfano inviato dal checkout o dallo script client quando l'utente compila il campo telefono e sposta il cursore (evento JavaScript onblur con debounce di 500ms):

Parametro Tipo Obbligatorio Descrizione
phone String Sì Numero di telefono del cliente in formato internazionale standard E.164 (es. +393401234567).
customer_name String Sì Nome di battesimo o ragione sociale dell'acquirente (usato per personalizzare il messaggio).
cart_token String Sì Identificativo univoco di sessione carrello generato da WooCommerce (es. ct_9f8e7d6c5b4a).
cart_total Float Sì Valore monetario totale degli articoli presenti nel carrello.
currency String No Codice valuta ISO a 3 lettere (default: EUR).
items Array Sì Elenco dei prodotti con product_id, name, quantity, price, image_url.
recovery_url String Sì URL con Magic Link per il ripristino immediato con 1 solo click su WhatsApp.
delay_minutes Integer No Minuti di attesa prima dell'invio del primo messaggio (default: 20).
discount_code String No Coupon promozionale opzionale (es. TORNA10) da applicare automaticamente.

Esempio di Payload Richiesta (JSON)

Request JSON Body
{
  "phone": "+393401234567",
  "customer_name": "Mario Rossi",
  "cart_token": "ct_9f8e7d6c5b4a",
  "currency": "EUR",
  "cart_total": 89.90,
  "items": [
    {
      "product_id": 412,
      "name": "Scarpe Running Nitro Pro",
      "quantity": 1,
      "price": 89.90,
      "image_url": "https://negozio.com/wp-content/uploads/nitro.jpg"
    }
  ],
  "recovery_url": "https://negozio.com/cart?restore=ct_9f8e7d6c5b4a&token=sec_abc123",
  "delay_minutes": 20,
  "discount_code": "TORNA10"
}

Esempio di Risposta di Successo (HTTP 201 Created)

Response 201 Created
{
  "success": true,
  "recovery_id": "rec_7832a8901fbc",
  "status": "scheduled",
  "scheduled_at": "2026-03-30T10:45:00Z",
  "phone": "+393401234567",
  "message_preview": "Ciao Mario! Hai dimenticato le tue Scarpe Running Nitro Pro nel carrello. Clicca qui per completare l'ordine con il 10% di sconto riservato: https://negozio.com/cart?restore=ct_9f8e7d6c5b4a"
}

Webhooks di Conversione e Tracciamento

Non appena l'utente finalizza l'acquisto tramite il link di recupero, il sistema invia una notifica webhook POST verso il tuo endpoint registrato con evento cart.recovered:

Webhook Event: cart.recovered
{
  "event": "cart.recovered",
  "recovery_id": "rec_7832a8901fbc",
  "phone": "+393401234567",
  "order_id": "10499",
  "recovered_revenue": 89.90,
  "currency": "EUR",
  "recovered_at": "2026-03-30T11:02:14Z",
  "time_to_convert_minutes": 17
}

⚡ WhatsApp OTP Gateway

Il WhatsApp OTP Gateway di BeraLabs offre un'infrastruttura ad alte prestazioni basata su cluster Baileys e WhatsApp Cloud API per l'invio e la validazione di codici monouso (One-Time Password) per autenticazione a due fattori (2FA), verifica contrassegno e login passwordless.

POST https://beralabs.it/api/send-otp
Parametro Tipo Obbligatorio Descrizione
phone String Sì Numero di telefono destinatario in formato internazionale E.164 (es. +393401234567).
shop_name String Sì Nome dell'e-commerce o brand che compare nell'intestazione del messaggio.
otp_length Integer No Lunghezza del codice numerico: 4 o 6 cifre (default: 6).
ttl_seconds Integer No Durata di validità del token prima della scadenza (default: 300, pari a 5 minuti).
purpose String No Scopo dell'operazione: cod_verification, login_2fa, checkout_auth.
Response 200 OK
{
  "success": true,
  "session_id": "otp_sess_a819c9e830f",
  "status": "delivered",
  "channel": "whatsapp",
  "expires_at": 1731683100,
  "retry_after_seconds": 60
}

Verifica del Codice OTP

Per convalidare il codice digitato dall'utente, invia la richiesta all'endpoint di verifica allegando l'identificativo di sessione ricevuto in precedenza:

POST https://beralabs.it/api/verify-otp
Parametro Tipo Obbligatorio Descrizione
session_id String Sì ID della sessione OTP restituito dalla chiamata /send-otp.
code String Sì Il codice numerico inserito dal cliente nel form.
Response 200 OK (Verificato)
{
  "success": true,
  "verified": true,
  "phone": "+393401234567",
  "verified_at": 1731682845
}

💬 WhatsApp Newsletter & Lead Generation

La suite WhatsApp Newsletter consente di acquisire lead qualificati dal sito web tramite widget interattivo flottante e orchestrare campagne promozionali broadcast con tassi di apertura superiori al 95%, nel pieno rispetto delle normative GDPR europee.

POST https://beralabs.it/api/newsletter/subscribe
Parametro Tipo Obbligatorio Descrizione
phone String Sì Numero di telefono in formato E.164 (es. +393401234567).
name String No Nome dell'iscritto per la personalizzazione dei messaggi.
email String No Indirizzo email per la sincronizzazione multicanale CRM.
consent_gdpr Boolean Sì Deve essere tassativamente true (consenso esplicito all'invio di comunicazioni promozionali).
tags Array No Tag di segmentazione tematica (es. ["offerte_lampo", "sneakers"]).
Meccanismo di Double Opt-in WhatsApp

Non appena l'utente compila il widget sul sito, riceve immediatamente un messaggio interattivo su WhatsApp con due pulsanti: "Conferma Iscrizione" e "Annulla". L'iscritto diventa attivo ed idoneo alla ricezione broadcast solo dopo aver premuto il pulsante di conferma.

💻 Codice & SDK Multi-Linguaggio

Tutti gli endpoint BeraLabs possono essere integrati facilmente con qualsiasi linguaggio o framework. Di seguito trovi gli snippet pronti per la produzione con gestione delle eccezioni e validazione degli header:

1. Invio Evento Cart Recovery

curl -X POST https://beralabs.it/api/cart-recovery \
  -H "Content-Type: application/json" \
  -H "X-Bera-API-Key: blk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "phone": "+393401234567",
    "customer_name": "Mario Rossi",
    "cart_token": "ct_9f8e7d6c5b4a",
    "cart_total": 89.90,
    "currency": "EUR",
    "items": [
      {
        "product_id": 412,
        "name": "Scarpe Running Nitro",
        "quantity": 1,
        "price": 89.90
      }
    ],
    "recovery_url": "https://negozio.com/cart?restore=ct_9f8e7d6c5b4a",
    "delay_minutes": 20,
    "discount_code": "TORNA10"
  }'
$response = wp_remote_post('https://beralabs.it/api/cart-recovery', [
    'headers' => [
        'Content-Type'   => 'application/json; charset=utf-8',
        'X-Bera-API-Key' => get_option('beralabs_api_key'),
    ],
    'body'    => wp_json_encode([
        'phone'         => '+393401234567',
        'customer_name' => 'Mario Rossi',
        'cart_token'    => 'ct_9f8e7d6c5b4a',
        'cart_total'    => 89.90,
        'currency'      => 'EUR',
        'items'         => [
            [
                'product_id' => 412,
                'name'       => 'Scarpe Running Nitro',
                'quantity'   => 1,
                'price'      => 89.90
            ]
        ],
        'recovery_url'  => 'https://negozio.com/cart?restore=ct_9f8e7d6c5b4a',
        'delay_minutes' => 20,
        'discount_code' => 'TORNA10'
    ]),
    'timeout' => 15,
]);

if (is_wp_error($response)) {
    error_log('BeraLabs Cart Recovery Error: ' . $response->get_error_message());
} else {
    $body = json_decode(wp_remote_retrieve_body($response), true);
    // Operazione pianificata con successo
}
async function sendCartRecovery(cartData) {
  try {
    const response = await fetch('https://beralabs.it/api/cart-recovery', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Bera-API-Key': process.env.BERALABS_API_KEY
      },
      body: JSON.stringify({
        phone: cartData.phone,
        customer_name: cartData.customerName,
        cart_token: cartData.token,
        cart_total: cartData.total,
        currency: 'EUR',
        items: cartData.items,
        recovery_url: `https://negozio.com/cart?restore=${cartData.token}`,
        delay_minutes: 20,
        discount_code: 'TORNA10'
      })
    });

    const data = await response.json();
    if (!response.ok) {
      throw new Error(data.message || 'Errore nella richiesta di Cart Recovery');
    }
    console.log('Recovery schedulata:', data.recovery_id);
    return data;
  } catch (error) {
    console.error('BeraLabs Recovery Exception:', error);
  }
}
import requests

def send_cart_recovery(api_key: str, cart: dict):
    url = "https://beralabs.it/api/cart-recovery"
    headers = {
        "Content-Type": "application/json",
        "X-Bera-API-Key": api_key
    }
    payload = {
        "phone": cart["phone"],
        "customer_name": cart["customer_name"],
        "cart_token": cart["token"],
        "cart_total": cart["total"],
        "currency": "EUR",
        "items": cart["items"],
        "recovery_url": f"https://negozio.com/cart?restore={cart['token']}",
        "delay_minutes": 20,
        "discount_code": "TORNA10"
    }
    
    response = requests.post(url, json=payload, headers=headers, timeout=10)
    response.raise_for_status()
    return response.json()

2. SDK Flusso OTP Completo (Invio e Validazione)

Esempio in Node.js / JavaScript per orchestrare il ciclo di invio OTP e successiva verifica token:

Node.js / Express Implementation
// 1. Invio Richiesta OTP
async function requestOtp(phoneNumber, brandName) {
  const res = await fetch('https://beralabs.it/api/send-otp', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Bera-API-Key': process.env.BERALABS_API_KEY
    },
    body: JSON.stringify({
      phone: phoneNumber,
      shop_name: brandName,
      otp_length: 6,
      ttl_seconds: 300,
      purpose: 'cod_verification'
    })
  });
  return await res.json(); // restituisce { success: true, session_id: '...' }
}

// 2. Verifica del Codice Inserito
async function verifyOtp(sessionId, userCode) {
  const res = await fetch('https://beralabs.it/api/verify-otp', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Bera-API-Key': process.env.BERALABS_API_KEY
    },
    body: JSON.stringify({
      session_id: sessionId,
      code: userCode
    })
  });
  return await res.json(); // restituisce { success: true, verified: true }
}

3. Validazione Firma HMAC Webhook

Assicurati di verificare sempre la firma dei webhook in ingresso per garantire l'autenticità dei dati ricevuti dai server BeraLabs (vedi codice completo nella sezione Sicurezza & Firme HMAC).

🛡️ Error Handling & Status Code HTTP

Le API di BeraLabs adottano i codici di stato convenzionali del protocollo HTTP per indicare il successo o il fallimento di ogni operazione. Tutti i codici di errore (4xx e 5xx) restituiscono un corpo JSON standardizzato con un codice macchina ed una spiegazione leggibile:

Standard Error JSON Payload
{
  "success": false,
  "error_code": "INVALID_PHONE_FORMAT",
  "message": "Il numero di telefono specificato non rispetta lo standard internazionale E.164 (es. +393401234567).",
  "field": "phone",
  "docs_url": "https://beralabs.it/docs#http-status-codes"
}
Status HTTP Codice Errore Descrizione & Significato Azione Consigliata
200 OK - Richiesta eseguita ed elaborata con successo. Elabora i dati nella risposta.
201 Created - Risorsa (es. sessione OTP o carrello) creata con successo. Salva l'ID sessione/risorsa restituito.
400 Bad Request MISSING_REQUIRED_FIELD Manca uno o più campi obbligatori nel payload JSON. Controlla i dati inviati e il Content-Type.
401 Unauthorized INVALID_API_KEY L'API Key è assente, scaduta o non valida per l'ambiente. Verifica l'header X-Bera-API-Key.
403 Forbidden INSUFFICIENT_PERMISSIONS La chiave non ha accesso al microservizio o firma HMAC non valida. Verifica il piano sottoscritto o il Webhook Secret.
404 Not Found SESSION_EXPIRED_OR_NOT_FOUND La sessione OTP o il token carrello non esiste o è scaduto. Richiedi un nuovo token OTP al cliente.
422 Unprocessable PHONE_NOT_ON_WHATSAPP Il numero di telefono indicato non possiede un account WhatsApp attivo. Attiva il fallback automatico via SMS.
429 Too Many Req RATE_LIMIT_EXCEEDED Superato il limite di richieste consentite per minuto. Attendi i secondi indicati nell'header Retry-After.
500 Server Error INTERNAL_GATEWAY_ERROR Errore imprevisto nei server di elaborazione. Riprova con backoff esponenziale o contatta il supporto.

Guida Rapida di Troubleshooting

Risoluzione Problemi Frequenti

1. Il messaggio OTP non viene recapitato su WhatsApp: Assicurati che il numero sia preceduto dal prefisso internazionale (es. +39 per l'Italia) senza spazi, trattini o parentesi. Verifica che il telefono non sia in modalità non disturbare.
2. Errore "Invalid HMAC Signature": Controlla che stai validando il payload grezzo (raw body) prima che venga parsato o formattato dal framework (non fare json_encode($parsed) perché l'ordine delle chiavi o la spaziatura potrebbero differire).
3. Errore CORS al checkout: Se invii le richieste direttamente dal browser frontend invece che dal server WordPress, assicurati di aver abilitato il tuo dominio nelle impostazioni API di BeraLabs.
4. Risposta 429 persistente: Implementa una coda con backoff esponenziale ed un jitter casuale tra 1 e 3 secondi.