Cómo añadir lectura de códigos de barras a tu app

¿Por qué leer códigos de barras?

La lectura de códigos de barras es la función estrella de las apps de nutrición. El usuario apunta con el teléfono a un producto y ve al instante las calorías, los macros y los ingredientes. Con 6,1 millones de productos en nuestra base de datos — 4,1 millones de ellos con código de barras procedentes de Open Food Facts — tu app puede reconocer la mayoría de los productos de las estanterías de todo el mundo.

Cómo funcionan los códigos de barras

La mayoría de los productos alimentarios usan uno de estos dos formatos de código de barras:

EAN-13 (13 dígitos) — de uso global, sobre todo en Europa, Asia y Australia
UPC-A (12 dígitos) — usado principalmente en Norteamérica

Nuestra API acepta ambos formatos. Basta con pasar el código numérico al endpoint de códigos de barras:

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

Elegir una librería de escaneo

Apps web (con cámara)

En apps web, ZXing o QuaggaJS pueden leer códigos de barras desde un flujo de vídeo:

// 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 / móvil

En 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 de AVFoundation para la detección de códigos de barras integrada
Android: usa la API Barcode Scanning de Google ML Kit

La función de consulta

Esta es la integración con la API que funciona con cualquier escáner:

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();
}

Qué recibes

Una consulta por código de barras correcta devuelve el producto completo con un resumen nutricional:

{
  "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..."}
  ]
}

Cómo gestionar los productos «no encontrados»

Algunos escaneos no encontrarán coincidencia — casi siempre marcas locales o regionales. Buenas prácticas:

Muestra un mensaje claro — «Producto no encontrado en nuestra base de datos»
Deja que el usuario busque por nombre como alternativa
Guarda en caché local los productos encontrados para que los escaneos repetidos sean instantáneos
Permite la entrada manual para productos que no están en ninguna base de datos

¿Sin código de barras? Usa una foto

Dos opciones más cuando el camino del código de barras llega a un callejón sin salida, ambas con créditos de IA (todos los planes incluyen una asignación):

POST /v1/vision/barcode decodifica el código de barras a partir de una foto — sin necesidad de ninguna librería de escaneo. Es visión por computador pura (0 créditos, se mide con tu cuota diaria) y devuelve directamente el producto encontrado.
POST /v1/vision/product reconoce un producto a partir de la foto de su frontal y devuelve coincidencias del catálogo con puntuación — la vía de rescate para códigos dañados o ausentes.

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
}

Puedes probar ambos en el navegador en el playground de fotos.

Consejos de rendimiento

Guarda las consultas en caché local — los datos de los productos cambian poco, así que los productos encontrados pueden cachearse en el cliente durante mucho tiempo
Aplica debounce a los callbacks del escáner — algunas librerías se disparan varias veces con el mismo código de barras
Precarga los productos habituales — si conoces los hábitos de compra de tus usuarios, usa el endpoint bulk para precargarlos

Notas sobre la cobertura

La cobertura de códigos de barras sigue la de los datos de origen: más sólida para productos vendidos en Europa y Norteamérica, más escasa para marcas regionales en otros lugares — y mejora continuamente a medida que se añaden productos. En lugar de fiarte de una tabla de cobertura estática, prueba con los productos que tus usuarios escanean de verdad: pega un código de barras en el explorador de productos y comprueba al instante si se reconoce.

Empieza con la lectura de códigos de barras — el plan gratuito incluye consultas por código de barras.