API de consulta de códigos de barras

Qué hace una consulta

Envía GET /v1/foods/barcode/{code} con tu clave en la cabecera X-API-Key. El código va de GTIN-8 a GTIN-14, con un máximo de 20 caracteres. FoodBase prueba primero una coincidencia exacta con el código de barras guardado y después los equivalentes con ceros a la izquierda del mismo número, de modo que un UPC-A de 12 dígitos encuentra el registro guardado como EAN de 13 dígitos.

Para 5449000000996 el registro vuelve con barcode 5449000000996 e id 62ea12b8-b260-c288-5c38-3a4906f5d6dd. Ese id es estable entre reimportaciones, así que guárdalo como clave foránea en lugar de la cadena del código de barras.

Cuando varias filas del catálogo comparten el mismo código de barras, gana la más popular y la elección es determinista: el mismo código devuelve el mismo producto en cada llamada.

• El barcode devuelto es la forma guardada, no necesariamente la forma que enviaste.

Cómo leer el registro

El cuerpo del 200 es el mismo registro completo de alimento que devuelve por id la API de base de datos de alimentos, así que analízalo una vez y reutiliza el parser. Para 5449000000996 eso significa source openfoodfacts, name_default Original Taste con entradas bg y fr en el array name, nutriscore e, nova_group 4 y ecoscore_grade not-applicable. El texto de etiqueta como serving_size_raw (1 can (330 ml)) y quantity (0kg en este registro, un error de un colaborador) se devuelve tal como se tecleó en el envase, así que trátalo como una pista y no como un número.

• categories_tags es la taxonomía legible por máquinas (en:colas); category es la misma ruta como cadena para mostrar, unida con comas.
• allergens y traces son null cuando la fuente no lista ninguno, lo cual no es lo mismo que libre de alérgenos.
• image_url apunta a images.openfoodfacts.org y puede cambiar cuando los colaboradores actualizan el producto.

Localización y nutrición

Añade ?lang=bg (o en, fr, es, de, it) para rellenar category_localized, category_segments_localized y allergens_localized a partir de los diccionarios de traducción. Donde no existe traducción, el campo es null en lugar de un respaldo en inglés, así que mantén category y allergens en tu cadena de respaldo. lang no afecta a name ni a ingredients.

nutrition_summary tiene seis claves: energy_kcal, proteins_g, carbs_g, fat_g, sugars_g, fiber_g. Cualquiera puede ser null, y todo el objeto es null cuando la fuente no registró nutrición. Para la tabla completa por 100 g, más de 40 nutrientes cuando la fuente los tiene, llama a la API de nutrición con el id que acabas de recibir.

Flujo de escáner, caché y fallos

Con un 200, pinta la tarjeta con name_default, brand, image_url y nutrition_summary, y guarda el id. Con un 404 el código no está en el catálogo: recurre a la API de reconocimiento de imágenes de alimentos con una foto del frontal del envase, o ofrece al usuario una búsqueda de texto. No reintentes un 404; no cambiará hasta que se actualice el catálogo.

Las respuestas 200 llevan Cache-Control: public, max-age=300, y los 404 se pueden cachear durante 60 segundos. Respétalos en cualquier caché entre tus usuarios y FoodBase. Cada respuesta también lleva X-RateLimit-Second-Remaining y las cabeceras de cuota diaria; limita tu ritmo con ellas antes de ver un 429.

La cobertura es mejor para productos de venta minorista europeos y estadounidenses, porque el catálogo se construye a partir de Open Food Facts y USDA FoodData Central, con GS1 Bulgaria y Metro Bulgaria por encima. Las líneas de marca blanca y los productos muy recientes son los fallos más habituales.