DEV Community: Alessandro Binda

OCR Intelligente per Documenti Aziendali: Architettura e Lezioni dal Campo

Alessandro Binda — Sat, 16 May 2026 22:24:31 +0000

L'OCR (Optical Character Recognition) per testo stampato moderno è un problema risolto da decenni. Tesseract gestisce i documenti dattiloscritti chiari in modo affidabile. Le sfide interessanti stanno nei casi difficili: documenti manoscritti, archivi storici degradati, layout complessi multi-colonna, tabelle nei PDF scansionati, e documenti che mescolano testo stampato e manoscritto.

Questo post documenta l'architettura che usiamo in produzione per il processing di documenti aziendali nel contesto italiano, le scelte che abbiamo fatto, e cosa abbiamo imparato sul campo.

Il Contesto di Business

Il contesto determina i requisiti tecnici, quindi è utile essere specifici.

Nel contesto legale e notarile italiano, i documenti includono:

Rogiti notarili: spesso dattiloscritti su macchine da scrivere d'epoca, con linguaggio giuridico denso, abbreviazioni, e convenzioni di formato specifiche per periodo e notaio
Atti catastali: moduli scansionati con campi dati strutturati, timbri, e annotazioni manoscritte
Contratti e locazioni: documenti moderni tipicamente scansionati invece che creati digitalmente
Fatture e documenti finanziari: formati variabili tra emittenti e periodi

Il requisito di accuratezza è alto — per documenti legali e finanziari, gli errori di estrazione hanno conseguenze reali. E il volume può essere significativo: una compravendita immobiliare genera decine di documenti.

La Catena di Processing a Tre Livelli

Dopo molte iterazioni, siamo arrivati a un approccio a tre livelli basato sulla classificazione del tipo di documento:

Livello 1: Documenti Moderni Stampati → Tesseract

Per documenti stampati moderni (fatture, contratti generati negli ultimi 20 anni, moduli), Tesseract 5.x con preprocessing appropriato è adeguato. Il preprocessing è fondamentale:

import cv2
import pytesseract
import numpy as np

def preprocess_document(image_path):
    img = cv2.imread(image_path)
    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)

    # Correzione inclinazione
    coords = np.column_stack(np.where(gray > 0))
    angle = cv2.minAreaRect(coords)[-1]
    if angle < -45:
        angle = -(90 + angle)
    else:
        angle = -angle

    (h, w) = gray.shape[:2]
    M = cv2.getRotationMatrix2D((w//2, h//2), angle, 1.0)
    gray = cv2.warpAffine(gray, M, (w, h), flags=cv2.INTER_CUBIC)

    # Denoising e threshold
    gray = cv2.GaussianBlur(gray, (3,3), 0)
    _, thresh = cv2.threshold(gray, 0, 255,
                              cv2.THRESH_BINARY + cv2.THRESH_OTSU)
    return thresh

Correzione inclinazione, denoising e thresholding portano l'accuratezza di Tesseract dall'80-85% al 92-96% su documenti aziendali tipici.

Livello 2: Manoscritti e Documenti Degradati → Mistral Pixtral

Per testo manoscritto e documenti storici degradati, Tesseract fallisce significativamente. Il riconoscimento di caratteri corsivi richiede un modello di visione che comprende i pattern contestuali delle lettere, non il matching pixel per pixel.

Usiamo Mistral Pixtral (modello vision-capable) per questo livello. Il prompt è strutturato con cura:

const prompt = `
Estrai tutto il testo da questa immagine di documento.
- Preserva la struttura e la formattazione originale
- Marca le letture incerte con [?]
- Per i numeri, presta attenzione speciale a: 1/7, 0/6, 5/3 (confusioni comuni)
- Output come JSON strutturato con: full_text, tables (se presenti), key_values (campi modulo rilevati)
- Lingua: documento giuridico italiano (può contenere frasi in latino)
`;

const response = await mistral.chat.complete({
  model: "pixtral-12b-2409",
  messages: [{
    role: "user",
    content: [
      { type: "image_url", imageUrl: { url: base64Image } },
      { type: "text", text: prompt }
    ]
  }]
});

Pixtral gestisce la scrittura italiana con accuratezza nell'85-90% sui nostri test — significativamente meglio di qualsiasi approccio OCR tradizionale.

Livello 3: Fallback → Gemini Vision

Per documenti che non superano i controlli di qualità dopo il processing Pixtral, usiamo Gemini Vision come opzione di emergenza. Raramente utilizzato, ma assicura che nessun documento sia completamente non processabile.

La Logica di Routing

async function processDocument(imagePath, documentType) {
  // Routing per tipo documento
  if (documentType === 'modern_typed') {
    const result = await runTesseract(imagePath);
    if (result.confidence > 0.90) return result;
    // Fallthrough al modello vision se qualità bassa
  }

  // Percorso vision model (manoscritti o typed con bassa confidenza)
  const pixtralResult = await runPixtral(imagePath);
  if (pixtralResult.confidence > 0.75) return pixtralResult;

  // Fallback di emergenza
  console.warn('Confidenza bassa — escalating a Gemini');
  return await runGemini(imagePath);
}

Estrazione Strutturata vs. Testo Grezzo

L'estrazione del testo grezzo non è l'obiettivo finale per i documenti aziendali — è l'estrazione di dati strutturati. Dopo l'OCR, eseguiamo un secondo passaggio LLM specificamente per l'estrazione dei campi:

Per una fattura: estrarre numero_fattura, data, nome_fornitore, p_iva_fornitore, righe[], totale, valuta.
Per un rogito: estrarre riferimento_catastale, parti[], notaio, data, tipo_atto, corrispettivo.

Questo approccio a due fasi (OCR → testo grezzo, poi LLM → dati strutturati) è più affidabile che tentare l'estrazione strutturata direttamente dall'immagine in un solo passaggio.

Considerazioni per la Produzione

Gestione della coda: Le chiamate ai modelli vision hanno latenza e costo significativi. Usiamo una coda con priorità e limiti di concorrenza configurabili — nel nostro deployment, massimo 3 job OCR in parallelo per evitare di saturare le API e incorrere in rate limit.

Gestione costi: Pixtral sul free tier di Mistral copre un numero limitato di pagine al giorno. Monitora attentamente l'utilizzo e implementa caching per i documenti già processati.

Monitoring dell'accuratezza: Costruisci un feedback loop. Quando un operatore corregge un risultato di estrazione, cattura quella correzione. Nel tempo, accumuli un dataset per il fine-tuning o il miglioramento dei prompt.

Formato output: Esporta i documenti processati come PDF (per revisione umana) e JSON strutturato (per automazione downstream). La piattaforma S.C.A.L.A. gestisce entrambi i formati nel modulo OCR, con interfaccia di download per i documenti processati.

Cosa Faremmo Diversamente

La cosa su cui abbiamo investito meno nelle fasi iniziali è stato il classificatore di documenti — l'instradamento corretto verso il livello di processing appropriato prima di tentare l'OCR. Una fattura moderna processata attraverso la pipeline del modello vision è più lenta e costosa del necessario. Un rogito manoscritto spinto attraverso Tesseract produce risultati inutilizzabili.

Investi nel classificatore presto. Anche un classificatore semplice addestrato su qualche centinaio di esempi etichettati fa risparmiare costi significativi e migliora l'accuratezza complessiva del sistema.

Il modulo OCR AI per documenti aziendali è parte della piattaforma S.C.A.L.A. Dettagli su get-scala.com.

API Dati Aziendali: Guida Tecnica per Sviluppatori che Lavorano con il Registro Imprese Italiano

Alessandro Binda — Sat, 16 May 2026 22:19:00 +0000

Se hai mai tentato di accedere programmaticamente ai dati del Registro Imprese italiano, sai già che l'esperienza è... migliorabile. Questa guida documenta il landscape reale delle API disponibili, i workaround che funzionano in produzione, e come strutturare un'integrazione robusta.

Il Panorama delle Fonti Dati Ufficiali

Infocamere / Telemaco

È il sistema ufficiale di accesso ai dati delle Camere di Commercio italiane. Tecnicamente capace, ma costruito pensando a notai, avvocati e commercialisti — non agli sviluppatori.

Cosa offre:

Visure camerali complete (dati anagrafici, soci, amministratori, capitale)
Bilanci in formato XBRL
Atti depositati
Procedure concorsuali

Accesso:

Prevede registrazione professionale o rivenditori accreditati
Pricing per query (non per piano mensile)
Documentazione tecnica disponibile ma datata
Non esiste un ambiente sandbox

Per uno sviluppatore che vuole prototipare velocemente, questa non è la strada.

OpenAPI del MISE (Ministero delle Imprese)

Il Ministero ha pubblicato alcune API per l'accesso a dati aggregati e statistici, ma non per query individuali su singole aziende.

API di terze parti (aggregatori)

La strada pratica per la maggior parte degli use case è lavorare con un aggregatore che ha già costruito il layer di normalizzazione sopra le fonti ufficiali. L'API S.C.A.L.A. score è una di queste, con un free tier per il prototyping.

Schema della Risposta API

{
  "company_name": "Rossi e Figli Srl",
  "vat_number": "IT08765432109",
  "fiscal_code": "08765432109",
  "status": "active",
  "legal_form": "Srl",
  "ateco_code": "43.21.01",
  "ateco_description": "Installazione di impianti elettrici",
  "registered_address": {
    "street": "Via Roma 42",
    "city": "Milano",
    "province": "MI",
    "region": "Lombardia",
    "zip": "20121"
  },
  "founding_date": "2008-03-15",
  "employees_range": "10-49",
  "revenue": 2340000,
  "last_filing_year": 2023,
  "score": 71,
  "risk_category": "low",
  "financial_summary": {
    "total_assets": 1850000,
    "total_liabilities": 920000,
    "equity": 930000,
    "net_result": 145000
  },
  "data_confidence": 0.87,
  "last_updated": "2026-04-12"
}

Validazione della Partita IVA Prima della Query

Risparmia quota API e gestisci gli errori in modo più chiaro validando il formato della P.IVA prima di chiamare l'API.

function validateItalianVAT(vat) {
  // Normalizza: rimuovi IT prefix se presente, rimuovi spazi
  const normalized = vat.replace(/^IT/i, '').replace(/\s/g, '');

  // Deve essere esattamente 11 cifre
  if (!/^\d{11}$/.test(normalized)) {
    return { valid: false, error: 'Formato non valido: attese 11 cifre numeriche' };
  }

  // Checksum (algoritmo Luhn adattato per P.IVA italiana)
  let sum = 0;
  for (let i = 0; i < 10; i++) {
    const digit = parseInt(normalized[i]);
    if (i % 2 === 0) {
      sum += digit;
    } else {
      const doubled = digit * 2;
      sum += doubled > 9 ? doubled - 9 : doubled;
    }
  }
  const checkDigit = (10 - (sum % 10)) % 10;

  if (checkDigit !== parseInt(normalized[10])) {
    return { valid: false, error: 'Checksum non valido' };
  }

  return { valid: true, normalized: `IT${normalized}` };
}

Pattern di Integrazione per Casi d'Uso Comuni

Autofill del Form di Registrazione

async function autofillFromVAT(vatNumber) {
  const validation = validateItalianVAT(vatNumber);
  if (!validation.valid) {
    return { error: validation.error };
  }

  try {
    const res = await fetch(
      `https://api.get-scala.com/score/company?vat=${validation.normalized}`,
      { headers: { Authorization: `Bearer ${process.env.SCALA_API_KEY}` } }
    );

    if (!res.ok) throw new Error(`API error: ${res.status}`);
    const data = await res.json();

    return {
      companyName: data.company_name,
      address: data.registered_address,
      ateco: data.ateco_code,
      employees: data.employees_range,
      status: data.status
    };
  } catch (err) {
    console.error('Company lookup failed:', err);
    return null; // Graceful degradation — lascia l'utente compilare manualmente
  }
}

Screening di una Lista Fornitori

async function screenSuppliers(suppliers, riskThreshold = 40) {
  const BATCH_SIZE = 10;
  const results = [];

  for (let i = 0; i < suppliers.length; i += BATCH_SIZE) {
    const batch = suppliers.slice(i, i + BATCH_SIZE);

    const batchResults = await Promise.allSettled(
      batch.map(async (supplier) => {
        const res = await fetch(
          `https://api.get-scala.com/score/company?vat=${supplier.vat}`,
          { headers: { Authorization: `Bearer ${process.env.SCALA_API_KEY}` } }
        );
        const data = await res.json();
        return {
          ...supplier,
          score: data.score,
          riskCategory: data.risk_category,
          flagged: data.score < riskThreshold
        };
      })
    );

    results.push(...batchResults
      .filter(r => r.status === 'fulfilled')
      .map(r => r.value)
    );

    // Rispetta i rate limit — pausa tra batch
    if (i + BATCH_SIZE < suppliers.length) {
      await new Promise(resolve => setTimeout(resolve, 200));
    }
  }

  return {
    total: results.length,
    flagged: results.filter(r => r.flagged),
    clean: results.filter(r => !r.flagged)
  };
}

Gestione della Qualità dei Dati

I dati del Registro Imprese hanno alcune caratteristiche specifiche da gestire:

Bilanci non ancora depositati: Le aziende hanno 6-7 mesi dalla chiusura dell'esercizio per depositare il bilancio. last_filing_year: 2022 in un'API call di maggio 2026 non significa necessariamente che l'azienda sia inattiva — potrebbe avere il 2023 in attesa di deposito.

function assessDataFreshness(lastFilingYear) {
  const currentYear = new Date().getFullYear();
  const lag = currentYear - lastFilingYear;

  if (lag <= 1) return 'fresh';
  if (lag === 2) return 'acceptable'; // probabile deposito in corso
  if (lag === 3) return 'stale';      // attenzione
  return 'very_stale';                // segnale negativo significativo
}

Campo revenue nullo: Le microimprese possono depositare bilanci in forma abbreviata senza esporre il fatturato. Un campo revenue: null non è un errore — è un dato mancante per ragioni di legge.

Aziende in liquidazione: status: "in_liquidation" non significa insolvenza immediata, ma richiede attenzione. La liquidazione volontaria è normale alla fine della vita di un'azienda; quella forzata è un segnale negativo.

Caching e Rate Limiting

La maggior parte dei dati aziendali cambia lentamente. Un TTL di 24 ore è appropriato per la maggior parte degli use case:

const cache = new Map();

async function getCachedScore(vatNumber) {
  const cached = cache.get(vatNumber);
  if (cached && Date.now() - cached.timestamp < 24 * 60 * 60 * 1000) {
    return cached.data;
  }

  const data = await fetchFromAPI(vatNumber);
  cache.set(vatNumber, { data, timestamp: Date.now() });
  return data;
}

In produzione, usa Redis con TTL nativo invece di una Map in memoria.

La documentazione completa dell'API S.C.A.L.A. score e il free tier sono disponibili su get-scala.com/score/. Registrazione su get-scala.com.

AI-Powered Document OCR for Business: Moving Beyond Simple Text Extraction

Alessandro Binda — Sat, 16 May 2026 22:13:28 +0000

OCR (Optical Character Recognition) has been a solved problem for simple printed text since the 1990s. Tesseract can handle clean, high-contrast typed documents reliably. The interesting engineering challenges now are in the hard cases: handwritten documents, degraded historical records, complex multi-column layouts, tables within scanned PDFs, and mixed-format documents that combine printed and handwritten text.

This post covers the technical architecture we use in production for business document processing, the tradeoffs we made, and what we learned from real-world deployment.

The Business Context

Before diving into the technical stack, the business context matters because it shapes the technical requirements.

In legal and notarial workflows in Italy, documents include:

Rogiti (notarial deeds): Often handwritten or typed on old typewriters, with dense legal language, abbreviations, and format conventions specific to the period and the notary
Catastali (land registry documents): Scanned forms with structured data fields, stamps, and handwritten annotations
Contracts and leases: Modern typed documents, often scanned rather than digitally created
Invoices and financial documents: Varying formats across different periods and issuers

The accuracy requirement is high — for legal and financial documents, extraction errors can have real consequences. And the volume can be significant — a property transaction generates dozens of documents.

The Three-Tier Processing Chain

We settled on a three-tier approach based on document type classification:

Tier 1: Modern Typed Documents → Tesseract

For clean, modern typed documents (invoices, contracts generated in the last 20 years, forms), Tesseract 5.x with appropriate preprocessing handles the job adequately. Preprocessing matters enormously:

import cv2
import pytesseract
import numpy as np

def preprocess_for_tesseract(image_path):
    img = cv2.imread(image_path)
    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)

    # Deskew
    coords = np.column_stack(np.where(gray > 0))
    angle = cv2.minAreaRect(coords)[-1]
    if angle < -45:
        angle = -(90 + angle)
    else:
        angle = -angle
    (h, w) = gray.shape[:2]
    center = (w // 2, h // 2)
    M = cv2.getRotationMatrix2D(center, angle, 1.0)
    gray = cv2.warpAffine(gray, M, (w, h), flags=cv2.INTER_CUBIC)

    # Denoise and threshold
    gray = cv2.GaussianBlur(gray, (3, 3), 0)
    _, thresh = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)

    return thresh

Deskewing, denoising, and thresholding together take Tesseract accuracy from 80-85% to 92-96% on typical business documents.

Tier 2: Handwritten and Degraded Documents → Mistral Pixtral

For handwritten text and degraded historical documents, Tesseract fails badly. Character recognition on cursive handwriting requires a vision model that understands contextual letter patterns, not pixel-level character matching.

We use Mistral's Pixtral model (vision-capable) for this tier. The prompt is structured carefully:

const prompt = `
Extract all text from this document image.
- Preserve the original formatting and structure
- Mark uncertain readings with [?]
- For numbers, pay special attention to: 1/7, 0/6, 5/3 (common confusions)
- Output as structured JSON with: full_text, tables (if any), key_values (detected form fields)
- Language: Italian legal document (may contain Latin phrases)
`;

const response = await mistral.chat.complete({
  model: "pixtral-12b-2409",
  messages: [{
    role: "user",
    content: [
      { type: "image_url", imageUrl: { url: base64Image } },
      { type: "text", text: prompt }
    ]
  }]
});

Pixtral handles Italian handwriting with accuracy in the 85-90% range on our test set — significantly better than any traditional OCR approach, and good enough for the majority of documents.

Tier 3: Fallback → Gemini Vision

For documents that fail quality checks after Pixtral processing (confidence below threshold, or manual review flagged), we fall back to Gemini Vision as an emergency option. This is rarely used but ensures no document is completely unprocessable.

The Fallback Decision Logic

async function processDocument(imagePath, documentType) {
  // Route by document type
  if (documentType === 'modern_typed') {
    const result = await runTesseract(imagePath);
    if (result.confidence > 0.90) return result;
    // Fall through to vision model if quality is low
  }

  // Vision model path (handwritten or low-confidence typed)
  const pixtralResult = await runPixtral(imagePath);
  if (pixtralResult.confidence > 0.75) return pixtralResult;

  // Emergency fallback
  console.warn('Low confidence — escalating to Gemini');
  return await runGemini(imagePath);
}

Structured Extraction vs. Raw Text

Raw text extraction is not the end goal for business documents — structured data extraction is. After OCR, we run a second LLM pass specifically for field extraction:

For an invoice: extract invoice_number, date, vendor_name, vendor_vat, line_items[], total, currency.
For a land deed: extract property_cadastral_ref, parties[], notary_name, date, transaction_type, consideration_amount.

This two-stage approach (OCR → raw text, then LLM → structured data) is more reliable than trying to do structured extraction directly from the image in one pass. The OCR stage normalizes the text; the extraction stage applies business logic.

Production Deployment Considerations

Queue management: Vision model calls are expensive in latency and cost. We use a priority queue with configurable concurrency limits — in our implementation, maximum 3 concurrent OCR jobs to avoid overwhelming the API and incurring rate limits.

Cost management: Pixtral on Mistral's free tier covers a limited number of pages per day. Monitor usage carefully and implement caching for documents that have already been processed.

Accuracy monitoring: Build a feedback loop. When a human corrects an extraction result, capture that correction. Over time, you accumulate a dataset for fine-tuning or prompt improvement.

Format output: Export processed documents as PDF (for human review) and structured JSON (for downstream automation). The S.C.A.L.A. platform handles both formats in the OCR module, with a download interface for processed documents.

What We Would Do Differently

The main thing we underinvested in early on was the document classification step — correctly routing documents to the right processing tier before attempting OCR. A modern typed invoice processed through the vision model pipeline is slower and more expensive than necessary. A handwritten deed pushed through Tesseract produces garbage.

Invest in the classifier early. Even a simple classifier trained on a few hundred labeled examples will save significant processing cost and improve overall accuracy.

The S.C.A.L.A. platform includes AI-powered document OCR for business documents as part of the core toolset. Details at get-scala.com.

Company Data API: A Developer's Guide to Building with Business Registry Data

Alessandro Binda — Sat, 16 May 2026 22:07:58 +0000

Business registry data is one of the most useful — and most underused — data sources available to developers. If your application needs to verify a company's legal existence, check its financial standing, autofill company information from a VAT number, or perform due diligence at scale, a company data API can save you months of scraping work.

This guide covers what company data APIs actually expose, how to evaluate them, and a practical walkthrough of what you can build.

What Business Registry Data Contains

Depending on the country and data source, business registry records can include:

Legal company name and registered address
VAT number / tax code / company registration number
Legal form (LLC, corporation, sole trader, etc.)
Registered capital
Date of incorporation
Legal representative and board members
Annual financial filings (revenue, assets, liabilities, profit/loss)
SIC/ATECO industry classification codes
Company status (active, dissolved, in liquidation, bankrupt)
Court proceedings and judgments (in some jurisdictions)

Not all jurisdictions expose all of this. The UK (Companies House) and Denmark are unusually open. Italy publishes core data via the Chamber of Commerce (CCIAA) but charges for full financial data. The US has no single national registry — you work with state-level records, which are inconsistent in both format and completeness.

Evaluating a Company Data API

Before integrating, ask these questions:

1. Coverage: What countries are covered? What percentage of active companies in those countries are in the database? A 60% coverage rate sounds impressive until you realize that the 40% missing includes many legitimate businesses.

2. Freshness: How often is the data updated? Annual financial filings can be 12-18 months old by the time they're filed, processed, and indexed. For risk assessment, you want signals that reflect current reality, not last year's situation.

3. Financial depth: Does the API return raw financial figures, or does it normalize them into comparable metrics? Knowing that Company X reported €2.1M in assets is less useful than knowing its debt-to-asset ratio relative to industry benchmarks.

4. Scoring vs. raw data: Some APIs return raw registry data. Others return processed scores. You may want both — the score for quick checks, the raw data for custom analysis.

5. Rate limits and pricing: For bulk lookups (screening a list of suppliers, running nightly checks on your client portfolio), rate limits matter enormously. A limit of 100 requests/hour makes batch processing impractical.

Practical Use Cases

VAT Number Validation and Autofill

The simplest use case: a user types their company VAT number into your registration form, and you autofill their company name, address, and other details. This reduces friction and errors.

async function autofillCompanyData(vatNumber) {
  const response = await fetch(
    `https://api.get-scala.com/score/company?vat=${vatNumber}`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );
  const data = await response.json();

  return {
    name: data.company_name,
    address: data.registered_address,
    city: data.city,
    country: data.country,
    status: data.status,
    score: data.financial_health_score
  };
}

Supplier Screening Pipeline

You have a list of 500 suppliers. You want to flag any that are at financial risk before renewing contracts. Run them through the API in batch, filter by score threshold, and export a report.

async function screenSupplierList(suppliers) {
  const results = await Promise.allSettled(
    suppliers.map(s =>
      fetch(`https://api.get-scala.com/score/company?vat=${s.vatNumber}`)
        .then(r => r.json())
        .then(data => ({ ...s, score: data.score, riskCategory: data.risk_category }))
    )
  );

  return results
    .filter(r => r.status === 'fulfilled')
    .map(r => r.value)
    .sort((a, b) => a.score - b.score); // lowest scores first
}

Real-Time Risk Monitoring

Monitor your active client portfolio on a rolling basis. Set up a nightly job that checks scores and triggers alerts when a client's score drops below a threshold.

// Run nightly via cron
async function monitorClientPortfolio(clients) {
  for (const client of clients) {
    const current = await getScore(client.vatNumber);
    const previous = await db.getLastScore(client.id);

    if (current.score < RISK_THRESHOLD || current.score < previous.score - 10) {
      await sendAlert({
        clientName: client.name,
        previousScore: previous.score,
        currentScore: current.score,
        riskCategory: current.risk_category
      });
    }

    await db.saveScore(client.id, current);
  }
}

The Score API from S.C.A.L.A.

The S.C.A.L.A. company score exposes a REST API covering Italian and European company data. The free tier allows a limited number of lookups per month, suitable for prototyping. Paid tiers (API Starter at €19/month for 500 calls, API Growth at €49/month for 5K calls) cover most production use cases.

The response schema includes:

{
  "company_name": "Acme Srl",
  "vat_number": "IT12345678901",
  "status": "active",
  "score": 74,
  "risk_category": "low",
  "revenue": 2100000,
  "employees_range": "10-49",
  "last_filing_year": 2023,
  "legal_form": "Srl",
  "ateco_code": "62.01",
  "city": "Milano",
  "region": "Lombardia"
}

Handling Data Quality Issues

Registry data is messy. Build defensively:

Always validate VAT number format before hitting the API (saves quota)
Handle null fields gracefully — not all companies file all data
For scoring, treat missing financial data as a signal, not just a gap
Cache results with appropriate TTL (24 hours for most use cases, shorter for high-risk monitoring)
Log API errors separately from data quality issues — they require different handling

Limitations to Be Aware Of

Company data APIs are powerful but not omniscient. What they cannot tell you:

Real-time cash position (filings are historical)
Off-balance-sheet liabilities
Key person risk (what happens if the founder leaves)
Market and competitive position
Qualitative factors that experienced analysts pick up in conversation

Use the score as a first filter, not a final judgment. For large transactions, it surfaces which companies warrant deeper investigation — it does not replace that investigation.

The S.C.A.L.A. Score API documentation and free tier are available at get-scala.com/score/. API keys require registration at get-scala.com.

Building a WhatsApp AI Assistant for Small Business: Architecture and Lessons Learned

Alessandro Binda — Sat, 16 May 2026 22:01:45 +0000

WhatsApp has 2.5 billion monthly active users. In Europe, it is the primary communication channel for most people — not email, not phone calls, not SMS. For small businesses, this creates an enormous opportunity: meet customers where they already are.

But building a reliable WhatsApp AI assistant is significantly harder than it looks. This post documents the architecture we settled on after many iterations, the mistakes we made, and the things that actually work in production.

Why WhatsApp, Not a Chatbot Widget

The answer is simple: nobody installs apps, nobody visits your website's chat widget at midnight, and nobody reads email subject lines anymore. WhatsApp is different. People have it open all day. Messages get read within minutes. Response rates are 5-10x higher than email.

For a small business — a dental clinic, a real estate agency, a consulting firm — this is transformative. Instead of playing phone tag with clients, you have a persistent, asynchronous communication channel that works around the clock.

The Architecture We Use

Our implementation for the S.C.A.L.A. platform uses the following stack:

WhatsApp Cloud API (Meta)
        ↓
Webhook receiver (Fastify / Node.js)
        ↓
Message classifier (intent detection)
        ↓
RAG pipeline (retrieval-augmented generation)
        ↓
LLM (Mistral 7B / Groq / fallback chain)
        ↓
Response formatter
        ↓
WhatsApp Cloud API (send)

Message Classification First

Before hitting the LLM, every incoming message goes through a lightweight classifier. This is not an LLM — it is a fine-tuned intent classifier that runs in milliseconds. Its job is to assign one of ~20 intents: booking_request, price_inquiry, complaint, document_request, general_question, etc.

Why bother? Because 60-70% of messages can be answered with template responses or simple database lookups, without touching the expensive LLM at all. This keeps costs low and latency down.

RAG for Business-Specific Knowledge

The LLM on its own does not know anything about your specific business — your opening hours, your pricing, your team, your policies. RAG (retrieval-augmented generation) solves this by injecting relevant context into the prompt before asking the model to respond.

We store business knowledge in a vector database. When a question comes in, we embed the query, find the top-k most relevant chunks from the knowledge base, and inject them into the prompt. The model then answers based on the actual business data, not its training data.

// Simplified RAG pipeline
async function buildPrompt(query, businessId) {
  const embedding = await embed(query);
  const context = await vectorDB.search(embedding, {
    businessId,
    topK: 5
  });

  return `
    You are a helpful assistant for ${business.name}.
    Context from our knowledge base:
    ${context.map(c => c.text).join('\n\n')}

    Customer question: ${query}

    Answer based only on the context above. If you don't know, say so.
  `;
}

The Fallback Chain

LLMs fail. APIs go down. Rate limits get hit. You need a fallback chain:

Primary: Groq API (fast, generous free tier)
Secondary: Mistral API (reliable, good quality)
Tertiary: Local Ollama instance (your own hardware, always available)
Final fallback: Template response + flag for human review

The fallback chain means the assistant never goes dark. A degraded response is better than no response.

Lessons Learned the Hard Way

Lesson 1: Context Window Management Is Critical

WhatsApp conversations can run for weeks. You cannot stuff the entire conversation history into every prompt — you will hit token limits and costs will spiral. We use a sliding window: the last N messages, plus a summary of earlier context generated every K turns.

Lesson 2: Tone Calibration Takes Time

Italian users (our primary market) are more formal in business contexts than the English-speaking world assumes. We spent weeks calibrating the tone — not too robotic, not too casual, with appropriate courtesy markers that feel natural in Italian business communication.

Lesson 3: Handoff to Humans Must Be Seamless

The AI cannot handle everything. Angry customers, complex complaints, legally sensitive questions — these need a human. The handoff mechanism must be invisible from the customer's perspective: the conversation continues in the same WhatsApp thread, but a human agent takes over.

We use a simple flagging system: high-confidence responses are sent automatically, low-confidence responses are queued for human review before sending, and certain intent categories always require human approval.

Lesson 4: WhatsApp Template Messages Are Restrictive

Meta enforces strict rules on template messages (messages sent outside the 24-hour customer service window). They must be pre-approved, cannot be promotional, and have limited formatting options. This catches many developers off guard. Plan your template library early and get them approved before you need them.

Lesson 5: Message Queue Is Not Optional

Do not send WhatsApp messages synchronously from your webhook handler. Use a queue. Message delivery is not always instant, rate limits apply, and you need retry logic. A proper message queue (BullMQ, Redis-backed) makes this manageable.

What the Assistant Can Handle in Production

Our production deployment handles:

Appointment booking and rescheduling (with calendar integration)
FAQ responses (with RAG over the business knowledge base)
Document requests (sending PDFs, contracts, invoices via WhatsApp)
Lead qualification (collecting contact details and requirements from new inquiries)
Escalation to human agents (with context transfer)

The system is available as part of the S.C.A.L.A. AI OS, where businesses can configure the assistant via a no-code interface — setting the knowledge base, defining custom responses, and reviewing conversation logs.

Performance Numbers

In our production deployments:

~68% of messages handled fully automatically
Average response latency: 2.3 seconds
Escalation rate: ~12% (messages flagged for human review)
Customer satisfaction: consistently higher than phone-only support (based on follow-up surveys)

What We Would Do Differently

If we were starting over, we would invest more time upfront in the knowledge base structure. The quality of RAG responses is almost entirely determined by the quality and organization of your business knowledge base. Garbage in, garbage out — the LLM cannot make up for missing or poorly structured context.

We would also build the human handoff mechanism from day one, not as an afterthought.

The WhatsApp AI assistant (SARA) is part of the S.C.A.L.A. platform. Source architecture details are available in our engineering documentation at get-scala.com.

Building an AI WhatsApp Bot for Business: Lessons from SARA

Alessandro Binda — Sat, 16 May 2026 22:01:17 +0000

We built SARA — a WhatsApp AI assistant that handles customer inquiries, qualifies leads, schedules appointments, and routes tickets 24/7 — and deployed it as part of a larger AI operating system for SMBs. Here is what we learned.

Why WhatsApp, not a website chatbot

Most business chatbots live behind a "Chat" bubble on a website that nobody opens. WhatsApp is where your customers already are. In Italy and across Europe, WhatsApp has a 90%+ open rate for business messages. When a customer sends a message at 11pm, they expect a reply — not an autoresponder email.

SARA lives on WhatsApp. She replies in seconds, speaks the customer's language (we support Italian, English, Spanish, Portuguese), and escalates to a human when the conversation requires judgment.

The tech stack

We built SARA using:

Baileys — a Node.js library for WhatsApp Web automation. No official API keys needed for prototyping; for production we migrated to Meta's official Cloud API.
Ollama + LLaMA 3 — local LLM inference on a Hetzner dedicated server. No per-token costs, full data privacy.
Fastify — our backend API layer. Extremely fast, TypeScript-friendly.
PostgreSQL — all conversations, contacts, and CRM events are stored relationally. No document-store magic — just normalized tables.
PM2 — process manager for the bot daemon.

The bot is one module inside a larger system we call S.C.A.L.A. AI OS, an AI operating system that covers CRM, financial health scoring, 14 vertical solutions, and a full analytics layer.

Conversation architecture

SARA is not a keyword-matching bot. The flow looks like this:

Incoming message hits the Fastify webhook.
We retrieve the contact record from PostgreSQL (or create one).
We inject the contact's CRM history, vertical context (e.g., real estate, wellness, legal), and current conversation thread into the LLM prompt.
LLaMA 3 generates a reply. We enforce JSON-structured output for intents (book_appointment, escalate_to_human, request_quote, etc.).
The reply goes out via WhatsApp. Intent actions trigger CRM updates, calendar entries, or Slack/email alerts to the human team.

This means SARA "knows" the customer. If they asked about pricing two weeks ago, she remembers. If they are a paying client, she treats them differently than a cold lead.

Handling hallucination in production

LLMs hallucinate. In a customer-facing bot, this is unacceptable. Our mitigations:

RAG (Retrieval-Augmented Generation): we maintain a knowledge base of 174 documents (product sheets, FAQs, pricing, legal terms). Before every reply, we do a semantic search and inject the top-3 relevant chunks. This dramatically reduces made-up answers.
Intent guardrails: if the structured output parser fails to extract a valid intent, we fall back to a safe "let me connect you with a human" message.
Escalation threshold: if a conversation scores above a confidence threshold for sensitivity (legal, medical, financial advice), SARA escalates immediately.

Results in production

After 90 days running SARA across client accounts:

Average response time: 4 seconds (vs 6 hours for human email).
Lead qualification rate: 38% of inbound WhatsApp contacts converted to qualified pipeline within 48h.
Human escalation rate: 12% of conversations — meaning 88% are fully resolved by the bot.
Client NPS improved on average by 14 points.

The bigger picture

SARA alone is not the product. She is the interface to a full AI operating system. When a customer books an appointment via WhatsApp, that event flows into the CRM, triggers an invoice draft, updates the pipeline stage, and flags the account for follow-up. Everything is connected.

If you are curious about how the full system works, you can explore S.C.A.L.A. AI OS at get-scala.com — there is a free starter plan that includes SARA, CRM, and one vertical module.

Open questions / things we are still figuring out

Multi-agent handoff: when SARA escalates to a human, the context transfer is still clunky. We want a seamless "warm transfer" UX.
Voice messages: WhatsApp users send a lot of voice notes. Whisper transcription is working in staging, not yet in prod.
Rate limits: Meta's official Cloud API has message limits that bite when you send campaigns. Baileys has no limits but is technically against ToS for commercial use. The tension is real.

What is your experience building WhatsApp bots in production? Happy to discuss in the comments.

SARA is part of S.C.A.L.A. AI OS — an AI operating system for SMBs. Free plan available.