GTIN API

Consulte dados de produtos por GTIN (EAN/UPC/ISBN). Inclui lookup unitário, consultas em batch e busca por filtros.

Ver endpointsQuickstartRate limits
Índice

Introdução

A GTIN API permite consultar informações de produtos por GTIN. O servidor normaliza o GTIN removendo caracteres não numéricos (por exemplo, espaços e traços).

Formatos suportados

GTIN-8, GTIN-12, GTIN-13 e GTIN-14 (inclui EAN/UPC/ISBN quando aplicável).

Autenticação

Todos os endpoints desta página exigem uma API key válida. Você pode enviar a chave em um destes cabeçalhos:

Authorization

Formato Bearer

Authorization: Bearer SUA_CHAVE_API
X-API-Key

Cabeçalho direto

X-API-Key: SUA_CHAVE_API

Dica: para aplicações servidor-servidor, prefira X-API-Key. Para ferramentas e proxies que já usam Authorization, use Bearer.

Quickstart

Use o exemplo abaixo para fazer a primeira consulta.

Base URLhttps://api.pesquisagtin.com.br
cURL (lookup unitário)
curl -X GET "https://api.pesquisagtin.com.br/v1/gtins/7891234567890" \
  -H "X-API-Key: SUA_CHAVE_API"

Endpoints

A seguir estão os endpoints suportados nesta API.

GET/v1/gtins/{gtin}
Consultar produto por GTIN
Lookup (req/min)

Retorna os dados de um produto a partir do seu GTIN. Caracteres não numéricos no parâmetro são ignorados.

Parâmetros
  • gtin — GTIN do produto (8, 12, 13 ou 14 dígitos).
curl -X GET "https://api.pesquisagtin.com.br/v1/gtins/7891234567890" \
  -H "Authorization: Bearer SUA_CHAVE_API"
Códigos de resposta
  • 200Produto encontrado
  • 400GTIN inválido ou parâmetros inválidos
  • 401API key ausente ou inválida
  • 403Plano sem acesso à API
  • 404Produto não encontrado
  • 429Rate limit ou quota mensal excedida
POST/v1/gtins/batch
Consultar produtos em lote (POST)
Lookup (req/min)

Consulta múltiplos GTINs em uma única requisição. O limite de itens por batch depende do seu plano, com hard limit de 100 GTINs por requisição.

curl -X POST "https://api.pesquisagtin.com.br/v1/gtins/batch" \
  -H "X-API-Key: SUA_CHAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "gtins": ["7891234567890", "0012345678905"]
  }'
Códigos de resposta
  • 200Consulta em lote concluída
  • 400Requisição inválida (ex.: acima do limite do plano)
  • 401API key ausente ou inválida
  • 403Plano sem acesso a batch
  • 429Rate limit ou quota mensal excedida
GET/v1/gtins/batch?gtin=...
Consultar produtos em lote (GET)
Lookup (req/min)

Versão cacheável do batch via query string. Use o parâmetro repetido `gtin` (ex.: `?gtin=...&gtin=...`). Esta rota limita o batch em 10 GTINs por requisição e responde com headers de cache (`Cache-Control: private, max-age=3600` e `Vary: X-API-Key`).

curl -X GET "https://api.pesquisagtin.com.br/v1/gtins/batch?gtin=7891234567890&gtin=0012345678905" \
  -H "X-API-Key: SUA_CHAVE_API"
Códigos de resposta
  • 200Consulta em lote concluída
  • 400Máximo de 10 GTINs no GET /batch
  • 401API key ausente ou inválida
  • 403Plano sem acesso a batch
  • 429Rate limit ou quota mensal excedida
GET/v1/gtins/search
Buscar produtos por filtros
Search (cooldown)

Busca produtos por brand, product_name e/ou ncm. Exige pelo menos um filtro. Paginação via offset com limite fixo de 10 itens.

Parâmetros
  • brand — Marca (contém, case-insensitive).
  • product_name — Nome do produto (contém, case-insensitive).
  • ncm — Código NCM (match exato).
  • offset — Offset para paginação (recomendado múltiplos de 10).
curl -X GET "https://api.pesquisagtin.com.br/v1/gtins/search?brand=acme&offset=0" \
  -H "X-API-Key: SUA_CHAVE_API"
Códigos de resposta
  • 200Resultados paginados
  • 400Nenhum filtro informado ou parâmetros inválidos
  • 401API key ausente ou inválida
  • 403Plano sem acesso à API
  • 429Cooldown/rate limit ou quota mensal excedida

Rate limits e quotas

Existem dois tipos de proteção: rate limit (picos) e quota mensal (volume). Além disso, endpoints de batch têm limite de itens por requisição.

Lookup (/v1/gtins/{gtin} e /v1/gtins/batch): requisições por minuto
PlanoLimite
starter60 req/min
pro90 req/min
advanced120 req/min
Batch: limite de GTINs por requisição

O batch tem um limite por plano e um hard limit de 100 itens. No GET /v1/gtins/batch o limite é 10.

PlanoMáx. GTINs no POST /batch
starter2
pro5
advanced10
Search (/search): cooldown por organização
PlanoCooldown
starter1 pesquisa a cada 6s
pro1 pesquisa a cada 4s
advanced1 pesquisa a cada 2s
Quota mensal (por organização)

Cada chamada aos endpoints autenticados consome 1 unidade da quota mensal. Consultas em batch também contam como 1 chamada (independente do número de itens). Ao exceder, a API retorna 429.

PlanoLimite mensal
starter5.000
pro10.000
advanced20.000
HTTP 429 (headers)

Quando o rate limit é excedido, a resposta inclui headers para orientar o retry.

HTTP/1.1 429 Too Many Requests
Retry-After: 5
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Content-Type: application/json

{
  "detail": "Limite de 60 requisições/minuto excedido para seu plano (starter). Aguarde 5s."
}

Erros

Em geral, erros seguem o padrão do FastAPI com a chave detail.

Exemplo de erro
{
  "detail": "Produto com GTIN '7891234567890' não encontrado"
}

Exemplos

Snippets prontos para copiar e colar.

Escolha a linguagem
Exemplos minimalistas para consultar um GTIN.
const res = await fetch("https://api.pesquisagtin.com.br/v1/gtins/7891234567890", {
  headers: {
    "X-API-Key": "SUA_CHAVE_API",
  },
});

if (!res.ok) throw new Error(await res.text());
const data = await res.json();
console.log(data);