O que é um GTIN válido
GTIN é o número do código de barras que identifica um produto no mundo todo (EAN, UPC). A API consulta produtos por ele e recusa códigos que não seguem a regra da GS1. Aqui está a regra, o porquê de cada recusa e como corrigir a integração.
Formatos · Dígito verificador · Códigos que não são de produto · Erros comuns · Como a API responde
Verifique um código
Mesma regra da API. Nada é consultado nem gravado: só a conta é feita.
Formatos aceitos
Somente dígitos (sem espaços, pontos ou traços), com um destes tamanhos, e não todo zero:
| Tamanho | Nome | Onde aparece | Exemplo |
|---|---|---|---|
| 8 dígitos | GTIN-8 (EAN-8) | Embalagens pequenas | 96385074 |
| 12 dígitos | GTIN-12 (UPC-A) | Produtos dos EUA e Canadá | 036000291452 |
| 13 dígitos | GTIN-13 (EAN-13) | O mais comum no Brasil (começa com 789 ou 790) | 7891000100103 |
| 14 dígitos | GTIN-14 (DUN-14) | Caixas e embalagens de transporte | 17891000100100 |
Zeros à esquerda fazem parte do código: 0036000291452 (13 dígitos) e 036000291452 (12) são o mesmo produto.
Guarde e envie o GTIN como texto; num campo numérico os zeros se perdem.
Dígito verificador
O último dígito confere os anteriores e pega a maioria dos erros de leitura e digitação. A conta é a mesma em qualquer país: da direita para a esquerda, sem contar o último dígito, multiplique os dígitos alternadamente por 3 e por 1 e some tudo. O dígito verificador é o que falta para a soma chegar à próxima dezena (se já for dezena, é 0).
Exemplo: 7891000100103
| Dígito | 7 | 8 | 9 | 1 | 0 | 0 | 0 | 1 | 0 | 0 | 1 | 0 | DV |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Peso | ×1 | ×3 | ×1 | ×3 | ×1 | ×3 | ×1 | ×3 | ×1 | ×3 | ×1 | ×3 | — |
| Resultado | 7 | 24 | 9 | 3 | 0 | 0 | 0 | 3 | 0 | 0 | 1 | 0 | 3 |
Soma: 47. Para chegar à próxima dezena (50) faltam 3, então o dígito verificador correto é 3. O código termina em 3: confere.
Códigos que não são de produto
Alguns códigos passam na conta do dígito verificador, mas a GS1 reserva a faixa deles para outros usos: não identificam um produto global. A API não pesquisa esses códigos e, se não estiverem cadastrados, responde 404 com o motivo.
| Tipo | Prefixo | Por quê | Motivo na API |
|---|---|---|---|
| Circulação restrita | 020 a 029, 040 a 049, 200 a 299; GTIN-8 começando com 0 ou 2 | Codigo de circulacao restrita (uso interno de loja ou produto de peso/preco variavel): nao identifica um produto global e nao e pesquisado. | circulacao_restrita |
| Cupons e comprovantes | 050 a 059, 980 a 984, 990 a 999 | Codigo de cupom ou comprovante: nao identifica um produto. | cupom |
| Publicações periódicas (ISSN) | 977 | Codigo de publicacao periodica (ISSN): fora do catalogo de produtos. | issn |
O prefixo é contado nos 13 dígitos do código (no GTIN-14, sem o primeiro dígito; no UPC-A de 12, com um zero à frente).
Exemplo: etiquetas de balança de supermercado começam com 2 (2xx) e mudam a cada pesagem, então não são um produto.
Livros (978 e 979, ISBN) são produtos e são aceitos normalmente.
Os 3 primeiros dígitos indicam o país onde a empresa registrou o código na GS1, não onde o produto foi fabricado:
789 e 790 são do Brasil, mas um produto importado pode ter código brasileiro, e vice-versa.
Erros mais comuns nas integrações
- Código interno no lugar do GTIN: SKU, referência ou código do ERP não são GTIN. Use o número do código de barras da embalagem.
- Zeros perdidos: o GTIN guardado em campo numérico perde os zeros à esquerda e fica com 7, 11 ou 12 dígitos errados.
- Espaços e separadores: espaço no fim, ponto ou traço fazem a API recusar o código.
- Leitura parcial: leitor de código de barras com defeito ou digitação errada geram dígito verificador que não confere.
- Campo vazio preenchido com zeros:
0000000000000passa na conta, mas não é produto. - Etiqueta de balança ou código de uso interno da loja: faixa de circulação restrita, não é produto global.
Valide o GTIN antes de consultar: a conta é simples e evita chamadas recusadas.
Como a API responde
| Situação | Resposta |
|---|---|
| Fora do formato | 400, motivo formato. Não é pesquisado e não gasta a cota do plano. |
| Dígito verificador não confere | 400, motivo digito_verificador. É pesquisado (há cadastros antigos assim) e gasta a cota; se existir, é devolvido. |
| Código que não é de produto, sem cadastro | 404, motivo circulacao_restrita, cupom ou issn. |
| GTIN inválido repetido |
10 GTINs inválidos em 20 minutos suspendem as consultas:
1 h, depois 6 h e depois 24 h (novas ocorrências em 7 dias),
com 429 e a lista dos códigos recusados. Token e gravação continuam funcionando. |
Respostas de GTIN inválido trazem o campo ajuda com o link desta página. Contrato completo na documentação da API.