SI5 Global SI5 Global

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:

1

Crie sua conta

Entre gratuitamente com o Google na sua página de conta.

2

Gere um token

Na mesma página, crie um token de API. Guarde-o: ele identifica o seu uso.

3

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
Mantenha o token em segredo

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

GET /api/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âmetroTipoDescrição
qstringCódigo de barras (prefixo) ou termo de busca no nome. Vazio = lista tudo, paginado.
per_pageintegerItens por página. Padrão 20, máximo 100.
pageintegerNú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

GET /api/produtos/{codbar}

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:

CampoTipoDescrição
codbarstringCódigo de barras (GTIN/EAN-8, 12, 13 ou 14). Sempre texto — preserva zeros à esquerda.
produtostringNome/descrição comercial do produto.
marcastring | nullMarca. Pode ser nulo quando não identificada.
categoriastring | nullCategoria do catálogo (ex.: ALIMENTOS, Higiene E Beleza).
ncmstring | nullNCM com 8 dígitos, sem pontos (ex.: 04022110).
cest_codigostring | nullCEST com 7 dígitos, sem pontos (ex.: 1701200). Nulo quando não se aplica ou é ambíguo.
pesostring | nullPeso como texto decimal (ex.: "380.00").
embalagemstring | nullTipo de embalagem, quando informado.
quantidade_embalagemnumber | nullQuantidade de unidades na embalagem, quando informado.
preco_medionullSempre nulo: o catálogo não publica preço. O campo existe só para manter o contrato.
imagem_urlstring | nullURL da foto do produto, em WEBP (veja a seção Imagens).
codigo_barras_urlnullCampo mantido por compatibilidade: agora é sempre null.

Campos adicionais na consulta por código de barras

CampoTipoDescrição
ncm_descricaostring | nullDescrição oficial do NCM, da tabela vigente.
cest_segmentostring | nullSegmento oficial do CEST.
ingredientesstring | nullLista de ingredientes, quando disponível.
alergenosstring | nullAlérgenos declarados, quando disponível.
pode_conterstring | nullAlerta de contaminação cruzada, quando disponível.
porcaostring | nullPorção de referência da tabela nutricional.
nutrientesobject | nullTabela 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.

GET /api/produtos/{codbar}?uf=RJ
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

CampoDescrição
fiscal.ncmNCM do produto na tabela oficial: código, descrição e se está vigente.
fiscal.cestCEST 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.ibptCarga 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.ipiAlíquota do IPI na TIPI vigente e as exceções (EX) do NCM.
fiscal.pis_cofinsRegime de PIS/COFINS (geral, monofásico, alíquota zero...) com CST sugerido e as regras das tabelas da EFD-Contribuições.
fiscal.rtcReforma 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).

Ver planos com ficha fiscal →

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.

⚠ Formato WEBP

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ódigoSignificadoO 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.