Aggiungere la scansione dei codici a barre alla tua app

Perché la scansione dei codici a barre?

La scansione dei codici a barre è la funzione chiave delle app di nutrizione. L’utente inquadra un prodotto con il telefono e vede subito calorie, macro e ingredienti. Con 6,1 milioni di prodotti nel nostro database — di cui 4,1 milioni con codice a barre provenienti da Open Food Facts — la tua app può riconoscere la maggior parte dei prodotti sugli scaffali di tutto il mondo.

Come funzionano i codici a barre

La maggior parte dei prodotti alimentari usa uno di questi due formati di codice a barre:

• EAN-13 (13 cifre) — usato in tutto il mondo, soprattutto in Europa, Asia e Australia
• UPC-A (12 cifre) — usato principalmente in Nord America

La nostra API accetta entrambi i formati. Basta passare il codice numerico all’endpoint dei codici a barre:

curl "https://foodbase.dev/v1/foods/barcode/5449000000996" \
  -H "X-API-Key: food_your_key_here"

Scegliere una libreria di scansione

App web (con la fotocamera)

Per le app web, ZXing o QuaggaJS possono leggere i codici a barre da un flusso video:

// Using html5-qrcode (lightweight, well-maintained)
import { Html5QrcodeScanner } from "html5-qrcode";

const scanner = new Html5QrcodeScanner("reader", {
  fps: 10,
  qrbox: { width: 250, height: 250 },
});

scanner.render(async (barcode) => {
  scanner.clear();
  const product = await lookupBarcode(barcode);
  if (product) {
    displayProduct(product);
  } else {
    showNotFound(barcode);
  }
});

React Native / mobile

Per React Native, usa react-native-camera o expo-barcode-scanner:

import { BarCodeScanner } from "expo-barcode-scanner";

function Scanner() {
  const handleScan = async ({ data }) => {
    const product = await lookupBarcode(data);
    // Navigate to product detail screen
  };

  return <BarCodeScanner onBarCodeScanned={handleScan} />;
}

iOS/Android nativo

• iOS: usa AVCaptureMetadataOutput di AVFoundation per il rilevamento dei codici a barre integrato
• Android: usa l’API Barcode Scanning di Google ML Kit

La funzione di ricerca

Ecco l’integrazione con l’API che funziona con qualsiasi scanner:

const API_KEY = "food_your_key_here";

async function lookupBarcode(barcode) {
  const res = await fetch(
    `https://foodbase.dev/v1/foods/barcode/${barcode}`,
    { headers: { "X-API-Key": API_KEY } }
  );

  if (res.status === 404) return null; // Product not found
  if (!res.ok) throw new Error(`API error: ${res.status}`);

  return res.json();
}

Cosa ottieni

Una ricerca per codice a barre andata a buon fine restituisce il prodotto completo con un riepilogo nutrizionale:

{
  "name_default": "Original Taste",
  "brand": "Coca-Cola",
  "barcode": "5449000000996",
  "nutriscore": "e",
  "nova_group": 4,
  "image_url": "https://images.openfoodfacts.org/...",
  "nutrition_summary": {
    "energy_kcal": 42,
    "proteins_g": 0,
    "carbs_g": 10.6,
    "fat_g": 0,
    "sugars_g": 10.6,
    "fiber_g": null
  },
  "allergens": null,
  "ingredients": [
    {"lang": "en", "text": "carbonated water, sugar, colour..."}
  ]
}

Gestire i prodotti «non trovati»

Alcune scansioni non troveranno corrispondenze — più spesso marchi locali o regionali. Buone pratiche:

1. Mostra un messaggio chiaro — «Prodotto non trovato nel nostro database»
2. Lascia che l’utente cerchi per nome come alternativa
3. Salva in cache locale i prodotti trovati così le scansioni ripetute sono istantanee
4. Consenti l’inserimento manuale per i prodotti che non sono in nessun database

Niente codice a barre? Usa una foto

Due opzioni in più quando la strada del codice a barre si ferma, entrambe alimentate da crediti IA (ogni piano include una dotazione):

• POST /v1/vision/barcode decodifica il codice a barre da una foto — non serve alcuna libreria di scansione. È pura visione artificiale (0 crediti, conteggiata nella tua quota giornaliera) e restituisce direttamente il prodotto corrispondente.
• POST /v1/vision/product riconosce un prodotto dalla foto del fronte della confezione e restituisce corrispondenze del catalogo ordinate per punteggio — la via di salvataggio per codici danneggiati o mancanti.

async function lookupByPhoto(file) {
  const form = new FormData();
  form.append("image", file);
  const res = await fetch("https://foodbase.dev/v1/vision/product", {
    method: "POST",
    headers: { "X-API-Key": API_KEY },
    body: form,
  });
  if (!res.ok) return null;
  const { matches } = await res.json();
  return matches[0]?.product ?? null; // matches are score-ranked
}

Puoi provare entrambi nel browser nel playground foto.

Consigli sulle prestazioni

• Salva le ricerche in cache locale — i dati dei prodotti cambiano raramente, quindi i prodotti trovati possono essere tenuti in cache sul client a lungo
• Applica il debounce ai callback dello scanner — alcune librerie si attivano più volte per lo stesso codice a barre
• Precarica i prodotti più comuni — se conosci le abitudini di acquisto dei tuoi utenti, usa l’endpoint bulk per precaricarli

Note sulla copertura

La copertura dei codici a barre segue quella dei dati di partenza: più solida per i prodotti venduti in Europa e Nord America, più sottile per i marchi regionali altrove — e migliora di continuo man mano che vengono aggiunti nuovi prodotti. Invece di fidarti di una tabella di copertura statica, prova con i prodotti che i tuoi utenti scansionano davvero: incolla un codice a barre nell’esploratore di prodotti e vedi subito se viene riconosciuto.

Inizia con la scansione dei codici a barre — il piano gratuito include le ricerche per codice a barre.