Documentação
EAN Images API
Imagens e dados (nome e descrição) de produtos por EAN/GTIN. Consultar se temos um produto é grátis; liberar o conteúdo consome créditos uma única vez por produto.
Início rápido
- Crie sua conta — você ganha créditos de boas-vindas.
- Em Chaves de API, crie uma chave
testpara integrar e umalivepara produção. - Consulte a disponibilidade dos seus EANs (grátis).
- Libere imagem e/ou dados dos produtos que você quiser. Pronto: você recebe os links e o conteúdo.
# 1) O que vocês têm? (grátis)
curl -X POST https://api.eanimages.com.br/v1/availability \
-H "Authorization: Bearer eani_live_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{"eans": ["7896279102544", "7891000100103"]}'
# 2) Liberar o que interessa (consome créditos)
curl -X POST https://api.eanimages.com.br/v1/products/unlock \
-H "Authorization: Bearer eani_live_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{"eans": ["7896279102544"], "include": ["image", "data"]}'Autenticação
Envie sua chave no header Authorization: Bearer <chave> (ou X-API-Key: <chave>). Nunca exponha a chave em código de navegador ou app — chame a API a partir do seu servidor.
eani_live_…
Produção. Libera conteúdo real e consome créditos.
eani_test_…
Integração. A disponibilidade é real, mas a liberação não cobra e devolve imagem e textos de exemplo.
Como os créditos funcionam
- Consultar disponibilidade é grátis (há uma cota diária generosa por conta).
- 1 crédito libera a imagem de um produto; 1 crédito libera nome + descrição.
- Liberou uma vez, é seu: pedir o mesmo produto de novo não cobra — nem com EAN escrito com zero à esquerda.
- Nada indisponível é cobrado. Se o produto só tem imagem, só a imagem é cobrada.
- Tudo ou nada: se a cota do plano + o saldo avulso não cobrem o lote inteiro, nada é cobrado e você recebe o erro
402. - Plano mensal: uma cota de créditos por mês, assinada no painel: pago via PIX, vale um mês e depois você assina de novo (sem renovação automática). A cota é usada primeiro e não acumula. Acabou a cota (ou o plano venceu), novas liberações são recusadas com
402 PLAN_QUOTA_EXCEEDED, masGET /v1/products/{ean}continua devolvendo tudo o que você já liberou. - Créditos avulsos são pacotes pré-pagos via PIX no painel, não vencem e são usados depois da cota do plano.
- Acompanhe a cota em
GET /v1/account(campoplan) ou na resposta de cada liberação (planechargedFrom).
Consultar disponibilidade
GET /v1/availability/{ean}
Um EAN. Funciona até sem chave (limite de 20 por minuto por IP) — útil para testar.
POST /v1/availability
Até 1.000 EANs por chamada. Exige chave. Duplicados e inválidos são separados automaticamente.
POST /v1/availability
{ "eans": ["7896279102544", "7891000100103", "123"] }creditsToUnlockAll já desconta o que sua conta liberou antes — é exatamente quanto custaria liberar tudo.
Liberar imagem e dados
POST /v1/products/unlock
Até 100 EANs por chamada. include aceita "image" e/ou "data" (padrão: os dois). A resposta traz o conteúdo e um link de download temporário.
POST /v1/products/unlock
{ "eans": ["7896279102544"], "include": ["image", "data"] }charged: true indica que aquele recurso foi cobrado nesta chamada. O downloadUrl expira (veja expiresAt) — baixe e guarde o arquivo no seu storage, ou peça um link novo quando precisar.
Baixar de novo (grátis)
GET /v1/products/{ean}
Devolve o conteúdo já liberado com links novos. Recursos não liberados aparecem com unlocked: false.
GET /v1/products/{ean}/image
Redireciona (302) direto para o arquivo da imagem liberada. Útil para scripts e importadores.
curl -L -o 7896279102544.png \
-H "Authorization: Bearer eani_live_SUA_CHAVE" \
https://api.eanimages.com.br/v1/products/7896279102544/imageSaldo e conta
GET /v1/account
Saldo, custo de cada recurso e uso da cota diária de consultas. Bom para alertas de saldo baixo.
GET /v1/pricing
Pacotes de créditos e preços vigentes (público).
Erros
Todo erro segue o mesmo formato. Use o code no seu código e envie o requestId ao suporte.
{
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "Creditos insuficientes: necessario 40, saldo 12",
"details": { "required": 40, "balance": 12 },
"requestId": "c0a8…"
}
}| HTTP | code | Quando |
|---|---|---|
| 400 | VALIDATION_ERROR / INVALID_EAN / NO_VALID_EANS | Corpo inválido ou nenhum EAN válido |
| 401 | UNAUTHORIZED | Chave ausente, inválida ou revogada |
| 402 | INSUFFICIENT_CREDITS | Saldo não cobre o lote. Nada foi cobrado |
| 402 | PLAN_QUOTA_EXCEEDED | Cota do plano do mês esgotada (ou plano vencido) e sem saldo avulso. Nada foi cobrado; o já liberado continua acessível |
| 403 | NOT_UNLOCKED / FORBIDDEN | Imagem não liberada / conta suspensa |
| 404 | PRODUCT_NOT_FOUND | EAN não existe no catálogo |
| 429 | RATE_LIMITED / DAILY_QUOTA_EXCEEDED | Muitas requisições ou cota diária de consultas |
| 5xx | INTERNAL_ERROR | Falha temporária. Tente de novo com backoff |
Limites
- Consulta em lote: 60 requisições/min, até 1.000 EANs cada.
- Liberação: 120 requisições/min, até 100 EANs cada.
- Cota diária gratuita de consultas: 20.000 EANs por conta (fale conosco para ampliar).
- Toda resposta traz
RateLimit-Limit,RateLimit-RemainingeRateLimit-Reset. Em429, respeite o headerRetry-After.
Boas práticas
- Sempre consulte antes de liberar e use
creditsToUnlockAllpara confirmar o custo. - Se você só precisa da foto, envie
"include": ["image"]e economize créditos. - Baixe as imagens para o seu storage logo após liberar — os links expiram.
- Repetir uma liberação é seguro: em caso de timeout, chame de novo sem medo de cobrança dupla.
- Monitore o saldo com
GET /v1/accounte recarregue antes de zerar. - Gere clientes automaticamente a partir do openapi.json (Postman, Insomnia, openapi-generator).