Searches the canonical catalog first. Portugal is a ranking boost, not a hard filter. Set region=PT when only Portuguese records are acceptable.

GET /v1/search?q=queijo+cottage&region=PT&limit=10

{
  "data": [/* canonical foods, each with searchScore */],
  "externalData": [/* transient OFF food or Wikipedia context */],
  "meta": {
    "localCount": 10,
    "enrichment": {
      "requestedInBackground": true,
      "reason": "catalog_revalidation"
    }
  }
}

Returns up to ten lightweight objects with id, name, brand and barcode. Use for typeahead; use /search only after submission so external providers are not hit per keystroke.

identifier may be a NauTritiva UUID or a barcode. A missing barcode is fetched from Open Food Facts, normalized and cached. Existing stale OFF data is returned immediately and refreshed after the response.

The response contains the complete canonical food, the newest PT price observations, and price-refresh status. Pass country=ALL to include other countries.

Returns up to ten published foods from the same brand first, then the same FoodEx2 level. Every item uses the complete public food contract.

Devolve a projeção de preço atual por artigo e localização quando existe uma correspondência canónica aceite. Durante a transição, produtos apenas nutricionais mantêm o formato legado. Este GET não agenda nem escreve recolhas.

{
  "data": [{
    "source": "open_prices",
    "price": 2.77,
    "currency": "EUR",
    "retailer": "Auchan",
    "storeName": "Auchan ...",
    "countryCode": "PT",
    "city": "Lisboa",
    "observedAt": "2026-06-12",
    "ageDays": 28,
    "sourceUrl": "https://prices.openfoodfacts.org/..."
  }],
  "meta": { "projection": "legacy", "requestedInBackground": false }
}

Como funciona a publicação

Artigos de retalhista, identidade canónica e nutrição permanecem separados. Só uma correspondência revista e aceite pode alimentar a projeção atual. Recolhas são iniciadas manualmente nesta fase e podem ser inspecionadas no painel administrativo.

O adaptador direto reutiliza um transporte HTTPS com allowlist, validação de redirects, robots, timeout e limite de tamanho. A fixture de demonstração não efetua pedidos de rede. A API nunca inventa promoções nem preços.

Histórico limitado por period=30d|90d|1y|all ou por from/to. Pode filtrar por retailer e location e agregar por day, week ou month. Valores monetários agregados são strings decimais.

Submit a shelf observation as source=user_report. It is shown with confidence=low, the API key is retained as provenance, and retries from the same key/store/day update instead of duplicating.

{
  "price": 2.49,
  "currency": "EUR",
  "retailer": "Mercadona",
  "storeName": "Mercadona Braga Centro",
  "city": "Braga",
  "observedAt": "2026-07-10",
  "photoUrl": "https://example.com/shelf-photo.jpg"
}

Send canonical food UUIDs and consumed grams. Each nutrient is scaled from its per-100g value.

{
  "items": [
    { "foodId": "uuid-of-chicken", "grams": 180 },
    { "foodId": "uuid-of-rice", "grams": 120 }
  ]
}

The response includes totals and incompleteFields. If one item has no iodine value, iodine is not silently counted as zero.

{
  "name": "Arroz de frango",
  "description": "Family recipe",
  "servings": 4,
  "instructions": "Cook and combine.",
  "ingredients": [
    { "foodId": "uuid", "grams": 500, "notes": "cooked" }
  ]
}

GET /v1/recipes?q=... searches recipes owned by the API key. GET /v1/recipes/{id} calculates total and per-serving nutrition. Only the owning key may delete it.

Lists distinct FoodEx2 L1/L2/L3 paths present in the catalog. Use them for filters, category browsing, analytics and interoperable EU classification.

Propose a shopper-scanned product. The record remains pending until an admin approves it.

{ "name": "Iogurte natural", "brand": "Marca", "barcode": "5601234567890", "category": "Dairy", "imageUrl": "https://example.com/label.jpg", "nutrition": { "energyKcal": 62, "proteinG": 3.8 } }

Propose an HTTPS image for an existing product through the same review queue.

{ "imageUrl": "https://example.com/front.jpg" }

Poll the pending, approved, or rejected status. A key can only see its own submissions. Use GET /v1/submissions for a cursor-paginated list.

Queues one HTTPS product URL for human review. Free keys may submit up to five per rolling 24 hours; paid keys use their normal plan limits. Include productIdentifier to connect an approved retailer URL to an existing product and its price-refresh workflow.

{ "url": "https://brand.example/product", "productIdentifier": "5601234567890" }