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).
Tutte le chiamate API di produzione transitano su endpoint protetti HTTPS:https://beralabs.it/api
Supporto nativo per API Key individuali con token di test e produzione (blk_live_... / blk_test_...).
Firma crittografica bidirezionale su tutti i payload dei webhook per eliminare ogni rischio di replay attack.
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_payloadusando 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.
WordPress 6.0+, WooCommerce 7.0+, PHP 7.4 - 8.3. Pienamente compatibile con WooCommerce HPOS (High-Performance Order Storage).
Si inietta tramite hook nativi di WooCommerce (woocommerce_review_order_before_submit o modale AJAX).
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. |
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.
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).
Iniezione automatica di grafi JSON-LD Schema.org nidificati e interconnessi: WebSite, Organization, LocalBusiness, FAQPage, Speakable.
Esposizione automatica degli standard web /llms.txt e /llms-full.txt per il consumo machine-readable da parte dei crawler AI.
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.
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)
{
"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)
{
"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"
}
Tecnologia 1-Click Restore Magic Link
La barriera principale nel recupero carrelli tradizionale via email è la perdita della sessione browser. Se il cliente apre l'email sullo smartphone mentre aveva iniziato l'ordine su desktop, trova il carrello vuoto.
Il Magic Link di BeraLabs risolve definitivamente questo problema:
- Il link contiene un token crittografico effimero generato con HMAC SHA-256 e durata di 48 ore.
- Quando l'utente tocca il link nel messaggio WhatsApp sullo smartphone, il plugin ricostruisce istantaneamente gli articoli nel carrello, applica in automatico il coupon sconto e pre-compila tutti i dati di spedizione.
- L'utente deve semplicemente confermare il pagamento in 1 singolo tocco.
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:
{
"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.
| 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. |
{
"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:
| 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. |
{
"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.
| 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"]). |
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:
// 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:
{
"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
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.