Para desenvolvedores
Documentação da API
A mesma base de dados da busca do site, como API JSON gratuita: consulte produtos, NCM e CEST por código de barras ou por nome, direto do seu ERP, PDV, e-commerce ou aplicativo.
- URL base
https://global.si5.com.br/api- Formato
- JSON (UTF-8)
- Autenticação
- Bearer token
- Limite
- Grátis: 30 consultas/dia
Início rápido
Em três passos você faz a primeira consulta:
Crie sua conta
Entre gratuitamente com o Google na sua página de conta.
Gere um token
Na mesma página, crie um token de API. Guarde-o: ele identifica o seu uso.
Faça a chamada
Envie o token no cabeçalho Authorization e consulte um GTIN.
curl "https://global.si5.com.br/api/produtos/7891000325858" \ -H "Authorization: Bearer SEU_TOKEN_AQUI" \ -H "Accept: application/json"
Autenticação
Toda chamada precisa de um token pessoal. É assim que garantimos um limite de uso estável para quem integra de verdade (ERP, PDV, e-commerce). A franquia é diária e vale por plano: 30 consultas por dia no plano Grátis (renova à meia-noite, horário de Brasília), compartilhada entre os seus tokens — suficiente para consulta em tempo real (bipar o código, ver os dados, próximo). Cada plano define também quantos tokens você pode criar; veja os planos e preços. Envie o token em toda requisição:
Authorization: Bearer SEU_TOKEN_AQUI
Use-o no servidor ou no seu ERP, nunca em JavaScript de página pública nem em repositório aberto. Se vazar, revogue e gere outro na sua conta.
Buscar produtos
Pesquisa por código de barras ou por nome e devolve uma lista paginada. Se q tiver só
números, a busca é por prefixo do código de barras; com letras, é uma busca por
palavras no nome (palavras com 3+ letras são obrigatórias e aceitam prefixo — sabonete yp
encontra "Sabonete Ypê").
| Parâmetro | Tipo | Descrição |
|---|---|---|
q | string | Código de barras (prefixo) ou termo de busca no nome. Vazio = lista tudo, paginado. |
per_page | integer | Itens por página. Padrão 20, máximo 100. |
page | integer | Número da página. Padrão 1. |
Exemplo de código
<?php
$query = http_build_query([
'q' => 'sabonete ype',
'per_page' => 5,
]);
$ch = curl_init("https://global.si5.com.br/api/produtos?{$query}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer SEU_TOKEN_AQUI',
'Accept: application/json',
]);
$resposta = curl_exec($ch);
$codigo = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$dados = json_decode($resposta, true);
foreach ($dados['data'] as $produto) {
echo $produto['produto'] . ' - ' . $produto['marca'] . PHP_EOL;
}
uses
IdHTTP, IdSSLOpenSSL, IdURI, System.JSON, System.SysUtils;
function BuscarProdutos(const ATermo: string; APorPagina: Integer = 5): TJSONObject;
var
Http: TIdHTTP;
SSL: TIdSSLIOHandlerSocketOpenSSL;
Url, Resposta: string;
begin
Http := TIdHTTP.Create(nil);
SSL := TIdSSLIOHandlerSocketOpenSSL.Create(nil);
try
Http.IOHandler := SSL;
Http.Request.CustomHeaders.AddValue('Authorization', 'Bearer SEU_TOKEN_AQUI');
Http.Request.Accept := 'application/json';
Url := Format('https://global.si5.com.br/api/produtos?q=%s&per_page=%d',
[TIdURI.ParamsEncode(ATermo), APorPagina]);
Resposta := Http.Get(Url);
Result := TJSONObject.ParseJSONValue(Resposta) as TJSONObject;
finally
Http.Free;
SSL.Free;
end;
end;
// uso:
// var Json: TJSONObject;
// Json := BuscarProdutos('sabonete ype');
// try
// // Json.GetValue<TJSONArray>('data') ...
// finally
// Json.Free;
// end;
curl -G "https://global.si5.com.br/api/produtos" \ -H "Authorization: Bearer SEU_TOKEN_AQUI" \ -H "Accept: application/json" \ --data-urlencode "q=sabonete ype" \ --data-urlencode "per_page=5"
// Node.js 18+ (servidor). Não coloque o token em JavaScript de página pública.
const params = new URLSearchParams({ q: 'sabonete ype', per_page: '5' });
const resp = await fetch(`https://global.si5.com.br/api/produtos?${params}`, {
headers: {
Authorization: 'Bearer SEU_TOKEN_AQUI',
Accept: 'application/json',
},
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const { data, meta } = await resp.json();
data.forEach((p) => console.log(`${p.produto} - ${p.marca}`));
console.log(`página ${meta.current_page} de ${meta.last_page}`);
Exemplo de resposta
{
"data": [
{
"codbar": "7896098900475",
"produto": "Sabonete Em Barra Flor De Ypê Laranjeira E Damasco Ypê 90g",
"marca": "YPÊ",
"categoria": "Higiene E Beleza",
"ncm": "34011190",
"cest_codigo": "2001700",
"peso": "90.00",
"embalagem": null,
"quantidade_embalagem": 1,
"preco_medio": null,
"imagem_url": "https://global.si5.com.br/img/78/96/7896098900475.webp",
"codigo_barras_url": null
}
],
"meta": { "current_page": 1, "last_page": 214, "total": 26 }
}
O objeto meta traz a página atual (current_page), a última
(last_page) e o total de itens (total). Para percorrer tudo, incremente
page até last_page.
Consultar um produto pelo código de barras
Devolve o produto completo: os campos da busca mais descrição oficial de NCM/CEST e, quando
existirem, ingredientes, alérgenos e tabela nutricional. Use o GTIN inteiro, com zeros à esquerda
se houver (ex.: 0000000104500).
Exemplo de código
<?php
$codbar = '7891000100103';
$ch = curl_init("https://global.si5.com.br/api/produtos/{$codbar}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer SEU_TOKEN_AQUI',
'Accept: application/json',
]);
$resposta = curl_exec($ch);
$codigo = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($codigo === 404) {
echo "Produto nao encontrado";
} else {
$produto = json_decode($resposta, true);
echo $produto['produto'] . ' - NCM ' . $produto['ncm'];
}
uses
IdHTTP, IdSSLOpenSSL, IdComponent, System.JSON, System.SysUtils;
function ConsultarProduto(const ACodBar: string): TJSONObject;
var
Http: TIdHTTP;
SSL: TIdSSLIOHandlerSocketOpenSSL;
begin
Result := nil;
Http := TIdHTTP.Create(nil);
SSL := TIdSSLIOHandlerSocketOpenSSL.Create(nil);
try
Http.IOHandler := SSL;
Http.Request.CustomHeaders.AddValue('Authorization', 'Bearer SEU_TOKEN_AQUI');
Http.Request.Accept := 'application/json';
try
Result := TJSONObject.ParseJSONValue(
Http.Get('https://global.si5.com.br/api/produtos/' + ACodBar)
) as TJSONObject;
except
on E: EIdHTTPProtocolException do
if Http.ResponseCode = 404 then
raise Exception.Create('Produto nao encontrado')
else
raise;
end;
finally
Http.Free;
SSL.Free;
end;
end;
curl "https://global.si5.com.br/api/produtos/7891000100103" \ -H "Authorization: Bearer SEU_TOKEN_AQUI" \ -H "Accept: application/json"
// Node.js 18+ (servidor)
const codbar = '7891000100103';
const resp = await fetch(`https://global.si5.com.br/api/produtos/${codbar}`, {
headers: {
Authorization: 'Bearer SEU_TOKEN_AQUI',
Accept: 'application/json',
},
});
if (resp.status === 404) {
console.log('Produto não encontrado');
} else if (resp.ok) {
const produto = await resp.json();
console.log(`${produto.produto} - NCM ${produto.ncm} - CEST ${produto.cest_codigo}`);
}
Exemplo de resposta (produto real do catálogo)
{
"codbar": "7891000325858",
"produto": "LEITE PO NINHO INTEGRAL",
"marca": "Nestlé Ninho",
"categoria": "ALIMENTOS",
"ncm": "04022110",
"cest_codigo": "1701200",
"peso": "380.00",
"embalagem": null,
"quantidade_embalagem": null,
"preco_medio": null,
"imagem_url": "https://global.si5.com.br/img/78/91/7891000325858.webp",
"codigo_barras_url": null,
"ncm_descricao": "Leite integral",
"cest_segmento": "17. Produtos alimentícios",
"ingredientes": "Leite integral, minerais [cálcio, ferro e zinco] e vitaminas [C, E, A e D].",
"alergenos": "milk",
"pode_conter": null,
"porcao": "25g",
"nutrientes": {
"energia_kcal": 496,
"proteinas_g": 25.2,
"carboidratos_g": 37.6,
"acucares_g": 37.6,
"gorduras_g": 26.8,
"gorduras_saturadas_g": 17.6,
"fibras_g": 0,
"sodio_mg": 392
}
}
As respostas por GTIN ficam em cache por até 12 horas e são renovadas automaticamente quando o produto é atualizado no catálogo.
Referência de campos
Presentes tanto na busca quanto na consulta por código de barras:
| Campo | Tipo | Descrição |
|---|---|---|
codbar | string | Código de barras (GTIN/EAN-8, 12, 13 ou 14). Sempre texto — preserva zeros à esquerda. |
produto | string | Nome/descrição comercial do produto. |
marca | string | null | Marca. Pode ser nulo quando não identificada. |
categoria | string | null | Categoria do catálogo (ex.: ALIMENTOS, Higiene E Beleza). |
ncm | string | null | NCM com 8 dígitos, sem pontos (ex.: 04022110). |
cest_codigo | string | null | CEST com 7 dígitos, sem pontos (ex.: 1701200). Nulo quando não se aplica ou é ambíguo. |
peso | string | null | Peso como texto decimal (ex.: "380.00"). |
embalagem | string | null | Tipo de embalagem, quando informado. |
quantidade_embalagem | number | null | Quantidade de unidades na embalagem, quando informado. |
preco_medio | null | Sempre nulo: o catálogo não publica preço. O campo existe só para manter o contrato. |
imagem_url | string | null | URL da foto do produto, em WEBP (veja a seção Imagens). |
codigo_barras_url | null | Campo mantido por compatibilidade: agora é sempre null. |
Campos adicionais na consulta por código de barras
| Campo | Tipo | Descrição |
|---|---|---|
ncm_descricao | string | null | Descrição oficial do NCM, da tabela vigente. |
cest_segmento | string | null | Segmento oficial do CEST. |
ingredientes | string | null | Lista de ingredientes, quando disponível. |
alergenos | string | null | Alérgenos declarados, quando disponível. |
pode_conter | string | null | Alerta de contaminação cruzada, quando disponível. |
porcao | string | null | Porção de referência da tabela nutricional. |
nutrientes | object | null | Tabela nutricional por porção (energia_kcal, proteinas_g, carboidratos_g, acucares_g, gorduras_g, gorduras_saturadas_g, fibras_g, sodio_mg…). As chaves presentes variam por produto. |
Campos sem informação vêm como null — sempre trate a ausência de dado.
Ficha fiscal (planos pagos)
Nos planos pagos, a consulta por código de barras traz também o bloco fiscal: tudo o que o seu ERP precisa para tributar o produto num estado, a partir das tabelas oficiais. Informe o estado no parâmetro
uf (sigla, ex.: RJ); sem ele, vale SP.
curl -H "Authorization: Bearer SEU_TOKEN" "https://global.si5.com.br/index.php/api/produtos/7894900011517?uf=RJ"
Exemplo de resposta (resumido)
{
"codbar": "7894900011517",
"produto": "Refrigerante Coca Cola Garrafa 2l",
"…": "…",
"fiscal": {
"uf": "RJ",
"ncm": {
"codigo": "22021000",
"formatado": "2202.10.00",
"vigente": true,
"descricao": "Águas, incluindo as águas minerais e as águas gaseificadas, adicionadas de açúcar…"
},
"cest": {
"informado": "0300700",
"informado_compativel": true,
"sujeito_st": true,
"informado_na_uf": null
},
"ibpt": {
"uf": "RJ",
"versao": "26.2.B",
"federal_nacional": 14.74,
"estadual": 18,
"municipal": 0,
"total_nacional": 32.74,
"fonte": "IBPT - De Olho no Imposto"
},
"ipi": {
"aliquota": 2.6,
"nao_tributado": false,
"excecoes": [
{
"ex": "1",
"descricao": "Refrescos",
"aliquota": 2.6
}
]
},
"pis_cofins": {
"regime": "Incidência monofásica - alíquota por unidade",
"cst_sugerido": "03",
"regras": [
"…"
]
},
"rtc": {
"cclasstrib": "000001",
"cst": "000",
"descricao": "Situações tributadas integralmente pelo IBS e CBS.",
"reducao": 0,
"seletivo": true
},
"aviso": "Informação de apoio baseada em tabelas oficiais (TIPI, EFD-Contribuições, IBPT, NCM, CEST). Confirme a tributação com seu contador."
}
}
Blocos da ficha fiscal
| Campo | Descrição |
|---|---|
fiscal.ncm | NCM do produto na tabela oficial: código, descrição e se está vigente. |
fiscal.cest | CEST do cadastro, se é compatível com o NCM, CESTs possíveis e se o produto está na substituição tributária (ST) do estado. |
fiscal.ibpt | Carga tributária aproximada (Lei 12.741, "De Olho no Imposto"): percentuais federal (nacional e importado), estadual e municipal da UF, com versão e vigência da tabela. |
fiscal.ipi | Alíquota do IPI na TIPI vigente e as exceções (EX) do NCM. |
fiscal.pis_cofins | Regime de PIS/COFINS (geral, monofásico, alíquota zero...) com CST sugerido e as regras das tabelas da EFD-Contribuições. |
fiscal.rtc | Reforma Tributária: cClassTrib e CST do IBS/CBS, percentual de redução (100 = alíquota zero) e se há Imposto Seletivo. |
No plano Grátis
O bloco vem como null e o campo fiscal_info indica onde contratar:
{
"codbar": "7894900011517",
"…": "…",
"fiscal": null,
"fiscal_info": {
"mensagem": "Ficha fiscal completa (IBPT, IPI, PIS/COFINS, CEST/ST e IBS/CBS por estado) disponível nos planos pagos.",
"planos": "https://global.si5.com.br/index.php/precos/api"
}
}
Use o IBPT para o "valor aproximado dos tributos" do cupom fiscal (Lei 12.741). A ficha é informação de apoio a partir de tabelas oficiais: confirme a tributação com seu contador, principalmente quando o NCM tem exceções (EX).
Imagens
imagem_url (foto do produto) é um link público, sem token, ou null quando o produto não tem foto. Use sempre o link que a API devolve: não monte o endereço a partir do código de barras e consulte a API de novo se precisar do link, porque o formato pode mudar.
A URL sempre aponta para .webp. Decoders antigos — como o
TJPegImage nativo do Delphi — não leem esse formato e costumam falhar em
silêncio: a imagem simplesmente não aparece, sem erro. Se o seu sistema não decodifica WEBP,
passe a URL por um proxy de conversão antes de exibir.
Convertendo para JPG
<?php
// A API devolve .webp. Para clientes que não leem WEBP, converta pelo proxy:
function urlImagemJpg(string $imagemUrl): string
{
$semEsquema = preg_replace('#^https?://#i', '', $imagemUrl);
return 'https://images.weserv.nl/?url=' . $semEsquema . '&output=jpg';
}
// A API devolve .webp. Se o seu decoder não lê WEBP (TJPegImage não lê), // baixe pelo proxy de conversão, que entrega JPG: function UrlImagemJpg(const AImagemUrl: string): string; var SemEsquema: string; begin SemEsquema := StringReplace(AImagemUrl, 'https://', '', [rfIgnoreCase]); Result := 'https://images.weserv.nl/?url=' + SemEsquema + '&output=jpg'; end; // depois: baixe Result com TIdHTTP e carregue no TJPEGImage normalmente.
curl -o produto.jpg \ "https://images.weserv.nl/?url=global.si5.com.br/img/78/91/7891000325858.webp&output=jpg"
const urlImagemJpg = (imagemUrl) => 'https://images.weserv.nl/?url=' + imagemUrl.replace(/^https?:\/\//i, '') + '&output=jpg';
Erros
A API responde em JSON também nos erros, seguindo o padrão HTTP. Envie Accept: application/json para garantir esse formato.
| Código | Significado | O que fazer |
|---|---|---|
401 |
Unauthenticated. | Token ausente, inválido ou revogado. Confira o cabeçalho Authorization.{"message":"Unauthenticated."} |
404 |
Não encontrado | O código de barras não existe no catálogo (só vale para /api/produtos/{codbar}). |
422 |
Parâmetros inválidos | Algum parâmetro de query está fora do formato esperado. |
429 |
Too Many Requests | A franquia diária de consultas do seu plano foi excedida (100 por dia no plano Grátis). Ela renova à meia-noite (horário de Brasília) — ou mude de plano. |
Boas práticas
- Guarde o resultado. Os dados de um GTIN mudam pouco; salve a resposta no seu banco e só consulte de novo quando precisar atualizar. Economiza a sua franquia diária de consultas.
- Trate o 429. Ao atingir o limite, espere antes de tentar de novo em vez de repetir a chamada em laço.
- Trate o 404. Produto fora do catálogo não é falha: ofereça cadastro manual no seu sistema.
- Use o GTIN como texto. Em Delphi, PHP ou JavaScript, não converta para número — zeros à esquerda são perdidos.
- Aceite
null. Qualquer campo opcional pode vir vazio; valide antes de usar. - Defina timeout. Use um tempo limite de 10–15 segundos nas chamadas para não travar a tela do operador.
- Código pronto. Exemplos em cURL, PHP, Python, Node.js, C# e Delphi, e um script que preenche uma planilha CSV inteira com cache, no repositório do GitHub.
- NCM e CEST sem pontuação. Vêm só com dígitos (8 e 7); formate na exibição, se quiser.
Perguntas frequentes
A API é gratuita?
Sim. O plano Grátis dá 30 consultas por dia e 1 token, sem cartão e sem prazo. Para mais volume e mais tokens há planos pagos — veja os preços.
Os dados fiscais (NCM e CEST) são confiáveis?
O NCM é cruzado com a tabela oficial vigente antes de ser gravado, e o CEST só é preenchido quando o NCM tem correspondência única na tabela oficial. Ainda assim, a classificação final de cada operação é responsabilidade do contribuinte — confirme com seu contador quando houver dúvida.
Por que preco_medio vem sempre nulo?
O catálogo é de identificação do produto e classificação fiscal; não publicamos preço. O campo é mantido apenas para não quebrar integrações existentes.
O produto que preciso não está no catálogo. E agora?
O catálogo cresce todos os dias (veja a evolução em Crescimento). Se o GTIN não existir, a API responde 404; trate o caso no seu sistema.
Posso chamar a API direto do navegador do cliente?
Não é recomendado: o token ficaria exposto a qualquer visitante. Chame a API pelo seu servidor e entregue o resultado ao navegador.
CORS: a aplicação permite origens e cabeçalhos em /api/*. O preflight OPTIONS de /api/produtos foi validado para GET com os cabeçalhos Authorization e Accept. As consultas continuam exigindo token Bearer e respeitando os limites do plano. Não há suporte a cookies de sessão entre origens. Recomendamos integrar pelo servidor para não expor seu token. Outras rotas e proteções podem ter comportamento diferente.
A imagem não aparece no meu sistema.
As imagens são WEBP. Se o seu decoder não lê esse formato, converta pelo proxy descrito na seção Imagens.
Precisa de mais volume ou de um endpoint que ainda não existe? Fale com a gente pelos canais oficiais da SI5 Sistema — o SI5 Global está em desenvolvimento contínuo.