Usa os dados do Atlas.

Início rápido

Define o URL base uma vez e depois executa qualquer exemplo abaixo.

ATLAS_API=https://www.elabel-atlas.eu/api/v1

Autenticação

Os pedidos anónimos podem usar todos os endpoints públicos de leitura. Uma chave aumenta o limite de pedidos e é necessária para as operações de escrita dos fornecedores. Proprietários e administradores de espaços de trabalho de fornecedor podem criar uma chave no espaço de trabalho com sessão iniciada, em Chaves API. Se precisares de uma chave de leitura sem espaço de trabalho de fornecedor ou de acesso em massa, escreve para david@essentialcode.eu.

curl --fail --silent --show-error \
  -H "Authorization: Bearer $ATLAS_API_KEY" \
  "$ATLAS_API/public-records?limit=1"

Limites de pedidos

Cada operação pública permite 60 pedidos anónimos por minuto por endereço, ou 600 por minuto por chave de leitura. As respostas incluem os cabeçalhos limit, remaining e reset. Um pedido acima do limite devolve HTTP 429:

HTTP/1.1 429 Too Many Requests
retry-after: 60
x-ratelimit-limit: 60
x-ratelimit-remaining: 0

{"error":{"code":"rate_limited","message":"The public API rate limit was exceeded."}}

Endpoints públicos de leitura

curl --fail --silent --show-error \
  "$ATLAS_API/search?q=Veltliner&limit=1"

{
  "query": "Veltliner",
  "records": [{
    "atlas_record_id": "QXSvIVqvHcRW-LjHtG88I",
    "name": "Grüner Veltliner 2025",
    "provider": { "name": "Demo Wine Cooperative" },
    "gtin": "4006381333931"
  }]
}

curl --fail --silent --show-error \
  "$ATLAS_API/public-records?limit=1"

{
  "records": [{
    "atlas_record_id": "ovPcoHyHMEbzdcGC_Zkm_",
    "name": "Grüner Veltliner Ried Steinberg 2024",
    "provider": { "name": "Glasswise" }
  }],
  "next_cursor": "eyJ1cGRhdGVkQXQiOjE3ODk1MDIxMjQ3MDcsImlkIjoib3ZQY29IeUhNRWJ6ZGNHQ19aa21fIn0"
}

curl --fail --silent --show-error \
  "$ATLAS_API/public-records/4006381333931"

{
  "gtin": "4006381333931",
  "records": [{
    "atlas_record_id": "QXSvIVqvHcRW-LjHtG88I",
    "name": "Grüner Veltliner 2025",
    "provider": { "name": "Demo Wine Cooperative" }
  }]
}

RECORD_ID=$(curl --fail --silent --show-error \
  "$ATLAS_API/public-records?limit=1" | jq -r '.records[0].atlas_record_id')
curl --fail --silent --show-error \
  "$ATLAS_API/public-records/by-id/$RECORD_ID"

{
  "atlas_record_id": "ovPcoHyHMEbzdcGC_Zkm_",
  "name": "Grüner Veltliner Ried Steinberg 2024",
  "provider": { "name": "Glasswise" },
  "atlas_updated_at": "2026-09-15T19:55:24.707Z"
}

Paginação

A lista pública de registos devolve next_cursor quando existe outra página. Envia esse valor opaco exato com os mesmos filtros. Não o descodifiques nem o edites.

CURSOR=$(curl --fail --silent --show-error \
  "$ATLAS_API/public-records?limit=1" | jq -r '.next_cursor')
curl --fail --silent --show-error \
  "$ATLAS_API/public-records?limit=1&cursor=$CURSOR"

Idiomas dos registos públicos

As páginas de registos públicos só localizam as etiquetas do Atlas e os códigos definidos pelo E-Label Standard Format, incluindo tipo de vinho, propriedades do vinho, códigos de país, chaves de nutrição e unidades. Todo o texto escrito pelo fornecedor fica exatamente como foi fornecido, incluindo nomes e categorias de ingredientes e qualquer texto de embalagem ou de eliminação que o fornecedor escreveu.

O primeiro código em languages é sempre o idioma principal do registo, mesmo quando o Atlas não consegue apresentar a sua interface nesse idioma. Uma página oferece o conteúdo principal e os idiomas suportados que têm traduções do fornecedor. Liga a uma seleção com ?lang=de ou ?lang=hr. Sem parâmetro, o Atlas usa Accept-Language quando existe conteúdo correspondente e redireciona para o URL partilhável correspondente.

Prefere ingredients[] estruturados para preservar os indicadores de alergénios e de biológico. Usa ingredients_text apenas quando o fornecedor tem uma declaração completa em prosa. Os fornecedores podem adicionar valores translations.{language} para ingredients_text, designation_of_origin e cada instrução packaging[].disposal. O array packaging segue o comprimento e a ordem da lista principal; usa null para uma instrução que deva recair no valor principal. As traduções em falta recaem no valor principal de topo. REST e MCP devolvem este mapa opcional, e JSON-LD usa valores marcados por idioma. Este mapa fornecido pelo fornecedor é a única forma de o texto do fornecedor mudar entre idiomas.

O corpo do pedido do fornecedor segue o E-Label Standard Format.

Nas páginas públicas, o Atlas apresenta os códigos próprios do Standard (productType, color, sweetness, packagingGas, packagingType, materialType e collection) no idioma da página a partir do vocabulário Standard publicado. Qualquer outro valor do fornecedor fica exatamente como foi fornecido.

MCP

Model Context Protocol, ou MCP, é uma forma normalizada de um cliente de IA chamar ferramentas externas. O e-label Atlas disponibiliza um servidor Streamable HTTP anónimo em https://www.elabel-atlas.eu/mcp.

O servidor expõe search_elabels, lookup_elabel_by_gtin, get_elabel e list_elabels_updated_since.

Instala o Atlas num agente

Escolhe o teu cliente. O plugin do Claude Code e a configuração do Codex incluem tanto a orientação da skill do Atlas como as ferramentas MCP ao vivo. Outros clientes ligam-se ao mesmo servidor MCP só de leitura.

claude plugin marketplace add https://www.elabel-atlas.eu/claude/marketplace.json && \
  claude plugin install elabel-atlas@elabel-atlas

https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=e-label%20Atlas&connectorUrl=https%3A%2F%2Fwww.elabel-atlas.eu%2Fmcp

mkdir -p "$HOME/.agents/skills/elabel-atlas"
curl --fail --location   https://www.elabel-atlas.eu/api/v1/SKILL.md   --output "$HOME/.agents/skills/elabel-atlas/SKILL.md"
codex mcp add elabel-atlas --url https://www.elabel-atlas.eu/mcp

{
  "mcpServers": {
    "elabel-atlas": {
      "url": "https://www.elabel-atlas.eu/mcp"
    }
  }
}

{
  "mcpServers": {
    "elabel-atlas": {
      "httpUrl": "https://www.elabel-atlas.eu/mcp"
    }
  }
}